nd2py.core package

nd2py.core package#

Subpackages#

Submodules#

nd2py.core.base_visitor module#

nd2py.core.base_visitor.yield_nothing()[source]#

A generator that yields nothing, used as a placeholder for methods that do not yield.

class nd2py.core.base_visitor.Visitor[source]#

Bases: ABC

abstractmethod generic_visit(node: Symbol, *args, **kwargs)[source]#

nd2py.core.symbol_api module#

class nd2py.core.symbol_api.SymbolAPIMixin[source]#

Bases: object

Symbol API Mixin.

该类集中管理 Symbol 对象对用户暴露的所有核心功能接口 (Facade)。 所有具体逻辑均由底层的 Visitor 类实现。

作为 Symbol 的父类混入，从而保证 symbols.py 的整洁与高可维护性。

to_str(raw=False, latex=False, number_format='', omit_mul_sign=False, skeleton=False) → str[source]#

Return a string representation of the symbol expression.

This is a thin wrapper around StringPrinter and can produce raw, LaTeX, or skeleton forms of the expression.

Parameters:

  • raw (bool, optional) – If True, return the internal raw representation instead of a prettified one. Defaults to False.

  • latex (bool, optional) – If True, format the expression as LaTeX. Defaults to False.

  • number_format (str, optional) – Format specifier used to print numeric constants (for example "0.2f"). Defaults to an empty string, which uses the default formatting.

  • omit_mul_sign (bool, optional) – If True, omit explicit multiplication signs (for example render ab instead of a*b). Defaults to False.

  • skeleton (bool, optional) – If True, ignore concrete numeric values and keep only the symbolic structure of the expression. Defaults to False.

Returns:

String representation of the symbol expression.

Return type:

str

to_tree(number_format='', flat=False, skeleton=False) → str[source]#

Return an ASCII tree representation of the expression.

Parameters:

  • number_format (str, optional) – Format specifier used to print numeric constants (for example "0.2f"). Defaults to an empty string, which uses the default formatting.

  • flat (bool, optional) – If True, flatten nested Add and Mul nodes into a single level. Defaults to False.

  • skeleton (bool, optional) – If True, ignore concrete numeric values and keep only the symbolic structure of the expression. Defaults to False.

Returns:

Multi-line string visualising the expression tree.

Return type:

str

eval(vars: dict = {}, edge_list: Tuple[List[int], List[int]] = None, num_nodes: int = None, use_eps: float = 0.0)[source]#

Evaluate the expression numerically using NumPy.

Parameters:

  • vars (dict, optional) – Mapping from variable names to their numerical values. Values can be scalars or numpy.ndarray objects. Defaults to an empty dictionary.

  • edge_list (Tuple[List[int], List[int]], optional) – Pair of integer lists (sources, targets) describing directed edges in a graph. Node indices start from 0. If provided, this is used to parameterise graph-related symbols.

  • num_nodes (int, optional) – Number of nodes in the underlying graph. If omitted, it may be inferred from edge_list when possible.

  • use_eps (float, optional) – Small positive value added in denominators or other potentially unstable operations to avoid division by zero and improve numerical stability. Defaults to 0.0.

Returns:

Numerical evaluation result of the expression, whose shape depends on the symbol and inputs.

Return type:

numpy.ndarray | float

eval_torch(vars: dict = {}, edge_list: Tuple[List[int], List[int]] = None, num_nodes: int = None, use_eps: float = 0.0, device: str = 'cpu')[source]#

Evaluate the expression numerically using PyTorch.

Parameters:

  • vars (dict, optional) – Mapping from variable names to their numerical values. Values can be scalars or torch.Tensor objects. Defaults to an empty dictionary.

  • edge_list (Tuple[List[int], List[int]], optional) – Pair of integer lists (sources, targets) describing directed edges in a graph. Node indices start from 0. If provided, this is used to parameterise graph-related symbols.

  • num_nodes (int, optional) – Number of nodes in the underlying graph. If omitted, it may be inferred from edge_list when possible.

  • use_eps (float, optional) – Small positive value added in denominators or other potentially unstable operations to avoid division by zero and improve numerical stability. Defaults to 0.0.

  • device (str, optional) – Target device on which tensors are allocated and computations are performed, such as "cpu" or "cuda". Defaults to "cpu".

Returns:

Numerical evaluation result of the expression.

Return type:

torch.Tensor

split_by_add(split_by_sub: bool = False, expand_mul: bool = False, expand_div: bool = False, expand_aggr: bool = False, expand_rgga: bool = False, expand_sour: bool = False, expand_targ: bool = False, expand_readout: bool = False, remove_coefficients: bool = False, merge_bias: bool = False) → List['Symbol'][source]#

Split an additive expression into its additive terms.

The current symbol is treated as the root. Depending on the flags, this can also expand multiplication, division, aggregation and readout nodes before splitting.

Parameters:

  • split_by_sub (bool, optional) – If True, treat subtraction nodes as additions when splitting, so that a - b becomes [a, -b]. Defaults to False.

  • expand_mul (bool, optional) – If True, expand Mul nodes before splitting. Defaults to False.

  • expand_div (bool, optional) – If True, expand Div nodes before splitting. Defaults to False.

  • expand_aggr (bool, optional) – If True, expand aggregation nodes (for example graph aggregators) before splitting. Defaults to False.

  • expand_rgga (bool, optional) – If True, expand RGGA-related nodes before splitting. Defaults to False.

  • expand_sour (bool, optional) – If True, expand source-related transformations before splitting. Defaults to False.

  • expand_targ (bool, optional) – If True, expand target-related transformations before splitting. Defaults to False.

  • expand_readout (bool, optional) – If True, push Readout inside additions, so that for example Readout(a + b) becomes [Readout(a), Readout(b)]. Defaults to False.

  • remove_coefficients (bool, optional) – If True, drop scalar coefficients from the resulting symbols. Defaults to False.

  • merge_bias (bool, optional) – If True, merge additive bias terms into neighbouring symbols when appropriate. Defaults to False.

Returns:

List of symbols corresponding to each additive term.

Return type:

List[Symbol]

split_by_mul(split_by_div: bool = False, merge_coefficients: bool = False) → List['Symbol'][source]#

Split a multiplicative expression into its multiplicative factors.

The current symbol is treated as the root. Depending on the flags, this can also split divisions and optionally merge coefficients.

Parameters:

  • split_by_div (bool, optional) – If True, split divisions so that an expression like a / b is treated as having factors [a, b]. Defaults to False.

  • merge_coefficients (bool, optional) – If True, merge scalar coefficients into a single factor instead of returning them as separate symbols. Defaults to False.

Returns:

List of symbols corresponding to each multiplicative factor.

Return type:

List[Symbol]

fix_nettype(nettype: NetType = 'node', direction: Literal['bottom-up', 'top-down'] = 'top-down', edge_to_node=['remove_targ', 'remove_sour', 'add_aggr', 'add_rgga'], node_to_edge=['remove_aggr', 'remove_rgga', 'add_targ', 'add_sour'], edge_to_scalar=['remove_sour', 'remove_targ', 'add_readout'], node_to_scalar=['remove_aggr', 'remove_rgga', 'add_readout'], scalar_to_node=['keep'], scalar_to_edge=['keep'])[source]#

Normalize nettypes of all symbols in the expression.

This is useful in GP or LLM-based symbolic regression where equations are generated automatically and may contain inconsistent nettype annotations.

Parameters:

  • nettype (NetType, optional) – Target nettype of the root symbol. Typical values include "node", "edge" and "scalar". Defaults to "node".

  • direction (Literal["bottom-up", "top-down"], optional) – Direction in which the fix is propagated through the expression tree. Defaults to "top-down".

  • edge_to_node (List[str], optional) – Sequence of transformation rules applied when converting edge symbols to node symbols.

  • node_to_edge (List[str], optional) – Sequence of transformation rules applied when converting node symbols to edge symbols.

  • edge_to_scalar (List[str], optional) – Sequence of transformation rules applied when converting edge symbols to scalar symbols.

  • node_to_scalar (List[str], optional) – Sequence of transformation rules applied when converting node symbols to scalar symbols.

  • scalar_to_node (List[str], optional) – Sequence of transformation rules applied when converting scalar symbols to node symbols.

  • scalar_to_edge (List[str], optional) – Sequence of transformation rules applied when converting scalar symbols to edge symbols.

Returns:

Root symbol of the expression with consistent nettypes.

Return type:

Symbol

simplify(transform_constant_subtree: bool = True, remove_useless_readout: bool = True, remove_nested_sin: bool = False, remove_nested_cos: bool = False, remove_nested_tanh: bool = False, remove_nested_sigmoid: bool = False, remove_nested_sqrt: bool = False, remove_nested_sqrtabs: bool = False, remove_nested_exp: bool = False, remove_nested_log: bool = False, remove_nested_logabs: bool = False)[source]#

Apply algebraic simplifications to the expression.

Each flag controls whether a specific family of simplification rules is enabled. By default constant subtrees are folded and useless readout nodes are removed.

Parameters:

  • transform_constant_subtree (bool, optional) – If True, evaluate and replace constant-only subtrees with their numerical result. Defaults to True.

  • remove_useless_readout (bool, optional) – If True, eliminate redundant Readout nodes that do not affect the result. Defaults to True.

  • remove_nested_sin (bool, optional) – If True, simplify expressions containing nested sine functions when possible. Defaults to False.

  • remove_nested_cos (bool, optional) – If True, simplify expressions containing nested cosine functions when possible. Defaults to False.

  • remove_nested_tanh (bool, optional) – If True, simplify expressions containing nested hyperbolic tangent functions when possible. Defaults to False.

  • remove_nested_sigmoid (bool, optional) – If True, simplify expressions containing nested sigmoid functions when possible. Defaults to False.

  • remove_nested_sqrt (bool, optional) – If True, simplify nested square root expressions when possible. Defaults to False.

  • remove_nested_sqrtabs (bool, optional) – If True, simplify nested sqrtabs-like expressions when possible. Defaults to False.

  • remove_nested_exp (bool, optional) – If True, simplify nested exponential expressions when possible. Defaults to False.

  • remove_nested_log (bool, optional) – If True, simplify nested logarithm expressions when possible. Defaults to False.

  • remove_nested_logabs (bool, optional) – If True, simplify nested logabs-like expressions when possible. Defaults to False.

Returns:

A simplified version of the original symbol expression.

Return type:

Symbol