Analytic operators

Main authors: Simon Rohou, Damien Massé

Codac provides a list of operators for calculating intervals, defining expressions and constructing contractors.

Operators currently available

The following table lists the mathematical operators currently available. The availability is indicated for four operations:

Natural forward evaluation
Centered-form forward evaluation
Differentiation
Backward (reverse) evaluation

When operators are available for operations 2–3, then an AnalyticFunction can be built upon them and the .eval(EvalMode.CENTERED, ...) and .diff(...) methods can be successfully called. When operators are available for operation 4, then analytic contractors such as CtcInverse will work.

Only the ✓ operators are supported at the moment. If you notice any mathematical operators missing from the list below, feel free to contribute to the library. You can submit your suggestions or pull requests on the GitHub repository of Codac.

The sources of the operators are available in the operators folder:

https://github.com/codac-team/codac/blob/codac2/src/core/operators

List of available operators in Codac
Operator	Syntax	Struct	Operands type	Fwd eval.			Bwd. eval.
Operator	Syntax	Struct	Operands type	Natur.	Centr.	Diff.	Bwd. eval.
Unary operations
\(\|x\|\)	`abs(x)`	`AbsOp`	`x`: scalar	✓	✓	✓	✓
\(\arccos(x)\)	`acos(x)`	`AcosOp`	`x`: scalar	✓	✓	✓	✓
\(\arcsin(x)\)	`asin(x)`	`AsinOp`	`x`: scalar	✓	✓	✓	✓
\(\arctan(x)\)	`atan(x)`	`AtanOp`	`x`: scalar	✓	✓	✓	✓
\(\lceil x \rceil\)	`ceil(x)`	`CeilOp`	`x`: scalar	✓	✗	✗	✓
\(\cos(x)\)	`cos(x)`	`CosOp`	`x`: scalar	✓	✓	✓	✓
\(\cosh(x)\)	`cosh(x)`	`CoshOp`	`x`: scalar	✓	✓	✓	✓
\(\det(\mathbf{A})\)	`det(A)`	`DetOp`	`A`: matrix	✓	✓	✓	✓
\(\exp(x)\)	`exp(x)`	`ExpOp`	`x`: scalar	✓	✓	✓	✓
\(\lfloor x \rfloor\)	`floor(x)`	`FloorOp`	`x`: scalar	✓	✗	✗	✓
\(\log(x)\)	`log(x)`	`LogOp`	`x`: scalar	✓	✓	✓	✓
\(\mathrm{sgn}(x)\)	`sign(x)`	`SignOp`	`x`: scalar	✓	✓	✓	✓
\(\sin(x)\)	`sin(x)`	`SinOp`	`x`: scalar	✓	✓	✓	✓
\(\sinh(x)\)	`sinh(x)`	`SinhOp`	`x`: scalar	✓	✓	✓	✓
\(x^2\)	`sqr(x)`	`SqrOp`	`x`: scalar	✓	✓	✓	✓
\(\sqrt{x}\)	`sqrt(x)`	`SqrtOp`	`x`: scalar	✓	✓	✓	✓
\(\tan(x)\)	`tan(x)`	`TanOp`	`x`: scalar	✓	✓	✓	✓
\(\tanh(x)\)	`tanh(x)`	`TanhOp`	`x`: scalar	✓	✓	✓	✓
\(\mathrm{flatten}(\mathbf{X})\)	`flatten(X)`	`FlattenOp`	`X`: matrix	✓	✓	✓	✓
\(\mathbf{X}^\intercal\)	`transpose(x)`	`TransposeOp`	`X`: matrix	✓	✓	✓	✓
Binary operations
\(x_1+x_2\)	`x1+x2`	`AddOp`	`x1`, `x2`: scalar	✓	✓	✓	✓
\(\mathbf{x}_1+\mathbf{x}_2\)	`x1+x2`		`x1`, `x2`: vector	✓	✓	✓	✓
\(\mathbf{X}_1+\mathbf{X}_2\)	`X1+X2`		`x1`, `x2`: matrix	✓	✓	✓	✓

\(x_1-x_2\)	`x1-x2`	`SubOp`	`x1`, `x2`: scalar	✓	✓	✓	✓
\(\mathbf{x}_1-\mathbf{x}_2\)	`x1-x2`		`x1`, `x2`: vector	✓	✓	✓	✓
\(\mathbf{X}_1-\mathbf{X}_2\)	`X1-X2`		`x1`, `x2`: matrix	✓	✓	✓	✓

\(x_1\cdot x_2\)	`x1*x2`	`MulOp`	`x1`, `x2`: scalar	✓	✓	✓	✓
\(x_1\cdot\mathbf{x}_2\)	`x1*x2`		`x1`: scalar, `x2`: vector	✓	✓	✓	✓
\(\mathbf{x}_1\cdot x_2\)	`x1*x2`		`x1`: vector, `x2`: scalar	✓	✓	✓	✓
\(x_1\cdot\mathbf{X}_2\)	`x1*X2`		`x1`: scalar, `X2`: matrix	✓	✓	✓	✗
\(\mathbf{x}_1\cdot\mathbf{x}_2\)	`x1*x2`		`x1`: row, `x2`: vector	✓	✗	✗	✓
\(\mathbf{X}_1\cdot\mathbf{x}_2\)	`X1*x2`		`X1`: matrix, `x2`: vector	✓	✓	✓	✓
\(\mathbf{X}_1\cdot\mathbf{X}_2\)	`X1*X2`		`X1`: matrix, `X2`: matrix	✓	✓	✓	✗

\(x_1/x_2\)	`x1/x2`	`DivOp`	`x1`, `x2`: scalar	✓	✓	✓	✓
\(\mathbf{x}_1/x_2\)	`x1/x2`		`X1`: vector, `x2`: scalar	✓	✓	✓	✓
\(\mathbf{X}_1/x_2\)	`X1/x2`		`X1`: matrix, `x2`: scalar	✓	✓	✓	✓

\(\mathbf{x}_1\times\mathbf{x}_2\)	`cross_prod(x1,x2)`	`CrossProdOp`	`x1`, `x2`: vector	✓	✓	✓	✗
\(\max(x_1,x_2)\)	`max(x1,x2)`	`MaxOp`	`x1`, `x2`: scalar	✓	✓	✓	✓
\(\min(x_1,x_2)\)	`min(x1,x2)`	`MinOp`	`x1`, `x2`: scalar	✓	✓	✓	✓
\(x_1\mod p\)	`mod(x1,p)`	`ModOp`	`x1`, `p`: scalar	✓	✗	✗	✓
\((x_1)^{x_2}\)	`pow(x1,x2)` `x1**x2` (py)	`PowOp`	`x1`, `x2`: scalar	✓	✓	✓	✓
\(\mathrm{arctan2}(y,x)\)	`atan2(y,x)`	`Atan2Op`	`y`, `x`: scalar	✓	✓	✓	✓
\(\begin{split}f(x) \textrm{ if } x \in D_f,\\ g(x) \textrm{ otherwise}\end{split}\)	`extend(fx,gx)`	`ExtendOp`	`fx`, `gx`: any (same types)	✓	✓	✓	✓
Ternary operations
\(\begin{split}\chi(x_1,x_2,x_3) =\\ \begin{cases}x_2 & \text{if } x_1 \leqslant 0, \\x_3 & \text{if } x_1>0.\end{cases}\end{split}\)	`chi(x1,x2,x3)`	`ChiOp`	`x1`: scalar, `x2`, `x3`: any (same types)	✓	✓	✓	✓
Vectorial / matricial operations
\(x_i\) (vector coeff)	`x[i]`	`ComponentOp`	`x`: vector, `i`: scalar	✓	✓	✓	✓
\(X_{ij}\) (mat. coeff)	`X(i,j)`	`ComponentOp`	`X`: matrix, `i`, `j`: scalar	✓	✓	✓	✓
\(\mathbf{x}_{i:j}\) (subvector)	`x.subvector(i,j)`	`SubvectorOp`	`x`: vector expression `i`, `j`: scalar	✓	✓	✓	✓
\([x_1,x_2,\dots]^\intercal\)	`vec(x1,x2,...)`	`VectorOp`	`x1`, `...`: scalar	✓	✓	✓	✓
\(\left(\mathbf{x}_1,\mathbf{x}_2,\dots\right)\)	`mat(x1,x2,...)`	`MatrixOp`	`x1`, `...`: vector	✓	✓	✓	✗
\(\sigma(\mathbf{x})\)	`s(x)`	`OctaSymOp`	`s`: action, `x`: vector	✓	✓	✓	✓
Temporal operations
\(\mathbf{x}(t)\)	`x(t)`	`TrajectoryOp`	`x`: trajectory, `t`: scalar	✓	✗	✗	✗
\([\mathbf{x}](t)\)	`x(t)`	`TubeOp`	`x`: tube, `t`: scalar	✓	✗	✗	✗

Note: the operator \(\det\) is only available for \(1\times 1\) and \(2\times 2\) matrices.

Note: the operator \(\bmod\) is only available for real periods (double precision), interval periods are not yet supported.

Why `^` is disabled in Codac

The ^ syntax is intentionally disabled in Codac for powers. Although this operator can be overloaded, its precedence remains the one of the bitwise XOR operator, both in Python and in C++. Overloading an operator does not change the precedence rules of the host language.

As a consequence, an expression such as x^2 + sin(x) is parsed as x^(2 + sin(x)), not as (x^2) + sin(x). This kind of ambiguity is easy to overlook and may silently produce an expression different from the one intended by the user.

To avoid such error-prone expressions, Codac does not provide ^ as a power syntax. Use:

pow(x1,x2) for generic powers;
x1**x2 in Python when exponentiation syntax is preferred;
sqr(x1) for squares when applicable (it is equivalent to pow(x1,2)).

Examples:

x = ScalarVar()
f = AnalyticFunction([x], x**2 + sin(x))
g = AnalyticFunction([x], pow(x,2) + sin(x))

ScalarVar x;
AnalyticFunction f({x}, pow(x,2) + sin(x));
AnalyticFunction g({x}, sqr(x) + sin(x));

Expressions involving a non-supported centered-form operation

If an operator, for which the centered form is not defined, is involved in an expression, then this expression cannot be evaluated using the centered form (calculation is disabled for the entire operation). A simple natural evaluation will then be computed.

Expressions involving a temporal operator

Temporal operations for involving trajectories or tubes in analytic expressions require an intermediate operation:

x = # some sampled trajectory...
g = x.as_function() # intermediate operation

t = ScalarVar()
h = AnalyticFunction(
  [t], g(t)
)

x = // some sampled trajectory...
g = x.as_function(); // intermediate operation

ScalarVar t;
AnalyticFunction h(
  {t}, g(t)
);

Direct use of operators

Operators can be used directly without building an AnalyticFunction. They are organized in structures named <OperatorCode>Op and each structure provides .fwd() and .bwd() methods. For example, the operator cos is proposed with:

class CosOp:

  @staticmethod
  def fwd(x1):
    # Default natural forward evaluation
    # ...

  @staticmethod
  def bwd(y, x1):
    # Backward evaluation
    # ...

struct CosOp
{
  // Default natural forward evaluation
  static Interval fwd(const Interval& x1);

  // Backward evaluation
  static void bwd(const Interval& y, Interval& x1);
};

For the names of available structures, please refer to Table List of available operators in Codac.

An example of use of CosOp is given below:

# Forward evaluation
y = CosOp.fwd([0,PI/2]) # y = [0,1]

# Backward evaluation
x = Interval(0,PI) # prior value of [x]
CosOp.bwd([0,0.5], x) # [x] is contracted to [PI/3,PI/2]

// Forward evaluation
Interval y = CosOp::fwd({0,PI/2}); // y = [0,1]

// Backward evaluation
Interval x(0,PI); // prior value of [x]
CosOp::bwd({0,0.5}, x); // [x] is contracted to [PI/3,PI/2]

% Forward evaluation
y = CosOp().fwd(Interval(0,PI/2)); % y = [0,1]

% Backward evaluation
x = Interval(0,PI); % prior value of [x]
CosOp().bwd(Interval(0,0.5), x); % [x] is contracted to [PI/3,PI/2]