Operator

class pathsim.optim.operator.Operator(func, jac=None)

Bases: object

Operator class for function evaluation and linearization.

This class wraps a function to provide both direct evaluation and linear approximation capabilities. When linearized around a point x0, subsequent calls use the first-order Taylor approximation

\[f(x) \approx f(x_0) + \mathbf{J}(x_0) (x - x_0)\]

instead of evaluating the function.

The class supports multiple methods for Jacobian computation: user-provided analytical Jacobians, automatic differentiation via the Value class, and numerical differentiation as a fallback.

Example

Basic usage with automatic differentiation:

def f(x):
    return x**2 + np.sin(x)

op = Operator(f)

# Direct function evaluation
y1 = op(2.0)

# Linearize at current point
op.linearize(2.0)

# Use linear approximation
y2 = op(2.1)  # Returns f(2.0) + J(2.0) (2.1-2.0)

With user-provided Jacobian:

def f(x):
    return x**2 + np.sin(x)

def df_dx(x):
    return 2*x + np.cos(x)

op = Operator(f, jac=df_dx)

op.linearize(2.0)  # Uses df_dx for Jacobian

Parameters:

• func (callable) – The function to wrap

• jac (callable, optional) – Optional analytical Jacobian of func. If None, automatic or numerical differentiation will be used.

f0

function evaluation at operating point

Type:

array_like

x0

operating point

Type:

array_like

J

jacobian matrix at operating point

Type:

array_like

jac(x)

Compute the Jacobian matrix at point x.

Uses the following methods in order of preference: 1. User-provided analytical Jacobian if available 2. Automatic differentiation via Value class 3. Numerical differentiation as fallback

Parameters:

x (array_like) – Point at which to evaluate the Jacobian

Returns:

jacobian – Jacobian matrix at x

Return type:

ndarray

linearize(x)

Linearize the function at point x.

Computes and stores both the function value and its Jacobian at x. After linearization, calls to the operator will use the linear approximation until reset() is called.

Parameters:

x (array_like) – Point at which to linearize the function

reset()

Reset the linearization.

Clears the stored linearization point and Jacobian, causing the operator to evaluate the function directly on subsequent calls.

class pathsim.optim.operator.DynamicOperator(func, jac_x=None, jac_u=None)

Bases: object

Operator class for dynamic system function evaluation and linearization.

This class wraps a dynamic system function with signature f(x, u, t) to provide both direct evaluation and linear approximation capabilities. When linearized around operating points (x0, u0), subsequent calls use the first-order Taylor approximation

\[f(x, u, t) \approx f(x_0, u_0, t) + J_x(x_0, u_0, t) (x - x_0) + J_u(x_0, u_0, t) (u - u_0)\]

instead of evaluating the function.

The class supports multiple methods for Jacobian computation: user-provided analytical Jacobians, automatic differentiation via the Value class, and numerical differentiation as a fallback.

Example

Basic usage with automatic differentiation:

def system(x, u, t):
    return -0.5*x + 2*u

op = Operator(system)

# Direct function evaluation
y1 = op(x=1.0, u=0.5, t=0.0)

# Linearize at current point
op.linearize(x=1.0, u=0.5, t=0.0)

# Use linear approximation
y2 = op(x=1.1, u=0.6, t=0.1)

With user-provided Jacobians:

def system(x, u, t):
    return -0.5*x + 2*u

def jac_x(x, u, t):
    return -0.5

def jac_u(x, u, t):
    return 2.0

op = Operator(system, jac_x=jac_x, jac_u=jac_u)

op.linearize(x=1.0, u=0.5, t=0.0)

Parameters:

• func (callable) – The function to wrap with signature func(x, u, t)

• jac_x (callable, optional) – Optional analytical Jacobian with respect to x. If None, automatic or numerical differentiation will be used.

• jac_u (callable, optional) – Optional analytical Jacobian with respect to u. If None, automatic or numerical differentiation will be used.

f0

Function evaluation at operating point

Type:

array_like

x0

State operating point

Type:

array_like

u0

Input operating point

Type:

array_like

Jx

Jacobian matrix with respect to x at operating point

Type:

array_like

Ju

Jacobian matrix with respect to u at operating point

Type:

array_like

jac_x(x, u, t)

Compute the Jacobian matrix with respect to x.

Uses the following methods in order of preference: 1. User-provided analytical Jacobian if available 2. Automatic differentiation via Value class 3. Numerical differentiation as fallback

Parameters:

• x (array_like) – State vector

• u (array_like) – Input vector

• t (float) – Time

Returns:

jacobian – Jacobian matrix with respect to x

Return type:

ndarray

jac_u(x, u, t)

Compute the Jacobian matrix with respect to u.

Uses the following methods in order of preference: 1. User-provided analytical Jacobian if available 2. Automatic differentiation via Value class 3. Numerical differentiation as fallback

Parameters:

• x (array_like) – State vector

• u (array_like) – Input vector

• t (float) – Time

Returns:

jacobian – Jacobian matrix with respect to u

Return type:

ndarray

linearize(x, u, t)

Linearize the function at point (x, u, t).

Computes and stores the function value and Jacobians at the operating point. After linearization, calls to the operator will use the linear approximation until reset() is called.

Parameters:

• x (array_like) – State vector

• u (array_like) – Input vector

• t (float) – Time

reset()

Reset the linearization.

Clears the stored linearization points and Jacobians, causing the operator to evaluate the function directly on subsequent calls.