dcclib.extraction.formulae

DCCFunction dataclass 

DCCFunction(name: str, expression: str | Expr, variables: dict[str, Value], bound_variables: set[str])

Bases: Generic[T]

Represents a named, parameterised DCC formula.

combinations property 

combinations: list[Any]

Return one lambdified function per evaluation step (one per combination index).

The number of entries matches the number of results "evaluate()" would return.

FormulaExtractor 

FormulaExtractor(element: etree.Element)

Bases: Constructible, Extractable

extract 

extract() -> list[DCCFunction[DccQuantityType]]

Extract formulas from the XML.

Returns:
  • list[DCCFunction[DccQuantityType]] –

    a list of DCCFunction objects

from_file classmethod 

from_file(path: str)

Create a FormulaExtractor from a file path.

Parameters:
  • path (str) –

    the path to the file
Returns:
  • –

    the FormulaExtractor

from_str classmethod 

from_str(xml: str)

Create a FormulaExtractor from a string.

Parameters:
  • xml (str) –

    the XML string
Returns:
  • –

    the FormulaExtractor

from_tree classmethod 

from_tree(tree: etree.Element)

Create a FormulaExtractor from an ElementTree.

Parameters:
  • tree (etree.Element) –

    the ElementTree
Returns:
  • –

    the FormulaExtractor

format_quantity 

format_quantity(value: Any) -> tuple[str, str]

Return (value_str, unit_str) for a DccQuantityType or plain value.

quantity_fields 

quantity_fields(value: Any) -> dict[str, Any]

Return machine-readable fields for a DccQuantityType or plain value.

Keys: values (list of floats), unit (str or None), and uncertainties (list of floats or None). Scalars are returned as single-element lists so consumers can treat all quantities uniformly.

wrap_variable_value 

wrap_variable_value(raw_value: float | list[float], original_var: Any) -> Any

Wrap a user-provided value in a DccQuantityType, inheriting the unit from the original formula variable so that unit-aware arithmetic stays consistent. Returns a plain float when the original variable has no unit information.

formula

DCCFunction dataclass 

DCCFunction(name: str, expression: str | Expr, variables: dict[str, Value], bound_variables: set[str])

Bases: Generic[T]

Represents a named, parameterised DCC formula.

combinations property 

combinations: list[Any]

Return one lambdified function per evaluation step (one per combination index).

The number of entries matches the number of results "evaluate()" would return.

format_quantity 

format_quantity(value: Any) -> tuple[str, str]

Return (value_str, unit_str) for a DccQuantityType or plain value.

quantity_fields 

quantity_fields(value: Any) -> dict[str, Any]

Return machine-readable fields for a DccQuantityType or plain value.

Keys: values (list of floats), unit (str or None), and uncertainties (list of floats or None). Scalars are returned as single-element lists so consumers can treat all quantities uniformly.

sub_len 

sub_len(values: list[Value]) -> int

Return the common length of all multi-value items in values.

Scalars (len == 1) are compatible with any length. Raises "ValueError" on empty sublists or mismatched lengths.

wrap_variable_value 

wrap_variable_value(raw_value: float | list[float], original_var: Any) -> Any

Wrap a user-provided value in a DccQuantityType, inheriting the unit from the original formula variable so that unit-aware arithmetic stays consistent. Returns a plain float when the original variable has no unit information.

formula_extractor

FormulaExtractor 

FormulaExtractor(element: etree.Element)

Bases: Constructible, Extractable

extract 

extract() -> list[DCCFunction[DccQuantityType]]

Extract formulas from the XML.

Returns:
  • list[DCCFunction[DccQuantityType]] –

    a list of DCCFunction objects

from_file classmethod 

from_file(path: str)

Create a FormulaExtractor from a file path.

Parameters:
  • path (str) –

    the path to the file
Returns:
  • –

    the FormulaExtractor

from_str classmethod 

from_str(xml: str)

Create a FormulaExtractor from a string.

Parameters:
  • xml (str) –

    the XML string
Returns:
  • –

    the FormulaExtractor

from_tree classmethod 

from_tree(tree: etree.Element)

Create a FormulaExtractor from an ElementTree.

Parameters:
  • tree (etree.Element) –

    the ElementTree
Returns:
  • –

    the FormulaExtractor

mathml_sympy_converter

convert_mathml_apply 

convert_mathml_apply(apply: etree.Element) -> sympy.Expr

Recursively evaluate a MathML 'apply' node into a SymPy expression.

It parses the operands and arguments, handling special MathML tags like 'bvar', 'lowlimit', 'uplimit', 'logbase', and 'degree' by passing them as keyword arguments to the mapped SymPy operation.

Parameters:
  • apply (etree.Element) –

    The MathML 'apply' element.
Returns:
  • sympy.Expr –

    The resulting SymPy expression.
Raises:
  • NotImplementedError –

    If the MathML operand is not supported.

convert_mathml_node 

convert_mathml_node(node: etree.Element) -> DCCFunction | None

Process a single MathML element and return a DCCFunction object.

Parameters:
  • node (etree.Element) –

    A lxml etree Element from a MathML formula.
Returns:
  • DCCFunction | None –

    A DCCFunction object or None if the element is not a function declaration.

get_localname 

get_localname(txt: str) -> str

Extract the local name from a Clark-notation XML tag (e.g., '{uri}tag' -> 'tag').

Parameters:
  • txt (str) –

    The XML tag string.
Returns:
  • str –

    The local name of the tag.

get_node_value 

get_node_value(node: etree.Element) -> sympy.Expr

Evaluate a MathML node and return its SymPy representation.

This function handles 'apply' nodes (recursive calls), 'cn' (numbers), and 'ci' (symbols/identifiers).

Parameters:
  • node (etree.Element) –

    The lxml etree Element to evaluate.
Returns:
  • sympy.Expr –

    A SymPy Expression (Float, Symbol, or result of an operation).

handle_mathml_fn 

handle_mathml_fn(fn_node) -> tuple[str, sympy.Expr, set[str]]

Handle a MathML function declaration.

Parameters:
  • fn_node –

    The MathML 'declare' element.
Returns:
  • tuple[str, sympy.Expr, set[str]] –

    A tuple containing the function name, expression, and bound variables.
Raises:
  • ValueError –

    If the function node is invalid.