# {py:mod}`airsspy.search`

```{py:module} airsspy.search
```

```{autodoc2-docstring} airsspy.search
:allowtitles:
```

## Module Contents

### Classes

````{list-table}
:class: autosummary longtable
:align: left

* - {py:obj}`FormulaSamplingOptions <airsspy.search.FormulaSamplingOptions>`
  - ```{autodoc2-docstring} airsspy.search.FormulaSamplingOptions
    :summary:
    ```
* - {py:obj}`FormulaSamplingContext <airsspy.search.FormulaSamplingContext>`
  - ```{autodoc2-docstring} airsspy.search.FormulaSamplingContext
    :summary:
    ```
* - {py:obj}`RssPruneOptions <airsspy.search.RssPruneOptions>`
  - ```{autodoc2-docstring} airsspy.search.RssPruneOptions
    :summary:
    ```
* - {py:obj}`RssCandidate <airsspy.search.RssCandidate>`
  - ```{autodoc2-docstring} airsspy.search.RssCandidate
    :summary:
    ```
````

### Functions

````{list-table}
:class: autosummary longtable
:align: left

* - {py:obj}`canonicalize_formula <airsspy.search.canonicalize_formula>`
  - ```{autodoc2-docstring} airsspy.search.canonicalize_formula
    :summary:
    ```
* - {py:obj}`inject_formula_directive <airsspy.search.inject_formula_directive>`
  - ```{autodoc2-docstring} airsspy.search.inject_formula_directive
    :summary:
    ```
* - {py:obj}`build_formula_sampling_context <airsspy.search.build_formula_sampling_context>`
  - ```{autodoc2-docstring} airsspy.search.build_formula_sampling_context
    :summary:
    ```
* - {py:obj}`make_seed_text_transform <airsspy.search.make_seed_text_transform>`
  - ```{autodoc2-docstring} airsspy.search.make_seed_text_transform
    :summary:
    ```
* - {py:obj}`parse_key_float <airsspy.search.parse_key_float>`
  - ```{autodoc2-docstring} airsspy.search.parse_key_float
    :summary:
    ```
* - {py:obj}`parse_key_ints <airsspy.search.parse_key_ints>`
  - ```{autodoc2-docstring} airsspy.search.parse_key_ints
    :summary:
    ```
* - {py:obj}`validate_prune_options <airsspy.search.validate_prune_options>`
  - ```{autodoc2-docstring} airsspy.search.validate_prune_options
    :summary:
    ```
* - {py:obj}`pool_statistics <airsspy.search.pool_statistics>`
  - ```{autodoc2-docstring} airsspy.search.pool_statistics
    :summary:
    ```
* - {py:obj}`should_flush_prune_pool <airsspy.search.should_flush_prune_pool>`
  - ```{autodoc2-docstring} airsspy.search.should_flush_prune_pool
    :summary:
    ```
* - {py:obj}`select_pruned_candidates <airsspy.search.select_pruned_candidates>`
  - ```{autodoc2-docstring} airsspy.search.select_pruned_candidates
    :summary:
    ```
* - {py:obj}`prune_relaxed_pool <airsspy.search.prune_relaxed_pool>`
  - ```{autodoc2-docstring} airsspy.search.prune_relaxed_pool
    :summary:
    ```
* - {py:obj}`candidate_from_res <airsspy.search.candidate_from_res>`
  - ```{autodoc2-docstring} airsspy.search.candidate_from_res
    :summary:
    ```
````

### Data

````{list-table}
:class: autosummary longtable
:align: left

* - {py:obj}`DEFAULT_FORMULA_REMOVE_DIRECTIVES <airsspy.search.DEFAULT_FORMULA_REMOVE_DIRECTIVES>`
  - ```{autodoc2-docstring} airsspy.search.DEFAULT_FORMULA_REMOVE_DIRECTIVES
    :summary:
    ```
````

### API

````{py:data} DEFAULT_FORMULA_REMOVE_DIRECTIVES
:canonical: airsspy.search.DEFAULT_FORMULA_REMOVE_DIRECTIVES
:value: >
   ('NATOM', 'SPECIES', 'FORMULA', 'VARVOL', 'TARGVOL')

```{autodoc2-docstring} airsspy.search.DEFAULT_FORMULA_REMOVE_DIRECTIVES
```

````

`````{py:class} FormulaSamplingOptions
:canonical: airsspy.search.FormulaSamplingOptions

```{autodoc2-docstring} airsspy.search.FormulaSamplingOptions
```

````{py:attribute} formulas
:canonical: airsspy.search.FormulaSamplingOptions.formulas
:type: collections.abc.Sequence[str]
:value: >
   ()

```{autodoc2-docstring} airsspy.search.FormulaSamplingOptions.formulas
```

````

````{py:attribute} elements
:canonical: airsspy.search.FormulaSamplingOptions.elements
:type: collections.abc.Sequence[str]
:value: >
   ()

```{autodoc2-docstring} airsspy.search.FormulaSamplingOptions.elements
```

````

````{py:attribute} max_coeff
:canonical: airsspy.search.FormulaSamplingOptions.max_coeff
:type: int
:value: >
   6

```{autodoc2-docstring} airsspy.search.FormulaSamplingOptions.max_coeff
```

````

````{py:attribute} target_atom_volumes
:canonical: airsspy.search.FormulaSamplingOptions.target_atom_volumes
:type: dict[str, float]
:value: >
   'field(...)'

```{autodoc2-docstring} airsspy.search.FormulaSamplingOptions.target_atom_volumes
```

````

````{py:attribute} oxidation_states
:canonical: airsspy.search.FormulaSamplingOptions.oxidation_states
:type: dict[str, collections.abc.Sequence[int]]
:value: >
   'field(...)'

```{autodoc2-docstring} airsspy.search.FormulaSamplingOptions.oxidation_states
```

````

````{py:attribute} require_charge_neutral
:canonical: airsspy.search.FormulaSamplingOptions.require_charge_neutral
:type: bool
:value: >
   True

```{autodoc2-docstring} airsspy.search.FormulaSamplingOptions.require_charge_neutral
```

````

````{py:attribute} remove_directives
:canonical: airsspy.search.FormulaSamplingOptions.remove_directives
:type: collections.abc.Sequence[str]
:value: >
   None

```{autodoc2-docstring} airsspy.search.FormulaSamplingOptions.remove_directives
```

````

`````

`````{py:class} FormulaSamplingContext
:canonical: airsspy.search.FormulaSamplingContext

```{autodoc2-docstring} airsspy.search.FormulaSamplingContext
```

````{py:attribute} formulas
:canonical: airsspy.search.FormulaSamplingContext.formulas
:type: list[str]
:value: >
   None

```{autodoc2-docstring} airsspy.search.FormulaSamplingContext.formulas
```

````

````{py:attribute} remove_directives
:canonical: airsspy.search.FormulaSamplingContext.remove_directives
:type: tuple[str, ...]
:value: >
   None

```{autodoc2-docstring} airsspy.search.FormulaSamplingContext.remove_directives
```

````

````{py:attribute} varvol_by_formula
:canonical: airsspy.search.FormulaSamplingContext.varvol_by_formula
:type: dict[str, float]
:value: >
   'field(...)'

```{autodoc2-docstring} airsspy.search.FormulaSamplingContext.varvol_by_formula
```

````

````{py:method} sample(seed_text: str, rng: random.Random | None = None) -> tuple[str, str, float | None]
:canonical: airsspy.search.FormulaSamplingContext.sample

```{autodoc2-docstring} airsspy.search.FormulaSamplingContext.sample
```

````

`````

`````{py:class} RssPruneOptions
:canonical: airsspy.search.RssPruneOptions

```{autodoc2-docstring} airsspy.search.RssPruneOptions
```

````{py:attribute} enabled
:canonical: airsspy.search.RssPruneOptions.enabled
:type: bool
:value: >
   False

```{autodoc2-docstring} airsspy.search.RssPruneOptions.enabled
```

````

````{py:attribute} pool_size
:canonical: airsspy.search.RssPruneOptions.pool_size
:type: int
:value: >
   100

```{autodoc2-docstring} airsspy.search.RssPruneOptions.pool_size
```

````

````{py:attribute} keep_fraction
:canonical: airsspy.search.RssPruneOptions.keep_fraction
:type: float
:value: >
   0.1

```{autodoc2-docstring} airsspy.search.RssPruneOptions.keep_fraction
```

````

````{py:attribute} dedup_tol
:canonical: airsspy.search.RssPruneOptions.dedup_tol
:type: float
:value: >
   0.1

```{autodoc2-docstring} airsspy.search.RssPruneOptions.dedup_tol
```

````

````{py:attribute} fingerprint_cutoff
:canonical: airsspy.search.RssPruneOptions.fingerprint_cutoff
:type: float
:value: >
   5.0

```{autodoc2-docstring} airsspy.search.RssPruneOptions.fingerprint_cutoff
```

````

````{py:attribute} min_stable_pool_size
:canonical: airsspy.search.RssPruneOptions.min_stable_pool_size
:type: int
:value: >
   50

```{autodoc2-docstring} airsspy.search.RssPruneOptions.min_stable_pool_size
```

````

````{py:attribute} stable_window
:canonical: airsspy.search.RssPruneOptions.stable_window
:type: int
:value: >
   20

```{autodoc2-docstring} airsspy.search.RssPruneOptions.stable_window
```

````

````{py:attribute} mean_abs_tol
:canonical: airsspy.search.RssPruneOptions.mean_abs_tol
:type: float
:value: >
   0.001

```{autodoc2-docstring} airsspy.search.RssPruneOptions.mean_abs_tol
```

````

````{py:attribute} median_abs_tol
:canonical: airsspy.search.RssPruneOptions.median_abs_tol
:type: float
:value: >
   0.001

```{autodoc2-docstring} airsspy.search.RssPruneOptions.median_abs_tol
```

````

````{py:attribute} zweight
:canonical: airsspy.search.RssPruneOptions.zweight
:type: bool
:value: >
   False

```{autodoc2-docstring} airsspy.search.RssPruneOptions.zweight
```

````

`````

`````{py:class} RssCandidate
:canonical: airsspy.search.RssCandidate

```{autodoc2-docstring} airsspy.search.RssCandidate
```

````{py:attribute} label
:canonical: airsspy.search.RssCandidate.label
:type: str
:value: >
   None

```{autodoc2-docstring} airsspy.search.RssCandidate.label
```

````

````{py:attribute} energy
:canonical: airsspy.search.RssCandidate.energy
:type: float
:value: >
   None

```{autodoc2-docstring} airsspy.search.RssCandidate.energy
```

````

````{py:attribute} atoms
:canonical: airsspy.search.RssCandidate.atoms
:type: ase.Atoms | None
:value: >
   None

```{autodoc2-docstring} airsspy.search.RssCandidate.atoms
```

````

````{py:attribute} res_path
:canonical: airsspy.search.RssCandidate.res_path
:type: pathlib.Path | None
:value: >
   None

```{autodoc2-docstring} airsspy.search.RssCandidate.res_path
```

````

````{py:attribute} record
:canonical: airsspy.search.RssCandidate.record
:type: airsspy.ranking.StructureRecord | None
:value: >
   None

```{autodoc2-docstring} airsspy.search.RssCandidate.record
```

````

````{py:attribute} source
:canonical: airsspy.search.RssCandidate.source
:type: typing.Any
:value: >
   None

```{autodoc2-docstring} airsspy.search.RssCandidate.source
```

````

````{py:property} natoms
:canonical: airsspy.search.RssCandidate.natoms
:type: int

```{autodoc2-docstring} airsspy.search.RssCandidate.natoms
```

````

````{py:property} energy_per_atom
:canonical: airsspy.search.RssCandidate.energy_per_atom
:type: float

```{autodoc2-docstring} airsspy.search.RssCandidate.energy_per_atom
```

````

````{py:property} reduced_formula
:canonical: airsspy.search.RssCandidate.reduced_formula
:type: str

```{autodoc2-docstring} airsspy.search.RssCandidate.reduced_formula
```

````

`````

````{py:function} canonicalize_formula(formula: str) -> str
:canonical: airsspy.search.canonicalize_formula

```{autodoc2-docstring} airsspy.search.canonicalize_formula
```
````

````{py:function} inject_formula_directive(seed_text: str, formula: str, varvol: float | None = None, remove_directives: collections.abc.Sequence[str] = DEFAULT_FORMULA_REMOVE_DIRECTIVES) -> str
:canonical: airsspy.search.inject_formula_directive

```{autodoc2-docstring} airsspy.search.inject_formula_directive
```
````

````{py:function} build_formula_sampling_context(options: airsspy.search.FormulaSamplingOptions, seed_text: str | None = None) -> airsspy.search.FormulaSamplingContext
:canonical: airsspy.search.build_formula_sampling_context

```{autodoc2-docstring} airsspy.search.build_formula_sampling_context
```
````

````{py:function} make_seed_text_transform(context: airsspy.search.FormulaSamplingContext, rng: random.Random | None = None) -> collections.abc.Callable[[str], str]
:canonical: airsspy.search.make_seed_text_transform

```{autodoc2-docstring} airsspy.search.make_seed_text_transform
```
````

````{py:function} parse_key_float(text: str) -> tuple[str, float]
:canonical: airsspy.search.parse_key_float

```{autodoc2-docstring} airsspy.search.parse_key_float
```
````

````{py:function} parse_key_ints(text: str) -> tuple[str, list[int]]
:canonical: airsspy.search.parse_key_ints

```{autodoc2-docstring} airsspy.search.parse_key_ints
```
````

````{py:function} validate_prune_options(options: airsspy.search.RssPruneOptions) -> airsspy.search.RssPruneOptions
:canonical: airsspy.search.validate_prune_options

```{autodoc2-docstring} airsspy.search.validate_prune_options
```
````

````{py:function} pool_statistics(candidates: collections.abc.Sequence[airsspy.search.RssCandidate]) -> dict[str, float]
:canonical: airsspy.search.pool_statistics

```{autodoc2-docstring} airsspy.search.pool_statistics
```
````

````{py:function} should_flush_prune_pool(candidates: collections.abc.Sequence[airsspy.search.RssCandidate], stats_history: collections.abc.Sequence[dict[str, float]], options: airsspy.search.RssPruneOptions) -> tuple[str, bool]
:canonical: airsspy.search.should_flush_prune_pool

```{autodoc2-docstring} airsspy.search.should_flush_prune_pool
```
````

````{py:function} select_pruned_candidates(candidates: collections.abc.Sequence[airsspy.search.RssCandidate], options: airsspy.search.RssPruneOptions, remaining: int | None = None) -> tuple[list[airsspy.search.RssCandidate], list[airsspy.search.RssCandidate]]
:canonical: airsspy.search.select_pruned_candidates

```{autodoc2-docstring} airsspy.search.select_pruned_candidates
```
````

````{py:function} prune_relaxed_pool(candidates: collections.abc.Sequence[airsspy.search.RssCandidate], options: airsspy.search.RssPruneOptions, remaining: int | None = None) -> list[airsspy.search.RssCandidate]
:canonical: airsspy.search.prune_relaxed_pool

```{autodoc2-docstring} airsspy.search.prune_relaxed_pool
```
````

````{py:function} candidate_from_res(path: str | pathlib.Path) -> airsspy.search.RssCandidate
:canonical: airsspy.search.candidate_from_res

```{autodoc2-docstring} airsspy.search.candidate_from_res
```
````