vibe-sketcherDocumentation

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 as O_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

AtomMapEntry(*, start, to)

An atom map: atom start of a reactant is atom end of a product.

OpenReservoir(*, quantity, description[, ...])

An explicit statement that a quantity is exchanged outside the scheme.

Potential(*, value_v, reference)

Pressure(*, value, unit[, of])

SiteMapEntry(*, start, to[, image])

A lattice-site map: a site of a reactant goes to a site of a product in cell image.

SiteRef(*, participant, site)

SolidParticipant(*, id, kind, label[, ...])

One physical state in a solid-state or surface reaction scheme.

SolidStep(*, id, kind, reactants, products)

One step of a solid-state or surface scheme.

StepConditions(*[, facet, temperature_k, ...])

Annotations of a step; none of them implies a rate or a balanced kinetics.

Term(*, participant[, coefficient])

A participant with its formula coefficient in a step.

class vibesketcher.document.solid_reaction_model.AtomMapEntry(*, start, to)[source]

Bases: _Strict

An atom map: atom start of a reactant is atom end of a product.

Parameters:
start: SiteRef
end: SiteRef
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: _Strict

An 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)

quantity: Annotated[str, StringConstraints(min_length=1, max_length=40)]
description: _Text
participant: _Identifier | None
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:
  • value_v (Annotated[float, AllowInfNan(allow_inf_nan=False)])

  • reference (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)])

value_v: float
reference: Annotated[str, StringConstraints(min_length=1, max_length=40)]
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:
  • value (Annotated[float, Gt(gt=0), AllowInfNan(allow_inf_nan=False)])

  • unit (Literal['Pa', 'kPa', 'bar', 'mbar', 'atm', 'Torr'])

  • of (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)

value: float
unit: Literal['Pa', 'kPa', 'bar', 'mbar', 'atm', 'Torr']
of: _Text | None
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: _Strict

A 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.

Parameters:
start: SiteRef
end: SiteRef
image: tuple[int, int, int]
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: _Strict

One 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)])

  • formula (dict[str, int] | 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
formula: dict[str, int] | None
charge: int | None
sites: dict[_SiteType, int] | None
structure: _Identifier | None
atoms: list[_Identifier]
parent: _Identifier | None
species: _Identifier | None
state: _Text | None
note: _Text | None
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: _Strict

One 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
reactants: list[Term]
products: list[Term]
arrow: Literal['forward', 'equilibrium']
reservoirs: list[OpenReservoir]
conditions: StepConditions
coverages: dict[_Identifier, float]
site_map: list[SiteMapEntry]
atom_map: list[AtomMapEntry]
schematic: bool
label: _Text | None
participant_ids()[source]
Return type:

list[str]

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: _Strict

Annotations 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)])

facet: Annotated[str, StringConstraints(min_length=1, max_length=40)] | None
temperature_k: float | None
pressures: list[Pressure]
potential: Potential | None
notes: list[_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.Term(*, participant, coefficient=1)[source]

Bases: _Strict

A participant with its formula coefficient in a step.

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)])

  • coefficient (Annotated[float, Gt(gt=0), Le(le=1000), AllowInfNan(allow_inf_nan=False)])

participant: _Identifier
coefficient: float
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].