API

Public API Reference

symtorch.symtorchify(expr: str | Basic | int | float | bool, trainable: bool = True, trainable_ints: bool = False) → Expression

Convert a string, SymPy object, or numeric value to a vanilla PyTorch implementation of the expression.

Parameters:

• expr – The expression or value to convert.

• trainable – Whether the resulting parameters should be trainable, by default True.

• trainable_ints –

  Whether integer parameters should be trainable, by default False. Sympy converts e.g. the division operator into a combination of a multiplication and an exponentiation operator:

  \[a / b = a * b^{-1}\]

  The -1 exponent is converted to a symtorch.Parameter by symtorch. If trainable_ints is True, this exponent will be trainable (and hence e.g. \(a/b\) may change during training to be:

  \[a * (b^{-1.56})\]

Returns:

The converted SymTorch Expression.

Return type:

Expression

Raises:

ValueError – If trainable_ints is True but trainable is False.

Examples

Create a simple addition of two symbols:

>>> model = symtorchify("x + y")
>>> model.long_hand_representation()
Expression(Add, [Symbol('x'), Symbol('y')])
>>> str(model)
>>> x + y
>>> len(list(model.parameters()))
0
>>> input = {"x": torch.scalar_tensor(1), "y": torch.scalar_tensor(2)}
>>> model(input)
tensor([3.])

symtorch.SymbolicExpression() → Expression

Create an empty, place-holder Expression.

Returns:

An empty Expression.

Return type:

Expression

Examples

Use this as a placeholder for a model:

>>> model = SymbolicExpression()
>>> model
empty

Fill it with a symbolic expression later:

>>> other_model = symtorchify("x + 2.0", trainable=False)
>>> model.load_state_dict(other_model.state_dict())
>>> model
x + 2.0

class symtorch.SymbolAssignment(symbol_order: list[str] | None = None)

Bases: Module

Convert a tensor into a dictionary of symbols.

This module converts a tensor X of shape (..., N) into a dictionary of symbols, {s: X[..., [i]]}, where s is the i’th symbol in symbol_order.

Parameters:

symbol_order – The order of symbols to use for assignment, by default None.

Examples

Use a SymbolAssignment module in combination with a SymbolicExpression within a torch.nn.Sequential module to create a simple model:

>>> model = torch.nn.Sequential(
...     SymbolAssignment(["x", "y"]),
...     symtorchify("x**2 + 2*y")
... )
>>> input = torch.arange(10).reshape(5, 2)
>>> model(input)
tensor([[ 2],
        [10],
        [26],
        [50],
        [82]])

class symtorch.Expression

Bases: SymbolicModule

A tree-based, PyTorch-compatible implementation of a symbolic expression, where each leaf node is a Symbol or Parameter, and each internal node is another Expression.

operation

The operation at the root of the expression tree.

Type:

Operation

nodes

The child nodes of the expression tree.

Type:

Sequence[SymbolicModule]

trainable

Whether the expression is trainable.

Type:

bool

trainable_ints

Whether integer parameters in the expression are trainable.

Type:

bool

Internal API Reference

class symtorch.Parameter

Bases: SymbolicModule

A symbolic parameter, i.e. a leaf node in the expression tree.

param

The underlying value of the parameter.

Type:

torch.nn.Parameter

class symtorch.Symbol

Bases: SymbolicModule

A symbolic variable, i.e. a leaf node in the expression tree.

name

The name of the symbol.

Type:

str

class symtorch.operations.Operation

Bases: Module, ABC

Abstract base class for all torch equivalents of SymPy operations.

class symtorch.operations.Id

Bases: Operation

Identity operation.

class symtorch.operations.UnaryOperation

Bases: Operation, ABC

ABC for all torch equivalents of SymPy unary operations.

class symtorch.operations.BinaryOperation

Bases: Operation, ABC

ABC for all torch equivalents of SymPy binary operations.

class symtorch.operations.ReductionOperation

Bases: Operation, ABC

ABC for all torch equivalents of SymPy operations that act to reduce a variable number of inputs using the same operation. Examples include addition and multiplication.