Search Settings

---
name: search-settings
description: Use this when configuring OpenForage search defaults, choosing genetic versus random_weighted, setting n_jobs, or writing a settings.yaml file for search runs.
---

# Search Settings

`openforage.search_settings` is the canonical settings module for library search defaults. Use `~/.openforage/settings.yaml` when a run needs explicit, reviewable knobs; run `openforage init` to create and merge it before registration or startup.

## Defaults

- `default_algorithm`: `genetic`
- `n_jobs`: all cores from the current CPU count
- `batch_size`: `100`
- per-candidate process timeout: fixed internal `300` seconds
- `process_priority`: `normal`
- `process_worker_memory_gib`: `4.0`
- `restart_threshold`: no-improvement window before fresh diversity injection
- `elite_fraction`: fraction of structurally distinct prior candidates used for breeding
- `diversity_weight`: penalty strength for redundant, high-correlation candidates
- `parsimony_weight`: penalty strength for larger expression trees
- `operator_rates`: relative rates for `crossover`, `point_mutation`, `subtree_mutation`, and `hoist_mutation`

`random_weighted` remains explicitly selectable by CLI, Python API, or settings file:

```yaml
default_algorithm: random_weighted
```

## Settings File

Create the file with `openforage init`, then edit `~/.openforage/settings.yaml` or pass another path explicitly through the Python API:

```python
import openforage

handle = openforage.search(settings_path="~/.openforage/settings.yaml")
```

Example:

```yaml
default_algorithm: genetic
n_jobs: 2
batch_size: 100
process_priority: normal
process_worker_memory_gib: 4.0
restart_threshold: 5
elite_fraction: 0.20
diversity_weight: 1.50
parsimony_weight: 0.05
operator_rates:
  crossover: 0.45
  point_mutation: 0.25
  subtree_mutation: 0.20
  hoist_mutation: 0.10
```

## Safety Rules

Malformed YAML, unknown keys, invalid algorithms, non-positive `n_jobs`, non-positive `batch_size`, invalid `process_priority`, non-positive `process_worker_memory_gib`, non-positive `restart_threshold`, invalid `elite_fraction`, negative weights, and empty `operator_rates` fail loudly with `SearchSettingsError`.

No seed is written to newly generated settings files. Ordinary runs generate and record a fresh internal run seed each time. Any stale `seed` key in an old settings file is removed by `openforage init` and rejected by strict settings loading.

Use a smaller `n_jobs` only when memory, CPU contention, or a test needs a bounded run. Set `process_worker_memory_gib` to the estimated memory per per-candidate child process; it caps child evaluator process count but does not lower public search `n_jobs`. Set `process_priority` to `normal`, `below_normal`, or `idle`; the default `normal` is a no-op that preserves current worker behavior. Lower priority values apply only to per-candidate multiprocessing worker children and fail loud on unsupported hosts or permission errors, with no fallback to `normal`. The public values are portable, but the current candidate multiprocessing evaluator remains fork-only and does not add Windows candidate multiprocessing support. Genetic search is designed to keep running until stopped; worker/process failures are recorded and dead workers are cleaned up or replaced. The default worker count is all cores.