parameter

Symbolic expressions built from real-valued, finite, atomic Parameter instances based on sympy symbols and expressions.

Also defines Coefficient used e.g. in OperatorPolynomial, QuantumState or Parameterized classes as union of symbolic expressions and Python built-in numeric types.

class parityos.utils.parameter.Parameterized

Bases: ABC

Interface for any object that may contain symbolic parameters.

property parameters: frozenset[Parameter]

The symbolic parameters parameterizing this object.

abstractmethod substitute_parameters(old_to_new: Mapping[Parameter, Symbolic | complex]) → Self

Substitute symbolic parameters with new symbolic expressions or numeric values.

Parameters:

old_to_new – Mapping from existing parameter symbols to new values (numeric or symbolic).

Returns:

Copy of self with replaced parameters.

class parityos.utils.parameter.HasNoParameters

Bases: Parameterized

Implementation of Parameterized interface for classes that have no parameters.

property parameters: frozenset[Parameter]

The parameters are an empty frozenset since there are no parameters.

substitute_parameters(old_to_new: Mapping[Parameter, Symbolic | complex]) → Self

No substitution since there are no parameters.

class parityos.utils.parameter.SupportsConjugate(*args, **kwargs)

Bases: Protocol

A protocol representing objects that support the conjugate operation.

conjugate() → Self

Return the complex conjugate of this object.

class parityos.utils.parameter.BinaryOp(*args, **kwargs)

Bases: Protocol

A protocol representing a binary operation.

This protocol defines a callable that takes two arguments and returns a Expr result. At least one of the arguments must be an Expr while the other one can also be a complex.

__call__(**kwds)

Helper for @overload to raise when called.

class parityos.utils.parameter.Assumptions(*args, **kwargs)

Bases: Protocol

A protocol for classes that hold assumption predicates for symbolic expressions.

Not all predicates are independent. For example, zero=True automatically implies

• nonzero=False

• positive=False

• negative=False

Implementing classes must ensure that all attributes are consistent.

This protocol formalizes (most of) the [SymPy assumption predicates](https://docs.sympy.org/latest/guides/assumptions.html#predicates) into an object with named attributes.

Note

SymPy supports the following numerical tower integer <: rational <: real <: complex where <: means “is a subtype of”. That means every well defined number is considered complex. Strictly complex symbols with a non-zero imaginary part are therefore marked with real = False.

real: bool | None

Whether this expression represents a real number.

finite: bool | None

Whether this expression represents a finite real number.

zero: bool | None = None

Whether this expression is zero.

nonzero: bool | None = None

Whether this expression is non-zero.

positive: bool | None = None

Whether this expression is positive.

negative: bool | None = None

Whether this expression is negative.

rational: bool | None = None

Whether this expression represents an rational number.

irrational: bool | None = None

Whether this expression represents an irrational number.

integer: bool | None = None

Whether this expression represents an integer.

even: bool | None = None

Whether this expression represents an even integer.

odd: bool | None = None

Whether this expression represents an odd integer.

classmethod from_expr(expr: Expr) → Self

Create Assumptions from a given SymPy expression.

class parityos.utils.parameter.ExpressionAssumptions(real: bool | None = None, finite: bool | None = None, zero: bool | None = None, nonzero: bool | None = None, positive: bool | None = None, negative: bool | None = None, rational: bool | None = None, irrational: bool | None = None, integer: bool | None = None, even: bool | None = None, odd: bool | None = None)

Bases: Assumptions

Assumptions that are appropriate for a composite symbolic ParameterExpression.

real: bool | None

Whether this expression represents a real number.

finite: bool | None

Whether this expression represents a finite real number.

zero: bool | None

Whether this expression is zero.

nonzero: bool | None

Whether this expression is non-zero.

positive: bool | None

Whether this expression is positive.

negative: bool | None

Whether this expression is negative.

rational: bool | None

Whether this expression represents an rational number.

irrational: bool | None

Whether this expression represents an irrational number.

integer: bool | None

Whether this expression represents an integer.

even: bool | None

Whether this expression represents an even integer.

odd: bool | None

Whether this expression represents an odd integer.

classmethod from_expr(expr: Expr) → Self

Create assumptions from a given SymPy expression.

All further assumptions in expr that are not fields of Assumptions are disregarded.

Parameters:

expr – SymPy expression to fetch assumptions from.

Returns:

Assumptions with values taken from expr.

class parityos.utils.parameter.ParameterAssumptions(zero: bool | None = None, nonzero: bool | None = None, positive: bool | None = None, negative: bool | None = None, rational: bool | None = None, irrational: bool | None = None, integer: bool | None = None, even: bool | None = None, odd: bool | None = None)

Bases: ExpressionAssumptions

Assumptions that are appropriate for an atomic symbolic Parameter.

Parameter instances are always assumed to be real and finite. This class thus auto-sets these attributes accordingly and removes them from the constructor.

real: bool | None

Whether this expression represents a real number. Parameters are real per definition.

finite: bool | None

Whether this expression represents a finite real number. Parameters are finite per definition.

class parityos.utils.parameter.Symbolic(*args, **kwargs)

Bases: SupportsConjugate, Protocol

Interface for symbolic objects based on SymPy expressions (Expr) and symbols (Symbol).

Symbolic expressions also have Assumptions that hold any assumption predicates that are known for this expression.

property expr: Expr

The SymPy expression representing this symbolic expression.

property assumptions: Assumptions

The assumptions of this symbolic expression.

property is_number: bool

Whether the expression is purely numeric (as opposed to containing symbols).

property parameters: frozenset[Parameter]

The atomic symbolic parameters of this expression.

substitute_parameters(old_to_new: Mapping[Parameter, Symbolic | complex]) → Symbolic | complex

Return copy with all parameters replaced according to the mapping old_to_new.

Any parameters appearing in old_to_new that don’t appear in self are disregarded.

__neg__() → Symbolic

The negation operator -.

__abs__() → Symbolic

The absolute value abs.

__mul__(other: Symbolic | complex) → Symbolic | complex

The multiplication operator *.

__truediv__(other: Symbolic | complex) → Symbolic | complex

The division operator /.

__add__(other: Symbolic | complex) → Symbolic | complex

The addition operator +.

__sub__(other: Symbolic | complex) → Symbolic | complex

The subtraction operator -.

parityos.utils.parameter.RealCoefficient: TypeAlias = parityos.utils.parameter.Symbolic | float

A numeric or symbolic real scalar coefficient.

parityos.utils.parameter.Coefficient: TypeAlias = parityos.utils.parameter.Symbolic | complex

A numeric or symbolic scalar coefficient.

class parityos.utils.parameter.Parameter(name: str, assumptions: ParameterAssumptions = NOTHING)

Bases: Symbolic

An atomic, real-valued, finite symbolic parameter.

Possible additional assumptions (e.g. positive, integer, …) can be given in form of an ParameterAssumptions instance.

Caution

Different Parameters with the same name but different assumptions are not assumed equal.

name: str

The name of this parameter.

assumptions: ParameterAssumptions

The assumptions for this parameter. Defaults to ParameterAssumptions with default parameters.

expr: Symbol

The SymPy Symbol representing this parameter.

Its assumptions are taken from assumptions.

classmethod from_symbol(symbol: Symbol) → Self

Create a parameter from an existing SymPy Symbol.

Caution

Realness and finiteness of symbol are disregarded, as Parameter instances are always real and positive.

Parameters:

symbol – The symbol from which to create a Parameter

Returns:

The Parameter created from symbol.

conjugate() → Self

Return the complex conjugate of this object.

property is_number: bool

Whether the expression is purely numeric (as opposed to containing symbols).

parameters: frozenset[Parameter]

substitute_parameters(old_to_new: Mapping[Parameter, Symbolic | complex]) → Symbolic | complex

Return copy with all parameters replaced according to the mapping old_to_new.

Any parameters appearing in old_to_new that don’t appear in self are disregarded.

class parityos.utils.parameter.ParameterExpression(expr: Expr)

Bases: Symbolic

A symbolic expression containing one or more symbolic parameters.

Assumptions are deduced from the contained parameter assumptions and their underlying SymPy expression.

Examples

>>> # `a` could be zero, so `1/a` is undefined.
>>> expr = 1./Parameter("a")
>>> assert expr.assumptions.real is None
>>> # `a` is explicitly nonzero, so `1/a` is real and finite.
>>> expr = 1./Parameter("a", ParameterAssumptions(nonzero=True))
>>> assert expr.assumptions.real

expr: Expr

The SymPy expression representing this symbolic expression.

assumptions: Assumptions

The assumptions that are known for this expression.

The assumptions are automatically deduced from the input SymPy expression.

classmethod from_string(expr: str) → Self

Create a ParameterExpression from a string representation.

Parameters:

expr – String representation of the expression.

Returns:

A ParameterExpression create from the string expression expr.

property is_number: bool

Whether the expression is purely numeric (as opposed to containing symbols).

parameters: frozenset[Parameter]

conjugate() → ParameterExpression

Return the complex conjugate of this object.

substitute_parameters(old_to_new: Mapping[Parameter, Symbolic | complex]) → Symbolic | complex

Return copy with all parameters replaced according to the mapping old_to_new.

Any parameters appearing in old_to_new that don’t appear in self are disregarded.

parityos.utils.parameter.make_real_finite_symbol(name: str, zero: bool | None = None, positive: bool | None = None, rational: bool | None = None, integer: bool | None = None, even: bool | None = None) → Symbol

Create a real-valued, finite Symbol with additional assumptions.

Assumptions that are set to None are considered unset, i.e. the according property of the resulting symbol is unknown.

Parameters:

• name – Name of the symbol.

• zero – Whether the symbol is zero.

• positive – Whether the symbol is positive,

• rational – Whether the symbol is a rational number,

• integer – Whether the symbol is an integer,

• even – Whether the symbol is even,

Returns:

A real-valued, finite symbol with name and given assumptions.

parityos.utils.parameter.convert_to_real_finite_symbol(symbol: Symbol) → Symbol

Convert a SymPy Symbol to a real, finite Symbol, preserving other assumptions.

Preserved assumptions are whether the symbol is non-zero, positive, an integer and even/odd.

Parameters:

symbol – The symbol to convert to a real, finite symbol.

Returns:

The converted symbol representing a real, finite number.

parityos.utils.parameter.get_symbols(expr: Basic) → frozenset[Symbol]

Get free symbols from an expression that are Symbol instances.

This function filters any results from Basic.free_symbols that are not Symbol instances.

Parameters:

expr – The expression to extract symbols from.

Returns:

A frozenset of Symbol instances present in the expression.

parityos.utils.parameter.desympify_numeric_expression(expr: Expr) → complex

The inverse of sympify for numeric types.

Parameters:

expr – The numeric expression to turn into a Python built-in numeric type.

Returns:

A Python built-in numeric type (int, float, or complex) equivalent to the input expression.

Raises:

TypeError – If expr is not a purely numeric expression.

parityos.utils.parameter.to_sympy(expr: Symbolic | complex) → Expr | complex

Convert a coefficient to a SymPy Expr if the coefficient is Symbolic.

If expr is numeric, it is returned unchanged.

Parameters:

expr – The Coefficient to convert.

Returns:

The sympy expression equivalent to the input coefficient. If the input is already a sympy expression, it’s returned directly. Otherwise, the input is returned as is.

parityos.utils.parameter.symbolic_from_sympy(expr: Expr) → Symbolic

Convert any SymPy expression to a Symbolic object.

Purely numeric expressions are not converted, use coefficient_from_sympy for that purpose.

Parameters:

expr – The sympy expression to convert.

Returns:

A Symbolic object representing the input SymPy expression. If the input is a Symbol, an instance of Parameter is returned. If the input is a Expr, an instance of ParameterExpression is returned.

Raises:

ParityOSTypeError – If expr is not Symbol or Expr.

parityos.utils.parameter.symbolic_from_string(expr: str) → Symbolic

Convert symbolic expression from string to a Symbolic object.

Purely numeric expressions are not converted, use coefficient_from_string for that purpose.

Parameters:

expr – The string representation of the symbolic expression.

Returns:

A Symbolic object representing the parsed expression.

Raises:

ParityOSTypeError – If the parsed expression is not a Symbol or Expr.

parityos.utils.parameter.coefficient_from_sympy(expr: Expr) → Symbolic | complex

Convert any SymPy expression to a Symbolic object.

Purely numeric expressions are converted to Python built-in types.

Parameters:

expr – The sympy expression to convert.

Returns:

A Coefficient object representing the input sympy expression.

Raises:

ParityOSTypeError – If expr is not a Symbol or Expr.

parityos.utils.parameter.coefficient_from_string(expr: str) → Symbolic | complex

Parse symbolic expression from string to a Symbolic object.

Purely numeric expressions are converted to Python built-in types.

Parameters:

expr – The string expression to convert.

Returns:

A Coefficient object representing the input string expression.

Raises:

ParityOSTypeError – If the parsed expression is not Symbol or Expr.

parityos.utils.parameter.is_real_coefficient(coefficient: Symbolic | complex) → bool

Whether a coefficient is real, i.e. not complex at all or complex with zero imaginary part.

Parameters:

coefficient – The coefficient to check.

Returns:

Whether the coefficient is real.

parityos.utils.parameter.convert_coefficient(coefficient: Symbolic | complex) → Symbolic | complex

Convert purely numeric symbolic expressions to Python built-in numeric types and downcast if possible. Return symbolic coefficients unchanged.

Parameters:

coefficient – The coefficient to convert.

Returns:

The converted coefficient. If the input is a symbolic number, it’s converted to a Python numeric type. Otherwise, the input is returned unchanged.

parityos.utils.parameter.substitute_parameters(number: Symbolic | complex, old_to_new: Mapping[Parameter, Symbolic | complex]) → Symbolic | complex

If number is a symbolic expression, return a copy with all parameters replaced according to the mapping old_to_new. If number is numeric, return unchanged.

Any parameters appearing in old_to_new that don’t appear in number are disregarded.

Parameters:

• number – The symbolic expression or number to substitute parameters in.

• old_to_new – A mapping from old parameters to new coefficients.

Returns:

A copy of the input number with parameters substituted, or the original number if it is numeric.

parityos.utils.parameter.convert_to_unique_term_coefficient_frozenset(elements: Iterable[tuple[KeyT, Symbolic | complex]] | Mapping[KeyT, Symbolic | complex]) → frozenset[tuple[KeyT, Symbolic | complex]]

Convert an iterable of (key, coefficient) pairs to a frozenset of (key, coefficient) pairs.

Pairs with the same key but different coefficients are collected into a single pair by summing the coefficients. Pairs with coefficient equal to zero are dropped.

Parameters:

elements – Iterable or mapping of (key, coefficient) pairs.

Returns:

frozenset of (key, coefficient) pairs with no duplicate keys.

parityos.utils.parameter.coefficient_to_prefix_str(coefficient: Symbolic | complex) → str

Construct a string prefix for an OperatorProduct string representation containing the coefficient with a sign.

Parameters:

coefficient – Number for which a string prefix is constructed.

Returns:

A string prefix for coefficient.