vibesketcher.document.solid_reaction_model¶
Solid-state and surface reaction schemes: participants, steps and balances (#192).
A participant is one physical state that takes part in a step: a bulk
phase, a clean or adsorbed slab, an empty surface site *, a surface
vacancy, an adsorbate, a gas or solution species, or an electron. Several
participants may draw on the same periodic structure (structure) or name
the same parent (parent), but every participant has its own ID, so CO*
on a slab and the clean slab it came from never share one.
A step states formula coefficients for its reactants and products. Each step is checked for three conserved quantities:
atoms, element by element, from each participant’s formula;
charge, from each participant’s charge (an electron carries -1);
sites, per site type:
*for an adsorption site, or any named lattice site such asO_site, counted the way Kröger-Vink notation counts them (Kröger and Vink, Solid State Phys. 3, 307 (1956)): a vacancy still occupies its lattice site.
A quantity that does not balance is refused unless the step names an open
reservoir for it: an explicit statement that this quantity is exchanged with
something outside the scheme (O with an O2 gas reservoir, charge with the
electrode at the stated potential, * with a surface of many sites).
Bulk synthesis steps never take a reservoir; they balance or are refused.
Atom maps, lattice-site maps, formula coefficients and coverages are separate fields: a coefficient never implies a coverage, and a site map never implies an atom map. Conditions (facet, temperature, pressures, potential) annotate a step; they state no rate, barrier or equilibrium constant.
This module holds the data model only. The balances are computed in
vibesketcher.document.solid_balance, which the document validator
calls, so a document cannot hold an unbalanced step without a stated
reservoir.
Classes
|
An atom map: atom |
|
An explicit statement that a quantity is exchanged outside the scheme. |
|
|
|
|
|
A lattice-site map: a site of a reactant goes to a site of a product in cell |
|
|
|
One physical state in a solid-state or surface reaction scheme. |
|
One step of a solid-state or surface scheme. |
|
Annotations of a step; none of them implies a rate or a balanced kinetics. |
|
A participant with its formula coefficient in a step. |
- class vibesketcher.document.solid_reaction_model.AtomMapEntry(*, start, to)[source]¶
Bases:
_StrictAn atom map: atom
startof a reactant is atomendof a product.- model_config = {'extra': 'forbid', 'populate_by_name': True, 'validate_assignment': True}¶
Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
- class vibesketcher.document.solid_reaction_model.OpenReservoir(*, quantity, description, participant=None)[source]¶
Bases:
_StrictAn explicit statement that a quantity is exchanged outside the scheme.
- Parameters:
quantity (Annotated[str, StringConstraints(strip_whitespace=None, to_upper=None, to_lower=None, strict=None, min_length=1, max_length=40, pattern=None, ascii_only=None)])
description (Annotated[str, StringConstraints(strip_whitespace=None, to_upper=None, to_lower=None, strict=None, min_length=1, max_length=500, pattern=None, ascii_only=None)])
participant (Annotated[str, StringConstraints(strip_whitespace=None, to_upper=None, to_lower=None, strict=None, min_length=None, max_length=None, pattern=^[A-Za-z][A-Za-z0-9_-]{0,63}$, ascii_only=None)] | None)
- description: _Text¶
- model_config = {'extra': 'forbid', 'populate_by_name': True, 'validate_assignment': True}¶
Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
- class vibesketcher.document.solid_reaction_model.Potential(*, value_v, reference)[source]¶
Bases:
_Strict- Parameters:
- model_config = {'extra': 'forbid', 'populate_by_name': True, 'validate_assignment': True}¶
Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
- class vibesketcher.document.solid_reaction_model.Pressure(*, value, unit, of=None)[source]¶
Bases:
_Strict- Parameters:
- unit: Literal['Pa', 'kPa', 'bar', 'mbar', 'atm', 'Torr']¶
- model_config = {'extra': 'forbid', 'populate_by_name': True, 'validate_assignment': True}¶
Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
- class vibesketcher.document.solid_reaction_model.SiteMapEntry(*, start, to, image=(0, 0, 0))[source]¶
Bases:
_StrictA lattice-site map: a site of a reactant goes to a site of a product in cell
image.For a diffusion hop the image is the lattice translation of the end site relative to the home cell of the start site; it is never inferred.
- model_config = {'extra': 'forbid', 'populate_by_name': True, 'validate_assignment': True}¶
Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
- class vibesketcher.document.solid_reaction_model.SiteRef(*, participant, site)[source]¶
Bases:
_Strict- Parameters:
participant (Annotated[str, StringConstraints(strip_whitespace=None, to_upper=None, to_lower=None, strict=None, min_length=None, max_length=None, pattern=^[A-Za-z][A-Za-z0-9_-]{0,63}$, ascii_only=None)])
site (Annotated[str, StringConstraints(strip_whitespace=None, to_upper=None, to_lower=None, strict=None, min_length=None, max_length=None, pattern=^[A-Za-z][A-Za-z0-9_-]{0,63}$, ascii_only=None)])
- participant: _Identifier¶
- site: _Identifier¶
- model_config = {'extra': 'forbid', 'populate_by_name': True, 'validate_assignment': True}¶
Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
- class vibesketcher.document.solid_reaction_model.SolidParticipant(*, id, kind, label, formula=None, charge=None, sites=None, structure=None, atoms=<factory>, parent=None, species=None, state=None, note=None)[source]¶
Bases:
_StrictOne physical state in a solid-state or surface reaction scheme.
- Parameters:
id (Annotated[str, StringConstraints(strip_whitespace=None, to_upper=None, to_lower=None, strict=None, min_length=None, max_length=None, pattern=^[A-Za-z][A-Za-z0-9_-]{0,63}$, ascii_only=None)])
kind (Literal['bulk_phase', 'slab', 'adsorbed_slab', 'empty_site', 'surface_vacancy', 'adsorbate', 'gas', 'solution', 'electron'])
label (Annotated[str, StringConstraints(strip_whitespace=None, to_upper=None, to_lower=None, strict=None, min_length=1, max_length=500, pattern=None, ascii_only=None)])
charge (int | None)
sites (dict[Annotated[str, StringConstraints(strip_whitespace=None, to_upper=None, to_lower=None, strict=None, min_length=None, max_length=None, pattern=^(\*|[A-Za-z][A-Za-z0-9_()*-]{0,31})$, ascii_only=None)], int] | None)
structure (Annotated[str, StringConstraints(strip_whitespace=None, to_upper=None, to_lower=None, strict=None, min_length=None, max_length=None, pattern=^[A-Za-z][A-Za-z0-9_-]{0,63}$, ascii_only=None)] | None)
atoms (Annotated[list[Annotated[str, StringConstraints(strip_whitespace=None, to_upper=None, to_lower=None, strict=None, min_length=None, max_length=None, pattern=^[A-Za-z][A-Za-z0-9_-]{0,63}$, ascii_only=None)]], MaxLen(max_length=25000)])
parent (Annotated[str, StringConstraints(strip_whitespace=None, to_upper=None, to_lower=None, strict=None, min_length=None, max_length=None, pattern=^[A-Za-z][A-Za-z0-9_-]{0,63}$, ascii_only=None)] | None)
species (Annotated[str, StringConstraints(strip_whitespace=None, to_upper=None, to_lower=None, strict=None, min_length=None, max_length=None, pattern=^[A-Za-z][A-Za-z0-9_-]{0,63}$, ascii_only=None)] | None)
state (Annotated[str, StringConstraints(strip_whitespace=None, to_upper=None, to_lower=None, strict=None, min_length=1, max_length=500, pattern=None, ascii_only=None)] | None)
note (Annotated[str, StringConstraints(strip_whitespace=None, to_upper=None, to_lower=None, strict=None, min_length=1, max_length=500, pattern=None, ascii_only=None)] | None)
- id: _Identifier¶
- kind: ParticipantKind¶
- label: _Text¶
- model_config = {'extra': 'forbid', 'populate_by_name': True, 'validate_assignment': True}¶
Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
- class vibesketcher.document.solid_reaction_model.SolidStep(*, id, kind, reactants, products, arrow='forward', reservoirs=<factory>, conditions=<factory>, coverages=<factory>, site_map=<factory>, atom_map=<factory>, schematic=False, label=None)[source]¶
Bases:
_StrictOne step of a solid-state or surface scheme.
- Parameters:
id (Annotated[str, StringConstraints(strip_whitespace=None, to_upper=None, to_lower=None, strict=None, min_length=None, max_length=None, pattern=^[A-Za-z][A-Za-z0-9_-]{0,63}$, ascii_only=None)])
kind (Literal['adsorption', 'desorption', 'dissociation', 'diffusion', 'surface_transformation', 'bulk_synthesis'])
reactants (Annotated[list[Term], MinLen(min_length=1), MaxLen(max_length=50)])
products (Annotated[list[Term], MinLen(min_length=1), MaxLen(max_length=50)])
arrow (Literal['forward', 'equilibrium'])
reservoirs (Annotated[list[OpenReservoir], MaxLen(max_length=20)])
conditions (StepConditions)
coverages (dict[Annotated[str, StringConstraints(strip_whitespace=None, to_upper=None, to_lower=None, strict=None, min_length=None, max_length=None, pattern=^[A-Za-z][A-Za-z0-9_-]{0,63}$, ascii_only=None)], float])
site_map (Annotated[list[SiteMapEntry], MaxLen(max_length=1000)])
atom_map (Annotated[list[AtomMapEntry], MaxLen(max_length=25000)])
schematic (bool)
label (Annotated[str, StringConstraints(strip_whitespace=None, to_upper=None, to_lower=None, strict=None, min_length=1, max_length=500, pattern=None, ascii_only=None)] | None)
- id: _Identifier¶
- kind: StepKind¶
- arrow: Literal['forward', 'equilibrium']¶
- reservoirs: list[OpenReservoir]¶
- conditions: StepConditions¶
- site_map: list[SiteMapEntry]¶
- atom_map: list[AtomMapEntry]¶
- model_config = {'extra': 'forbid', 'populate_by_name': True, 'validate_assignment': True}¶
Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
- class vibesketcher.document.solid_reaction_model.StepConditions(*, facet=None, temperature_k=None, pressures=<factory>, potential=None, notes=<factory>)[source]¶
Bases:
_StrictAnnotations of a step; none of them implies a rate or a balanced kinetics.
- Parameters:
facet (Annotated[str, StringConstraints(strip_whitespace=None, to_upper=None, to_lower=None, strict=None, min_length=1, max_length=40, pattern=None, ascii_only=None)] | None)
temperature_k (Annotated[float | None, Gt(gt=0), Le(le=100000.0), AllowInfNan(allow_inf_nan=False)])
pressures (Annotated[list[Pressure], MaxLen(max_length=20)])
potential (Potential | None)
notes (Annotated[list[Annotated[str, StringConstraints(strip_whitespace=None, to_upper=None, to_lower=None, strict=None, min_length=1, max_length=500, pattern=None, ascii_only=None)]], MaxLen(max_length=20)])
- model_config = {'extra': 'forbid', 'populate_by_name': True, 'validate_assignment': True}¶
Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
- class vibesketcher.document.solid_reaction_model.Term(*, participant, coefficient=1)[source]¶
Bases:
_StrictA participant with its formula coefficient in a step.
- Parameters:
- participant: _Identifier¶
- model_config = {'extra': 'forbid', 'populate_by_name': True, 'validate_assignment': True}¶
Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].