Python API Reference

This chapter documents the complete API of the oCAS Python bindings (the ocas module). Every class and function includes its signature, parameter descriptions, return value, exceptions, and complete examples.

Version: This document corresponds to oCAS 0.24.x.

Import

import ocas

The module exports all classes and functions at the top level; no submodule imports are required.

Expressions

Expression

Symbolic expression class. Constructed by parsing a string; supports arithmetic operations, calculus, simplification, and more.

Signature:

ocas.Expression(input: str)

Parameters:

Returns: an Expression instance.

Exceptions: ValueError — the expression string failed to parse.

Supported operations:

Methods:

Expression.clone

Expression.clone() -> Expression

Returns a deep copy of the expression.

Example:

>>> e = ocas.Expression("x + 1")
>>> f = e.clone()
>>> e == f
True

Expression.simplify

Expression.simplify() -> Expression

Simplifies the expression using the built-in rule set (fixed-point iteration).

Returns: the simplified Expression.

Exceptions: ValueError — an internal error occurred during simplification.

Example:

>>> e = ocas.Expression("x + x")
>>> print(e.simplify())
2*x

Expression.diff

Expression.diff(var: str) -> Expression

Differentiates the expression with respect to the variable var.

Parameters:

Returns: the derivative expression.

Example:

>>> e = ocas.Expression("x^3 + 2*x")
>>> print(e.diff("x"))
2 + (3*(x^2))

Expression.integrate

Expression.integrate(var: str) -> Expression

Symbolically integrates the expression with respect to the variable var. Uses a layered integration pipeline: fast lookup table → rational functions → Risch → trigonometric rewrite + realify → special functions → heuristic → unevaluated form.

Parameters:

Returns: the resulting expression. If no closed form can be found, returns the unevaluated Integral(expr, var) form. The result is not certified; use integrate_outcome when a machine-checkable certificate is required.

Example:

>>> e = ocas.Expression("x^2")
>>> print(e.integrate("x"))
(3^-1)*(x^3)

Expression.integrate_outcome

Expression.integrate_outcome(var: str, rules: bool = True) -> dict

Certified integration (new in 0.28.0): the result is three-valued. found always carries a machine-checkable symbolic certificate (D(F) − f ≡ 0), while unknown honestly returns the unevaluated form. A result the exact checker falsifies is never returned as found.

Parameters:

Returns: a dict with the keys:

Example:

>>> e = ocas.Expression("2*x")
>>> e.integrate_outcome("x")["kind"]
'found'
>>> ocas.Expression("exp(x^3)").integrate_outcome("x")["kind"]
'unknown'

Expression.integrate_heuristic

Expression.integrate_heuristic(var: str) -> Expression

Integrates using heuristic methods only (integration by parts, trigonometric substitutions, etc.), without invoking the full Risch algorithm. Returns a closed form on success and an unevaluated form on failure.

Parameters:

Returns: the integral result or the unevaluated Integral(expr, var).

Example:

>>> e = ocas.Expression("sin(x)")
>>> print(e.integrate_heuristic("x"))
-1*(cos(x))

Expression.taylor

Expression.taylor(var: str, point: Expression, order: int) -> Expression

Computes the Taylor expansion of the expression in var about point up to order order.

Parameters:

Returns: the Taylor polynomial.

Example:

>>> e = ocas.Expression("exp(x)")
>>> p = ocas.Expression("0")
>>> print(e.taylor("x", p, 4))
1 + x + ((2^-1)*(x^2)) + ((6^-1)*(x^3)) + ((24^-1)*(x^4))

Expression.substitute

Expression.substitute(var: str, replacement: Expression) -> Expression

Replaces every occurrence of var in the expression with replacement.

Parameters:

Returns: the substituted expression.

Example:

>>> e = ocas.Expression("x^2 + y")
>>> r = ocas.Expression("3")
>>> print(e.substitute("x", r))
y + (3^2)

Polynomials

Polynomial

Dense univariate polynomial supporting three coefficient domains: integers ℤ, rationals ℚ, and finite fields GF(p).

Signature:

ocas.Polynomial(coeffs, domain=None)

Parameters:

Coefficient formats:

• Integer domain: a list of integers, e.g. [1, 2, 1] represents $1 + 2x + x^2$
• Rational domain: a list of integers or a list of (numerator, denominator) tuples
• Finite field: a list of integers; arithmetic is automatically reduced modulo p

Exceptions: TypeError — coefficient types do not match the selected domain.

Example:

>>> from ocas import Polynomial
>>> p = Polynomial([1, 2, 1])
>>> print(p.degree())
2

Polynomial.coeffs

Polynomial.coeffs() -> list[str]

Returns the coefficient list (as strings), ordered from lowest to highest degree.

Example:

>>> p = Polynomial([1, 2, 1])
>>> p.coeffs()
['1', '2', '1']

Polynomial.degree

Polynomial.degree() -> int | None

Returns the degree of the polynomial. The zero polynomial returns None.

Example:

>>> Polynomial([1, 2, 1]).degree()
2
>>> Polynomial([0]).degree() is None
True

Polynomial.len

Polynomial.len() -> int

Returns the number of stored coefficients.

Polynomial.is_zero

Polynomial.is_zero() -> bool

Whether the polynomial is the zero polynomial.

Polynomial.eval

Polynomial.eval(x) -> str

Evaluates the polynomial at the point x. Over the integer domain x is an integer; over the rational domain x is an integer or a (numerator, denominator) tuple.

Returns: the string representation of the evaluation result.

Example:

>>> p = Polynomial([1, 2, 1])
>>> p.eval(2)
'9'

Polynomial.derivative

Polynomial.derivative() -> Polynomial

Returns the formal derivative.

Example:

>>> p = Polynomial([1, 2, 1])
>>> q = p.derivative()
>>> q.coeffs()
['2', '2']

Polynomial.integral

Polynomial.integral() -> Polynomial

Returns the formal integral (with zero constant term). Available on all three coefficient domains: exact over the rationals; over the integers and finite fields, coefficients whose division by $i+1$ does not divide exactly are set to zero (no exception is raised).

Polynomial.primitive_part

Polynomial.primitive_part() -> Polynomial

Returns the primitive part (content removed). Supported on the integer domain only.

Exceptions: ValueError — the polynomial is not over the integer domain.

Polynomial.factor

Polynomial.factor() -> list[PolynomialFactor]

Complete factorization. Returns a list of (factor, multiplicity) pairs: over the integers each factor is primitive; over a finite field each factor is monic.

Factorization strategy:

• ℤ[x]: square-free factorization + Berlekamp–Zassenhaus + Hensel lifting
• GF(p)[x]: Berlekamp's algorithm

Example:

>>> p = Polynomial([1, 2, 1])
>>> for f in p.factor():
...     print(f.factor.coeffs(), f.multiplicity)
['1', '1'] 2

Polynomial.square_free_factorization

Polynomial.square_free_factorization() -> list[PolynomialFactor]

Square-free factorization. Returns the pairwise-distinct square-free factors together with their multiplicities.

Example:

>>> p = Polynomial([1, 2, 1])
>>> for f in p.square_free_factorization():
...     print(f.factor.coeffs(), f.multiplicity)
['1', '1'] 2

Polynomial.is_square_free

Polynomial.is_square_free() -> bool

Whether the polynomial is square-free (has no repeated irreducible factors).

Polynomial.gcd

Polynomial.gcd(other: Polynomial) -> Polynomial

Computes the greatest common divisor with other. Both polynomials must be over the same coefficient domain.

Exceptions: TypeError — the coefficient domains do not match.

Example:

>>> a = Polynomial([0, 1])         # x
>>> b = Polynomial([0, 0, 1])     # x^2
>>> a.gcd(b).coeffs()
['0', '1']

Polynomial.div_rem

Polynomial.div_rem(other: Polynomial) -> tuple[Polynomial, Polynomial] | None

Division with remainder, returning (quotient, remainder). Returns None when other is zero.

Exceptions: TypeError — the coefficient domains do not match.

Example:

>>> a = Polynomial([1, 2, 1])
>>> b = Polynomial([1, 1])
>>> q, r = a.div_rem(b)
>>> q.coeffs()
['1', '1']
>>> r.is_zero()
True

Polynomial arithmetic

PolynomialFactor

A single factor in a factorization result.

Attributes:

MultivariatePolynomial

Sparse multivariate polynomial ($\mathbb{Q}[x_1, \dots, x_n]$), using the lexicographic order (Lex).

Signature:

ocas.MultivariatePolynomial(terms: dict, n_vars: int)

Parameters:

Example:

>>> from ocas import MultivariatePolynomial
>>> # x² + y² - 1
>>> p = MultivariatePolynomial({(2, 0): 1, (0, 2): 1, (0, 0): -1}, n_vars=2)
>>> p.n_vars()
2

MultivariatePolynomial.n_vars

MultivariatePolynomial.n_vars() -> int

Returns the number of variables.

Matrices

Matrix

Dense matrix over a field, supporting ℤ, ℚ, and GF(p).

Signature:

ocas.Matrix(rows, domain=None)

Parameters:

Exceptions: TypeError — element types do not match the selected domain.

Example:

>>> from ocas import Matrix
>>> a = Matrix([[1, 2], [3, 4]])
>>> a.determinant()
'-2'

Matrix.nrows

Matrix.nrows -> int  # property

The number of rows.

Matrix.ncols

Matrix.ncols -> int  # property

The number of columns.

Matrix.shape

Matrix.shape() -> tuple[int, int]

Returns (nrows, ncols).

Matrix.getitem

Matrix[i, j] -> str

Returns the element at position (i, j) (as a string).

Exceptions: ValueError — index out of bounds.

Example:

>>> a = Matrix([[1, 2], [3, 4]])
>>> a[1, 0]
'3'

Matrix.rows

Matrix.rows() -> list[list[str]]

Returns the two-dimensional list of all rows (as strings).

Matrix.transpose

Matrix.transpose() -> Matrix

Returns the transposed matrix.

Matrix.trace

Matrix.trace() -> str

Returns the trace of the square matrix (sum of diagonal elements).

Exceptions: ValueError — the matrix is not square.

Matrix.rank

Matrix.rank() -> int

Returns the rank of the matrix.

Matrix.determinant

Matrix.determinant() -> str

Returns the determinant of the square matrix (Bareiss fraction-free algorithm).

Exceptions: ValueError — the matrix is not square.

Example:

>>> a = Matrix([[1, 2], [3, 4]])
>>> a.determinant()
'-2'

Matrix.inverse

Matrix.inverse() -> Matrix

Returns the inverse matrix.

Exceptions: ValueError — the matrix is singular or not square.

Matrix.solve

Matrix.solve(rhs) -> list[str]

Solves the linear system self · x = rhs.

Parameters:

Returns: the solution vector (as a list of strings).

Exceptions: ValueError — no solution or the solution is not unique.

Example:

>>> a = Matrix([[2, 0], [0, 3]])
>>> a.solve([4, 9])
['2', '3']

Matrix arithmetic

Coefficient Domains

IntegerDomain

Selector class for the integer domain ℤ.

Signature:

ocas.IntegerDomain()

Note: the domain parameter of Polynomial and Matrix currently accepts strings ("integer" / "rational") or a FiniteField instance; IntegerDomain() / RationalDomain() instances cannot yet be passed directly as that parameter.

Example:

>>> from ocas import IntegerDomain, Polynomial
>>> d = IntegerDomain()
>>> repr(d)
'IntegerDomain()'
>>> p = Polynomial([1, 2, 1], domain="integer")
>>> p.coeffs()
['1', '2', '1']

RationalDomain

Selector for the rational number domain ℚ.

Signature:

ocas.RationalDomain()

Example:

>>> from ocas import RationalDomain, Polynomial
>>> d = RationalDomain()
>>> repr(d)
'RationalDomain()'
>>> p = Polynomial([(1, 2), (3, 4)], domain="rational")
>>> p.coeffs()
['1/2', '3/4']

FiniteField

The finite field GF(p), where $p$ is a prime.

Signature:

ocas.FiniteField(modulus: int)

Parameters:

Returns: a FiniteField instance.

Exceptions: ValueError — modulus < 2.

Attributes:

Example:

>>> from ocas import FiniteField, Polynomial
>>> gf5 = FiniteField(5)
>>> p = Polynomial([1, 2, 1], domain=gf5)
>>> print(repr(gf5))
FiniteField(5)

Solvers

solve_linear_rational

ocas.solve_linear_rational(a: list[list[int]], b: list[int]) -> list[tuple[int, int]]

Solves the linear system $A \mathbf{x} = \mathbf{b}$ over ℚ.

Parameters:

Returns: the solution vector, each component being a (numerator, denominator) tuple.

Exceptions: ValueError — the solution is not unique.

Example:

>>> ocas.solve_linear_rational([[2, 0], [0, 3]], [4, 9])
[(2, 1), (3, 1)]

solve_linear_integer

ocas.solve_linear_integer(a: list[list[int]], b: list[int]) -> list[int]

Solves the linear system $A \mathbf{x} = \mathbf{b}$ over ℤ.

Parameters:

Returns: the integer solution vector.

Exceptions: ValueError — no integer solution exists.

Example:

>>> ocas.solve_linear_integer([[2, 0], [0, 3]], [4, 9])
[2, 3]

solve_diophantine

ocas.solve_diophantine(a: int, b: int, c: int) -> DiophantineSolution | None

Solves the linear Diophantine equation $ax + by = c$.

Parameters:

Returns: a DiophantineSolution (when a solution exists) or None (when no integer solution exists).

Example:

>>> sol = ocas.solve_diophantine(3, 5, 1)
>>> sol.particular
(2, -1)
>>> sol.general
(5, -3)

DiophantineSolution

The solution of a Diophantine equation.

Attributes:

ODE

classify_ode

ocas.classify_ode(equation: Expression, func: str, var: str) -> list[str]

Classifies an ordinary differential equation and returns the list of available solver method names.

Parameters:

Returns: a list of method names, e.g. ["LinearFirst", "PowerSeries"].

Supported ODE types: Separable, LinearFirst, Bernoulli, Exact, Homogeneous, LinearConstantCoeff, CauchyEuler, ReductionOfOrder, PowerSeries.

Example:

>>> eq = ocas.Expression("Derivative(y(x), x) - y(x)")
>>> ocas.classify_ode(eq, "y", "x")
['LinearFirst', 'PowerSeries']

dsolve

ocas.dsolve(equation: Expression, func: str, var: str, hint: str | None = None) -> str

Symbolically solves an ODE.

Signature (with defaults): dsolve(equation, func, var, hint=None)

Parameters:

Returns: the string representation of the solution (explicit, implicit, series, or unevaluated form).

Example:

>>> eq = ocas.Expression("Derivative(y(x), x) - y(x)")
>>> ocas.dsolve(eq, "y", "x")
'y = C1*exp(x)'

dsolve_ivp

ocas.dsolve_ivp(equation: Expression, func: str, var: str, y0: str, y1: str | None = None) -> str

Solves an initial value problem for a constant-coefficient linear ODE via the Laplace transform.

Signature (with defaults): dsolve_ivp(equation, func, var, y0, y1=None)

Parameters:

Returns: the explicit solution string without arbitrary constants.

Example:

>>> eq = ocas.Expression("Derivative(y(x), x, 2) + y(x)")
>>> ocas.dsolve_ivp(eq, "y", "x", "0", "1")
'y = sin(x)'

Number Theory

factorint

ocas.factorint(n: int) -> list[tuple[str, int]]

Factors $|n|$ into prime factors. Negative inputs start with ("-1", 1).

Parameters:

Returns: a list of (prime, exponent) tuples, sorted by prime in ascending order.

Example:

>>> ocas.factorint(60)
[('2', 2), ('3', 1), ('5', 1)]
>>> ocas.factorint(-12)
[('-1', 1), ('2', 2), ('3', 1)]

isprime

ocas.isprime(n: int) -> bool

BPSW probabilistic primality test. Deterministic for $n < 2^{64}$; no composite numbers of any size are currently known to pass.

Parameters:

Returns: True if (probably) prime.

Example:

>>> ocas.isprime(97)
True
>>> ocas.isprime(100)
False

isprime_u64

ocas.isprime_u64(n: int) -> bool

Deterministic primality test for $n < 2^{64}$ (u64 fast path).

Parameters:

Returns: True if prime.

Example:

>>> ocas.isprime_u64(2**61 - 1)
True

nextprime

ocas.nextprime(n: int) -> int

Returns the smallest prime strictly greater than $n$.

Parameters:

Returns: the next prime (arbitrary precision).

Example:

>>> ocas.nextprime(10)
11
>>> ocas.nextprime(11)
13

discrete_log

ocas.discrete_log(p: int, base: int, target: int) -> int

Solves the discrete logarithm $\text{base}^x \equiv \text{target} \pmod{p}$. Uses the Pohlig–Hellman algorithm for prime $p$, otherwise BSGS.

Parameters:

Returns: the discrete logarithm $x$.

Exceptions: ValueError — the logarithm does not exist.

Example:

>>> ocas.discrete_log(13, 2, 9)
8
>>> pow(2, 8, 13)
9

crt

ocas.crt(moduli: list[int], residues: list[int]) -> tuple[int, int]

Chinese remainder theorem: solves the system of congruences $x \equiv r_i \pmod{m_i}$.

Parameters:

Returns: (r, m) such that $x \equiv r \pmod{m}$.

Exceptions: ValueError — the system is inconsistent.

Example:

>>> ocas.crt([3, 5, 7], [2, 3, 2])
(23, 105)

jacobi_symbol

ocas.jacobi_symbol(a: int, n: int) -> int

Computes the Jacobi symbol $\left(\frac{a}{n}\right)$, where $n$ is a positive odd integer.

Parameters:

Returns: $-1$, $0$, or $1$.

Exceptions: ValueError — n is not a positive odd integer.

Example:

>>> ocas.jacobi_symbol(2, 7)
1
>>> ocas.jacobi_symbol(3, 7)
-1

totient

ocas.totient(n: int) -> int

Euler totient function $\varphi(n)$.

Parameters:

Returns: $\varphi(n)$ (arbitrary precision).

Example:

>>> ocas.totient(12)
4

mobius

ocas.mobius(n: int) -> int

Möbius function $\mu(n)$.

Parameters:

Returns: $-1$, $0$, or $1$.

Example:

>>> ocas.mobius(6)
1
>>> ocas.mobius(4)
0

divisor_count

ocas.divisor_count(n: int) -> int

Number of positive divisors $\tau(n)$.

Parameters:

Returns: the number of positive divisors.

Example:

>>> ocas.divisor_count(12)
6

divisor_sigma

ocas.divisor_sigma(n: int, k: int = 1) -> int

Sum of the $k$-th powers of the divisors $\sigma_k(n) = \sum_{d \mid n} d^k$.

Signature (with defaults): divisor_sigma(n, k=1)

Parameters:

Returns: $\sigma_k(n)$.

Example:

>>> ocas.divisor_sigma(12)      # 1+2+3+4+6+12
28
>>> ocas.divisor_sigma(12, 2)   # 1+4+9+16+36+144
210

liouville_lambda

ocas.liouville_lambda(n: int) -> int

Liouville function $\lambda(n) = (-1)^{\Omega(n)}$, where $\Omega(n)$ is the number of prime factors of $n$ counted with multiplicity.

Parameters:

Returns: $-1$ or $1$.

Example:

>>> ocas.liouville_lambda(12)  # Ω(12)=3
-1
>>> ocas.liouville_lambda(9)   # Ω(9)=2
1

Gröbner Bases & Ideals

Note: The following functions keep their py_ prefix (the Rust side does not use #[pyo3(name=...)] renaming). The actual call names in Python are ocas.py_groebner_basis, ocas.py_ideal_contains, etc.

py_groebner_basis

ocas.py_groebner_basis(generators, n_vars: int = 1, algorithm: str = "auto") -> GroebnerBasis

Computes a Gröbner basis of the polynomial ideal.

Parameters:

Returns: a GroebnerBasis object.

Exceptions: ValueError — invalid algorithm name.

Example:

>>> from ocas import MultivariatePolynomial, py_groebner_basis
>>> f = MultivariatePolynomial({(2, 0): 1, (0, 0): -1}, n_vars=2)   # x² - 1
>>> g = MultivariatePolynomial({(0, 2): 1, (0, 0): -1}, n_vars=2)   # y² - 1
>>> gb = py_groebner_basis([f, g], n_vars=2)
>>> len(gb)
2

py_ideal_contains

ocas.py_ideal_contains(generators, f, n_vars: int = 1, algorithm: str = "auto") -> bool

Determines whether the polynomial $f$ belongs to the ideal generated by generators.

Parameters:

Returns: True if $f \in I$.

Example:

>>> from ocas import MultivariatePolynomial, py_ideal_contains
>>> f = MultivariatePolynomial({(2, 0): 1, (0, 0): -1}, n_vars=2)
>>> g = MultivariatePolynomial({(0, 2): 1, (0, 0): -1}, n_vars=2)
>>> x = MultivariatePolynomial({(1, 0): 1}, n_vars=2)
>>> py_ideal_contains([f, g], f, n_vars=2)
True
>>> py_ideal_contains([f, g], x, n_vars=2)
False

py_solve_polynomial_system

ocas.py_solve_polynomial_system(equations, n_vars: int = 1, algorithm: str = "auto") -> PolynomialSystemSolution

Solves a system of polynomial equations.

Parameters:

Returns: a PolynomialSystemSolution object.

Example:

>>> from ocas import MultivariatePolynomial, py_solve_polynomial_system
>>> f = MultivariatePolynomial({(2, 0): 1, (0, 2): 1, (0, 0): -1}, n_vars=2)
>>> g = MultivariatePolynomial({(1, 0): 1, (0, 0): -1}, n_vars=2)
>>> sol = py_solve_polynomial_system([f, g], n_vars=2)
>>> sol.kind
'zero_dimensional'
>>> for s in sol.solutions():
...     print(s.values, s.multiplicity)
[1.0, 0.0] 1

py_hilbert_series

ocas.py_hilbert_series(gb: GroebnerBasis) -> HilbertSeries

Computes the Hilbert series of the Gröbner basis.

Parameters:

Returns: a HilbertSeries object.

Example:

>>> from ocas import MultivariatePolynomial, py_groebner_basis, py_hilbert_series
>>> f = MultivariatePolynomial({(2, 0): 1, (0, 0): -1}, n_vars=2)
>>> gb = py_groebner_basis([f], n_vars=2)
>>> hs = py_hilbert_series(gb)
>>> hs.dimension
1

py_ideal_radical

ocas.py_ideal_radical(generators, n_vars: int = 1) -> GroebnerBasis

Computes the radical $\sqrt{I}$ of the ideal.

Parameters:

Returns: a Gröbner basis of $\sqrt{I}$.

Algorithm: square-free factorization for zero-dimensional ideals; Jacobian saturation $\sqrt{I} = I : h^\infty$ for positive-dimensional ideals.

py_primary_decomposition

ocas.py_primary_decomposition(generators, n_vars: int = 1) -> list[PrimaryComponent]

Computes the primary decomposition of the ideal.

Parameters:

Returns: a list of PrimaryComponent.

Example:

>>> from ocas import MultivariatePolynomial, py_primary_decomposition
>>> f = MultivariatePolynomial({(2, 0): 1, (0, 0): -1}, n_vars=1)
>>> comps = py_primary_decomposition([f], n_vars=1)
>>> len(comps)
2

py_is_zero_dimensional

ocas.py_is_zero_dimensional(gb: GroebnerBasis) -> bool

Determines whether the ideal of the Gröbner basis is zero-dimensional.

Parameters:

Returns: True if zero-dimensional.

py_eliminate

ocas.py_eliminate(generators, elim_vars: int, n_vars: int = 1, algorithm: str = "auto") -> GroebnerBasis

Elimination: computes a Gröbner basis of the elimination ideal $I \cap k[x_{e+1}, \dots, x_n]$.

Parameters:

Returns: a Gröbner basis of the elimination ideal.

MultivariatePolynomial (Gröbner helper class)

Already introduced in the Polynomials section. The Gröbner functions accept both MultivariatePolynomial and Polynomial as generators; the latter are automatically mapped to univariate multivariate polynomials.

GroebnerBasis

The result of a Gröbner basis computation.

Attributes:

Methods:

RealSolution

A real solution of a polynomial system.

Attributes:

PolynomialSystemSolution

The solving result of a polynomial system.

Attributes:

Methods:

HilbertSeries

The Hilbert series.

Attributes:

Methods:

PrimaryComponent

A component of a primary decomposition.

Attributes:

Algebraic Numbers

AlgebraicExtension

The algebraic number field $K = \mathbb{Q}(\alpha)$, defined by a monic minimal polynomial.

Signature:

ocas.AlgebraicExtension(min_poly: list)

Parameters:

Exceptions: ValueError — the coefficient list is too short, the leading coefficient is not 1, or irreducibility verification fails.

Example:

>>> from ocas import AlgebraicExtension
>>> # α² - 2 (i.e. ℚ(√2))
>>> field = AlgebraicExtension([-2, 0, 1])
>>> field.extension_degree()
2

AlgebraicExtension.extension_degree

AlgebraicExtension.extension_degree() -> int

Returns the degree of the extension $[K:\mathbb{Q}] = \deg(m)$.

AlgebraicExtension.alpha

AlgebraicExtension.alpha() -> AlgebraicElement

Returns the generator $\alpha$ of the extension.

Example:

>>> field = AlgebraicExtension([-2, 0, 1])
>>> a = field.alpha()
>>> a.coeffs()
['0', '1']

AlgebraicExtension.from_base

AlgebraicExtension.from_base(c) -> AlgebraicElement

Embeds the rational number $c$ as a constant element of the field.

Parameters:

AlgebraicExtension.element

AlgebraicExtension.element(coeffs: list) -> AlgebraicElement

Creates an element from the $\alpha$-polynomial coefficients (ascending powers).

Parameters:

Example:

>>> field = AlgebraicExtension([-2, 0, 1])
>>> # 3 + 2α
>>> e = field.element([3, 2])
>>> e.coeffs()
['3', '2']

AlgebraicElement

An element of the algebraic number field $\mathbb{Q}(\alpha)$, stored as a polynomial in $\alpha$.

AlgebraicElement.coeffs

AlgebraicElement.coeffs() -> list[str]

Returns the $\alpha$-polynomial coefficients (list of strings, ascending powers).

Example:

>>> field = AlgebraicExtension([-2, 0, 1])
>>> e = field.element([1, 1])  # 1 + α = 1 + √2
>>> e.coeffs()
['1', '1']

AlgebraicPolynomial

Dense univariate polynomial over the algebraic number field $\mathbb{Q}(\alpha)$.

Signature:

ocas.AlgebraicPolynomial(field: AlgebraicExtension, coeffs: list)

Parameters:

Example:

>>> from ocas import AlgebraicExtension, AlgebraicPolynomial
>>> field = AlgebraicExtension([-2, 0, 1])
>>> # x² - 2 over ℚ(√2)
>>> p = AlgebraicPolynomial(field, [-2, 0, 1])
>>> p.degree()
2

AlgebraicPolynomial.degree

AlgebraicPolynomial.degree() -> int | None

Returns the degree. The zero polynomial returns None.

AlgebraicPolynomial.len

AlgebraicPolynomial.len() -> int

Returns the number of stored coefficients.

AlgebraicPolynomial.is_zero

AlgebraicPolynomial.is_zero() -> bool

Whether the polynomial is the zero polynomial.

AlgebraicPolynomial.coeffs

AlgebraicPolynomial.coeffs() -> list[list[str]]

Returns the coefficient list. Each coefficient is a list of rationals (as strings) representing the $\alpha$-polynomial coefficients.

AlgebraicPolynomial.factor

AlgebraicPolynomial.factor() -> list[AlgebraicFactor]

Factors the polynomial over the algebraic number field (Trager's algorithm).

Returns: a list of AlgebraicFactor, each containing an irreducible factor and its multiplicity.

Example:

>>> field = AlgebraicExtension([-2, 0, 1])
>>> p = AlgebraicPolynomial(field, [-2, 0, 1])  # x² - 2 = (x-α)(x+α)
>>> facs = p.factor()
>>> len(facs)
2
>>> [f.multiplicity for f in facs]
[1, 1]

AlgebraicFactor

A factor in the factorization of an algebraic-number-field polynomial.

Attributes:

Automatic Differentiation

DualShape

First-order dual-number layout description, declaring the number of tracked differentiation variables. Construct once, share everywhere.

Signature:

# Not constructed directly; use the static method
shape = DualShape.first_order(n_vars)

DualShape.first_order (static method)

DualShape.first_order(n_vars: int) -> DualShape

Creates a layout with n_vars differentiation variables.

Parameters:

Exceptions: ValueError — n_vars == 0.

Example:

>>> from ocas import DualShape
>>> shape = DualShape.first_order(3)
>>> shape.n_vars
3
>>> shape.n_components
4

DualShape.n_vars

DualShape.n_vars -> int  # property

Number of differentiation variables.

DualShape.n_components

DualShape.n_components -> int  # property

Total number of components (value + derivative slots).

HyperDual

Hyper-dual number: a scalar value together with partial derivatives with respect to the variables of a DualShape. Computes exactly with rational numbers.

Limitations: supports only polynomial/rational arithmetic (+, -, *, /, negation). Transcendental functions (sin/exp/log) are not implemented; use repeated multiplication for integer powers.

HyperDual.variable (static method)

HyperDual.variable(shape: DualShape, i: int, value) -> HyperDual

Creates an independent variable $x_i = \text{value}$ (derivative 1 with respect to the $i$-th variable, 0 with respect to the others).

Parameters:

Exceptions: ValueError — index out of bounds.

HyperDual.constant (static method)

HyperDual.constant(shape: DualShape, value) -> HyperDual

Creates a constant (all derivatives zero).

Parameters:

HyperDual.value

HyperDual.value() -> str

Returns the scalar value (as a string, e.g. "5" or "3/7").

HyperDual.deriv

HyperDual.deriv(i: int) -> str | None

Returns the partial derivative with respect to the $i$-th variable. Returns None if i is out of bounds.

HyperDual.n_vars

HyperDual.n_vars -> int  # property

Number of differentiation variables.

HyperDual arithmetic

All operations require both operands to share the same DualShape. Different shapes raise ValueError.

Complete example:

>>> from ocas import DualShape, HyperDual
>>> shape = DualShape.first_order(2)
>>> x = HyperDual.variable(shape, 0, 3)
>>> y = HyperDual.variable(shape, 1, 5)
>>> f = x * y
>>> f.value()
'15'
>>> f.deriv(0)   # ∂f/∂x = y
'5'
>>> f.deriv(1)   # ∂f/∂y = x
'3'

Tensors

Tensor

Named tensor object with index slots and optional symmetry.

Signature:

ocas.Tensor(name: str, slots: list[tuple[str, str]], symmetry: str = "none")

Parameters:

Exceptions: ValueError — invalid position or symmetry string.

Example:

>>> from ocas import Tensor
>>> t = Tensor("T", [("i", "upper"), ("j", "lower")])
>>> t.name
'T'
>>> t.rank
2

Tensor.name

Tensor.name -> str  # property

The tensor name.

Tensor.rank

Tensor.rank -> int  # property

The tensor rank (number of slots).

Tensor.symmetry

Tensor.symmetry -> str  # property

The symmetry string ("none", "symmetric", "antisymmetric").

Tensor.slots

Tensor.slots() -> list[tuple[str, str]]

Returns the list of slots, each being (label, position).

Tensor.dummy_labels

Tensor.dummy_labels() -> list[str]

Returns the labels of the current dummy indices (those appearing twice).

Tensor.to_string_atom

Tensor.to_string_atom() -> str

Renders the tensor as the string form of an expression function node name(slot, slot, ...).

contract_tensors

ocas.contract_tensors(a: Tensor, b: Tensor) -> tuple[str, list | str]

Contracts two tensors: sums over shared dummy indices (same label, opposite variance).

Parameters:

Returns: a (kind, payload) tuple:

• when kind = "product", payload is the list of tensors after contraction (free indices concatenated)
• when kind = "scalar", payload is the string of the contracted scalar expression

Example:

>>> from ocas import Tensor, contract_tensors
>>> t = Tensor("T", [("i", "upper"), ("j", "lower")])
>>> u = Tensor("U", [("j", "upper"), ("k", "lower")])
>>> kind, payload = contract_tensors(t, u)
>>> kind
'product'

tensor_symmetrise_sign

ocas.tensor_symmetrise_sign(tensor: Tensor) -> int

Returns the symmetrization sign of the tensor ($+1$ or $-1$). "none" and "symmetric" always return $+1$; "antisymmetric" returns the parity of the slot permutation.

Parameters:

Returns: $+1$ or $-1$.

Example:

>>> from ocas import Tensor, tensor_symmetrise_sign
>>> eps = Tensor("eps", [("a", "lower"), ("b", "lower")], symmetry="antisymmetric")
>>> tensor_symmetrise_sign(eps) in (1, -1)
True

canonicalize_tensors

ocas.canonicalize_tensors(expr: str, specs: dict[str, str], index_groups: dict[str, int] | None = None) -> str

Canonicalizes a tensor expression using the graph isomorphism engine.

Parameters:

Returns: the canonicalized expression string.

Exceptions: ValueError — parsing or canonicalization failed.

young_project

ocas.young_project(expr: str, tableau: list[int]) -> str

Applies a Young projection to a tensor expression.

Parameters:

Returns: the projected expression string.

Example:

>>> proj = ocas.young_project("f(a,b,c)", [1, 1, 1])  # □/□/□ fully antisymmetric projection
>>> "f(a,b,c)" in proj
True

refresh_dummies

ocas.refresh_dummies(expr: str, specs: dict[str, str]) -> str

Renames (refreshes) the dummy indices in a tensor expression.

Parameters:

Returns: the expression string with the dummy indices renamed.

Evaluation

ExpressionEvaluator

Compiles an expression for fast numerical evaluation. Compile once, evaluate many times.

Signature:

ocas.ExpressionEvaluator(input: str, param_names: list[str])

Parameters:

Exceptions: ValueError — parsing or compilation error.

Example:

>>> from ocas import ExpressionEvaluator
>>> ev = ExpressionEvaluator("x^2 + y", ["x", "y"])
>>> ev.evaluate([3.0, 1.0])
[10.0]
>>> ev.evaluate([2.0, 0.0])
[4.0]

ExpressionEvaluator.evaluate

ExpressionEvaluator.evaluate(values: list[float]) -> list[float]

Evaluates with the given parameter values.

Parameters:

Returns: the list of result floats.

Exceptions: ValueError — parameter count mismatch or evaluation error.

ExpressionEvaluator.n_params

ExpressionEvaluator.n_params -> int  # property

The number of parameters.

Numerical Integration

Vegas

Adaptive Monte Carlo integrator (the Vegas algorithm), supporting multi-dimensional integrals.

Signature:

ocas.Vegas(n_dims: int, *, n_bins=None, n_samples=None, iterations=None, learning_rate=None, seed=None)

Parameters:

Example:

>>> from ocas import Vegas
>>> v = Vegas(2, n_samples=20000, iterations=8, seed=1)
>>> r = v.integrate(lambda xs: xs[0] * xs[1])
>>> abs(r.integral - 0.25) < 0.01
True

Vegas.integrate

Vegas.integrate(f: Callable[[list[float]], float]) -> IntegrateResult

Integrates the callable $f$ over the unit hypercube $[0, 1]^n$.

Parameters:

Returns: an IntegrateResult.

Vegas.result

Vegas.result -> IntegrateResult  # property

The latest accumulated estimate and error.

Vegas.iterations

Vegas.iterations -> int  # property

The number of completed iterations.

integrate_1d

ocas.integrate_1d(f: Callable[[float], float], a: float, b: float, *, n_bins=None, n_samples=None, iterations=None, learning_rate=None, seed=None) -> IntegrateResult

Convenience function for one-dimensional numerical integration.

Parameters:

Returns: an IntegrateResult.

Example:

>>> import ocas
>>> r = ocas.integrate_1d(lambda x: x, 0.0, 1.0)
>>> abs(r.integral - 0.5) < 0.01
True

IntegrateResult

The result of a numerical integration.

Attributes:

Supports indexing: result[0] = integral, result[1] = error; supports unpacking: integral, error = result.

Example:

>>> import ocas
>>> r = ocas.integrate_1d(lambda x: x**2, 0.0, 1.0, seed=42)
>>> r[0]       # integral
0.333...
>>> r[1]       # error
0.00...
>>> i, e = r   # unpacking

Double-Precision Floats

DoubleF64

Double-precision floating-point arithmetic (~31 significant decimal digits, ~84 binary bits), using the Dekker/Knuth "double-float" algorithm.

Signature:

ocas.DoubleF64(hi: float, lo: float = 0.0)

Parameters:

Example:

>>> from ocas import DoubleF64
>>> a = DoubleF64(1.0)
>>> b = DoubleF64(2.0)
>>> str(a + b)
'3'

DoubleF64.to_f64

DoubleF64.to_f64() -> float

Converts to a standard float (loses the precision of the error term).

DoubleF64.components

DoubleF64.components() -> tuple[float, float]

Returns the (hi, lo) tuple.

DoubleF64 arithmetic

Exceptions: ValueError — division by zero (__truediv__).

DoubleF64 transcendental functions

Complete example:

>>> from ocas import DoubleF64
>>> DoubleF64(0.0).sin().to_f64()
0.0
>>> DoubleF64(4.0).sqrt().components()
(2.0, 0.0)

Function Quick Reference

Class Quick Reference