`airsspy.search`#

Reusable helpers for AIRSS search workflows.

Module Contents#

Classes#

`FormulaSamplingOptions`	Options for sampling buildcell `#FORMULA` directives.
`FormulaSamplingContext`	Precomputed state for formula sampling.
`RssPruneOptions`	Options for pruning relaxed RSS candidates before final output.
`RssCandidate`	A relaxed structure considered for pruning.

Functions#

`canonicalize_formula`	Return pymatgen’s canonical reduced formula string.
`inject_formula_directive`	Inject `#FORMULA` and optional `#VARVOL` directives into seed text.
`build_formula_sampling_context`	Build a formula sampling context from user options.
`make_seed_text_transform`	Return a callable that rewrites seed text for one sampled formula.
`parse_key_float`	Parse `KEY=value` into a string key and float value.
`parse_key_ints`	Parse `KEY=a,b` into a string key and list of integers.
`validate_prune_options`	Validate pruning options and return options for convenient chaining.
`pool_statistics`	Return mean and median energy-per-atom statistics for a candidate pool.
`should_flush_prune_pool`	Return `(reason, should_flush)` for a pruning pool.
`select_pruned_candidates`	Select low-energy unique candidates and return `(kept, rejected)`.
`prune_relaxed_pool`	Return the candidates kept after post-relax pruning.
`candidate_from_res`	Create a pruning candidate from an AIRSS `.res` file.

Data#

DEFAULT_FORMULA_REMOVE_DIRECTIVES

API#

airsspy.search.DEFAULT_FORMULA_REMOVE_DIRECTIVES#: (‘NATOM’, ‘SPECIES’, ‘FORMULA’, ‘VARVOL’, ‘TARGVOL’)

class airsspy.search.FormulaSamplingOptions[source]#

Options for sampling buildcell #FORMULA directives.

formulas: collections.abc.Sequence[str]#: ()

elements: collections.abc.Sequence[str]#: ()

max_coeff: int#: 6

target_atom_volumes: dict[str, float]#: ‘field(…)’

oxidation_states: dict[str, collections.abc.Sequence[int]]#: ‘field(…)’

require_charge_neutral: bool#: True

remove_directives: collections.abc.Sequence[str]#: None

class airsspy.search.FormulaSamplingContext[source]#

Precomputed state for formula sampling.

formulas: list[str]#: None

remove_directives: tuple[str, ...]#: None

varvol_by_formula: dict[str, float]#: ‘field(…)’

sample(seed_text: str, rng: random.Random | None = None) → tuple[str, str, float | None][source]#: Return (new_seed_text, formula, varvol) for one sampled formula.

class airsspy.search.RssPruneOptions[source]#

Options for pruning relaxed RSS candidates before final output.

enabled: bool#: False

pool_size: int#: 100

keep_fraction: float#: 0.1

dedup_tol: float#: 0.1

fingerprint_cutoff: float#: 5.0

min_stable_pool_size: int#: 50

stable_window: int#: 20

mean_abs_tol: float#: 0.001

median_abs_tol: float#: 0.001

zweight: bool#: False

class airsspy.search.RssCandidate[source]#

A relaxed structure considered for pruning.

label: str#: None

energy: float#: None

atoms: ase.Atoms | None#: None

res_path: pathlib.Path | None#: None

record: airsspy.ranking.StructureRecord | None#: None

source: Any#: None

property natoms: int#: Number of atoms in this candidate.

property energy_per_atom: float#: Energy or enthalpy per atom.

property reduced_formula: str#: Reduced formula for the candidate.

airsspy.search.canonicalize_formula(formula: str) → str[source]#: Return pymatgen’s canonical reduced formula string.

airsspy.search.inject_formula_directive(seed_text: str, formula: str, varvol: float | None = None, remove_directives: collections.abc.Sequence[str] = DEFAULT_FORMULA_REMOVE_DIRECTIVES) → str[source]#: Inject #FORMULA and optional #VARVOL directives into seed text.

airsspy.search.build_formula_sampling_context(options: airsspy.search.FormulaSamplingOptions, seed_text: str | None = None) → airsspy.search.FormulaSamplingContext[source]#: Build a formula sampling context from user options.

airsspy.search.make_seed_text_transform(context: airsspy.search.FormulaSamplingContext, rng: random.Random | None = None) → collections.abc.Callable[[str], str][source]#: Return a callable that rewrites seed text for one sampled formula.

airsspy.search.parse_key_float(text: str) → tuple[str, float][source]#: Parse KEY=value into a string key and float value.

airsspy.search.parse_key_ints(text: str) → tuple[str, list[int]][source]#: Parse KEY=a,b into a string key and list of integers.

airsspy.search.validate_prune_options(options: airsspy.search.RssPruneOptions) → airsspy.search.RssPruneOptions[source]#: Validate pruning options and return options for convenient chaining.

airsspy.search.pool_statistics(candidates: collections.abc.Sequence[airsspy.search.RssCandidate]) → dict[str, float][source]#: Return mean and median energy-per-atom statistics for a candidate pool.

airsspy.search.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][source]#: Return (reason, should_flush) for a pruning pool.

airsspy.search.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]][source]#: Select low-energy unique candidates and return (kept, rejected).

airsspy.search.prune_relaxed_pool(candidates: collections.abc.Sequence[airsspy.search.RssCandidate], options: airsspy.search.RssPruneOptions, remaining: int | None = None) → list[airsspy.search.RssCandidate][source]#: Return the candidates kept after post-relax pruning.

airsspy.search.candidate_from_res(path: str | pathlib.Path) → airsspy.search.RssCandidate[source]#: Create a pruning candidate from an AIRSS .res file.

airsspy.search#