httk.atomistic.models.formula.notation

The one home of httk’s reduced/anonymous formula notation.

Functions

anonymous_symbol(index)	Return the unbounded OPTIMADE anonymous symbol for a zero-based index.
reduced_coefficients(ratios)	Return the least common integer coefficients for exact elemental ratios.
render_reduced(coefficients)	Render element symbols and reduced integer coefficients in the given order.
render_anonymous(counts)	Render descending-sorted integer counts using OPTIMADE anonymous symbols.
parse_reduced_formula(text)	Parse a strictly canonical reduced OPTIMADE chemical formula.
parse_anonymous_formula(text)	Parse a strictly canonical OPTIMADE anonymous chemical formula.
try_parse_reduced(text)	Return canonical reduced coefficients, or None when text is not one.
try_parse_anonymous(text)	Return canonical anonymous coefficients, or None when text is not one.

Module Contents

httk.atomistic.models.formula.notation.anonymous_symbol(index)

Return the unbounded OPTIMADE anonymous symbol for a zero-based index.

Parameters:

index (int) – The non-negative zero-based symbol index.

Returns:

The generated anonymous symbol.

Raises:

ValueError – If index is not a non-negative integer.

Return type:

str

httk.atomistic.models.formula.notation.reduced_coefficients(ratios)

Return the least common integer coefficients for exact elemental ratios.

Parameters:

ratios (collections.abc.Sequence[fractions.Fraction]) – The exact elemental ratios in their desired output order.

Returns:

The reduced integer coefficients, or None for an empty sequence.

Return type:

tuple[int, Ellipsis] | None

httk.atomistic.models.formula.notation.render_reduced(coefficients)

Render element symbols and reduced integer coefficients in the given order.

Parameters:

coefficients (collections.abc.Sequence[tuple[str, int]]) – The element and coefficient pairs to render.

Returns:

The canonical reduced formula text.

Return type:

str

httk.atomistic.models.formula.notation.render_anonymous(counts)

Render descending-sorted integer counts using OPTIMADE anonymous symbols.

Parameters:

counts (collections.abc.Sequence[int]) – The coefficients in descending order.

Returns:

The canonical anonymous formula text.

Return type:

str

httk.atomistic.models.formula.notation.parse_reduced_formula(text)

Parse a strictly canonical reduced OPTIMADE chemical formula.

The reduced and anonymous grammars are disjoint by construction: an anonymous label may have an arbitrary lowercase tail, while an element symbol has at most one.

Parameters:

text (str) – The formula text to parse.

Returns:

The canonical element and coefficient pairs.

Raises:

ValueError – If text is not a canonical reduced formula.

Return type:

tuple[tuple[str, int], Ellipsis]

httk.atomistic.models.formula.notation.parse_anonymous_formula(text)

Parse a strictly canonical OPTIMADE anonymous chemical formula.

Parameters:

text (str) – The formula text to parse.

Returns:

The canonical anonymous-label and coefficient pairs.

Raises:

ValueError – If text is not a canonical anonymous formula.

Return type:

tuple[tuple[str, int], Ellipsis]

httk.atomistic.models.formula.notation.try_parse_reduced(text)

Return canonical reduced coefficients, or None when text is not one.

Parameters:

text (str) – The formula text to test.

Returns:

The parsed coefficients, or None for invalid text.

Return type:

tuple[tuple[str, int], Ellipsis] | None

httk.atomistic.models.formula.notation.try_parse_anonymous(text)

Return canonical anonymous coefficients, or None when text is not one.

Parameters:

text (str) – The formula text to test.

Returns:

The parsed coefficients, or None for invalid text.

Return type:

tuple[tuple[str, int], Ellipsis] | None