Descriptor

GTPSA descriptor objects.

A descriptor defines the algebraic space for TPSA series: its variables, parameters, and their polynomial-order limits. Every Tpsa object is created on a descriptor, and series can only be combined meaningfully when they belong to compatible descriptors.

The Python object is a small handle to the underlying MAD-NG GTPSA descriptor. MAD-NG interns equivalent descriptors, and this module mirrors that by reusing the same Python Descriptor object for the same C descriptor pointer.

class madng_tpsa.descriptor.Descriptor(num_vars=None, order=None, *, num_params=None, param_order=1, variables=None, params=None, max_orders=None)

Algebraic space definition for one or more Tpsa series.

Parameters are appended after the variables in monomial tuples. For example, a descriptor with two variables and one parameter uses monomials of length three, where the last entry is the parameter order.

Create or reuse a descriptor: equivalent descriptors are interned.

Parameters:

• num_vars (int | None) – Number of variables. Omit it when variables provides their labels.

• order (int | None) – Maximum combined order of variable and parameter monomials.

• num_params (int | None) – Number of parameters. Omit it when params provides their labels; defaults to zero when params is omitted.

• param_order (int) – Maximum combined order of parameter monomials.

• variables (Sequence[str] | None) – Variable labels. Their number must match num_vars when both are given.

• params (Sequence[str] | None) – Parameter labels. Their number must match num_params when both are given.

• max_orders (Sequence[int] | None) – Per-variable and per-parameter order caps. It must contain one positive entry per variable and parameter.

Return type:

Descriptor

classmethod from_ptr(ptr, var_labels=None, param_labels=None)

Return the interned Descriptor for a raw C pointer.

Return type:

Descriptor

property ptr: Any

Descriptor pointer.

property num_vars: int

Number of variables (excluding parameters) supported by the descriptor.

property order: int

Maximum order supported by the descriptor.

property num_params: int

Number of parameters supported by the descriptor.

property param_order: int

Combined parameter order cap of the descriptor.

property monomial_length: int

Length of a full monomial, equal to num_vars + num_params.

property max_orders: tuple[int, ...]

Per-variable and per-parameter maximum orders.

is_valid_monomial(monomial)

Whether monomial is representable (querying beyond order is illegal in the C API).

Return type:

bool

monomial_index(monomial)

Index of monomial in the descriptor’s coefficient array.

Return type:

int

constant(value: SupportsComplex, /) → ComplexTpsa

constant(value: SupportsFloat, /) → Tpsa

Create a constant TPSA series on this descriptor.

Return type:

Tpsa | ComplexTpsa

zero(order=None)

Create a zero TPSA series on this descriptor.

Return type:

Tpsa

complex_zero(order=None)

Create a zero complex TPSA series on this descriptor.

Return type:

ComplexTpsa

var(index: int | str, value: SupportsFloat = 0.0, order: int | None = None) → Tpsa

var(index: int | str, value: SupportsComplex, order: int | None = None) → ComplexTpsa

Create identity variable index on this descriptor.

The variable index starts from 1 and is expanded around value. A variable label may be passed instead of an index. A complex value creates a ComplexTpsa.

Return type:

Tpsa | ComplexTpsa

vars(values: Sequence[SupportsComplex]) → tuple[ComplexTpsa, ...]

vars(values: Sequence[SupportsFloat] | None = None) → tuple[Tpsa, ...]

vars(values: Sequence[SupportsFloat | SupportsComplex]) → tuple[Tpsa | ComplexTpsa, ...]

Create identity series for all variables on this descriptor.

If values is provided, each variable is expanded around the corresponding value. Complex values create ComplexTpsa series.

Return type:

tuple[Tpsa | ComplexTpsa, …]

param(index: int | str, value: SupportsComplex) → ComplexTpsa

param(index: int | str, value: SupportsFloat = 0.0) → Tpsa

Create identity parameter index on this descriptor.

The parameter index starts from 1. Parameters are appended after variables in monomial tuples. A parameter label may be passed instead of an index. A complex value creates a ComplexTpsa.

The created TPSA will automatically be of order 1; for higher orders instantiate a new constant TPSA with the desired order and manually call madng_tpsa.Tpsa.set() to set the desired parameter coefficient.

Return type:

Tpsa | ComplexTpsa

var_or_param_index(variable)

Return the 1-based combined variable/parameter index for variable.

Return type:

int

params(values: Sequence[SupportsComplex]) → tuple[ComplexTpsa, ...]

params(values: Sequence[SupportsFloat] | None = None) → tuple[Tpsa, ...]

params(values: Sequence[SupportsFloat | SupportsComplex]) → tuple[Tpsa | ComplexTpsa, ...]

Create identity series for all parameters on this descriptor.

If values is provided, each parameter is expanded around the corresponding value. Complex values create ComplexTpsa series.

Return type:

tuple[Tpsa | ComplexTpsa, …]

format_polynomial(tpsa, style='code')

Format tpsa using this descriptor’s variable and parameter labels.

Parameters:

style (FormatStyle) – Output style. See madng_tpsa.formatting.FormatStyle.

Return type:

object