API Reference

Simulation

class pybounds.Simulator(f, h, dt=0.01, discrete=False, n=None, m=None, state_names=None, input_names=None, measurement_names=None, params_simulator=None, mpc_horizon=10)

Bases: object

simulator_tvp_function(t)

Set the set-point function for MPC simulator. :type t: :param t: current time

mpc_tvp_function(t)

Set the set-point function for MPC optimizer.

set_initial_state(x0)

Update the initial state.

update_dict(data=None, name=None)

Update.

simulate(x0=None, u=None, aux=None, mpc=False, return_full_output=False)

Simulate the system.

Parameters:

• x0 – initial state dict or array

• u – input dict or array, if True then mpc must be None

• aux – auxiliary input

• mpc – boolean to run MPC, if True then u must be None

• return_full_output – boolean to run (time, x, u, y) instead of y

plot(name='x', dpi=150, plot_kwargs=None)

Plot states, inputs.

Observability

class pybounds.EmpiricalObservabilityMatrix(simulator, x0, u, aux=None, eps=1e-05, parallel=False, z_function=None, z_state_names=None)

Bases: object

run(parallel=None)

Construct empirical observability matrix.

simulate(n)

Run the simulator for specified state index (n).

class pybounds.SlidingEmpiricalObservabilityMatrix(simulator, t_sim, x_sim, u_sim, aux_list=None, w=None, eps=1e-05, parallel_sliding=False, parallel_perturbation=False, simulator_factory=None, n_workers=None, z_function=None, z_state_names=None)

Bases: object

run(parallel_sliding=None)

Run.

class pybounds.FisherObservability(O, R=None, lam=None, force_R_scalar=False, states=None, sensors=None, time_steps=None, w=None)

Bases: object

set_noise_covariance(R=None)

Set the measurement noise covariance matrix.

class pybounds.SlidingFisherObservability(O_list, R=None, lam=1000000.0, time=None, states=None, sensors=None, time_steps=None, w=None)

Bases: object

pybounds.compute_observability(simulator, t_sim, x_sim, u_sim, R, w=6, eps=0.0001, lam=1e-08, use_jax=False)

Compute sliding-window Fisher observability in one call.

Parameters:

• simulator (Simulator or JaxSimulator) – A configured simulator instance. Pass a JaxSimulator when use_jax=True.

• t_sim (trajectory returned by simulator.simulate(..., return_full_output=True))

• x_sim (trajectory returned by simulator.simulate(..., return_full_output=True))

• u_sim (trajectory returned by simulator.simulate(..., return_full_output=True))

• R (dict — sensor noise covariance, e.g. {'r': 0.1})

• w (int — sliding window length (time steps))

• eps (float — finite-difference perturbation size (ignored when use_jax=True))

• lam (float — Chernoff regularization for Fisher inversion)

• use_jax (bool — if True, use JAX autodiff (exact Jacobians, faster for many windows).) – Requires JAX to be installed and simulator to be a JaxSimulator whose f and h functions are written with jax.numpy (jnp) instead of numpy. See JaxSimulator for details.

Returns:

• DataFrame with columns ‘time’, ‘time_initial’, and one column per state

• containing the minimum error variance for each sliding window.

Visualisation

class pybounds.ObservabilityMatrixImage(O, state_names=None, sensor_names=None, vmax_percentile=100, vmin_ratio=1.0, cmap='bwr')

Bases: object

plot(vmax_percentile=100, vmin_ratio=0.0, vmax_override=None, cmap='bwr', grid=True, scale=1.0, dpi=150, ax=None)

Plot the observability matrix.

pybounds.colorline(x, y, z, ax=None, cmap=<matplotlib.colors.LinearSegmentedColormap object>, norm=None, linewidth=1.5, alpha=1.0)

pybounds.plot_heatmap_log_timeseries(data, ax=None, log_ticks=None, data_labels=None, cmap='inferno_r', y_label=None, aspect=0.25, interpolation=False)

Plot log-scale time-series as heatmap.

Utilities

class pybounds.SymbolicJacobian(func, state_vars)

Bases: object

get_jacobian_function()

Returns a numerical function to evaluate the Jacobian at specific values of x and u.

Returns:

A function that calculates the Jacobian matrix given values of x and u. The function takes numpy arrays x and u as inputs.

pybounds.transform_states(O=None, square_flag=False, z_function=None, x0=None, z_state_names=None)

Transform the coordinates of an observability matrix (O) or Fisher information matrix (F) from the original coordinates (x) to new user defined coordinates (z).

Parameters:

• O – observability matrix or Fisher information matrix

• square_flag (boolean) – whether to square the transform Jacobian or not should be set to False if passing squared an observability matrix as O should be set to True if passing squared a Fisher information matrix as O

• z_function (callable) – function that transforms coordinates from original to new states must be of the form z = z_function(x), where x & z are the same size should use sympy functions wherever possible

• x0 (np.array) – initial state in original coordinates

• z_state_names (list | tuple) – (optional) names of states in new coordinates. will only have an effect if O or F is a data-frame

Returns:

Z: observability matrix or Fisher information matrix in transformed coordinates dzdx: numerical Jacobian dz/dx (inverse of dx/dz) evaluated at x0 dxdz_sym: symbolic Jacobian dx/dz

JAX Backend (optional)

The JAX backend provides exact autodiff Jacobians via jax.jacfwd and batched window computation via jax.vmap. Requires pip install pybounds[jax] and dynamics/measurement functions written with jax.numpy.

class pybounds.JaxSimulator(f_jax, h_jax, dt, state_names, input_names, measurement_names, integrator='rk4')

Bases: object

Open-loop forward simulator implemented in pure JAX.

Uses jax.lax.scan over RK4 (or Euler) time steps so the simulation function is fully JAX-traceable. This makes the measurement trajectory Y differentiable with respect to the initial state x₀ via jax.jacfwd.

Parameters:

• f_jax (callable) – Dynamics function f_jax(x, u) -> x_dot. x and u are 1-D jnp arrays; return value must also be a jnp array of shape (n,).

• h_jax (callable) – Measurement function h_jax(x, u) -> y. Returns a jnp array of shape (p,).

• dt (float) – Integration time step (seconds).

• state_names (list of str) – Names of state variables (length n).

• input_names (list of str) – Names of input variables (length m).

• measurement_names (list of str) – Names of measurement variables (length p).

• integrator ({'rk4', 'euler'}) – Numerical integration scheme. 'rk4' is more accurate and recommended; 'euler' is faster but first-order.

simulate(x0, u_seq)

Run the open-loop simulation.

Parameters:

• x0 (array-like or dict) – Initial state, shape (n,) or dict mapping state name → value.

• u_seq (array-like or dict) – Input sequence, shape (w, m) or dict mapping input name → array of length w.

Returns:

y_traj – Measurement trajectory.

Return type:

np.ndarray, shape (w, p)

class pybounds.JaxEmpiricalObservabilityMatrix(jax_simulator, x0, u_seq, eps=None)

Bases: object

Observability matrix via JAX forward-mode autodiff.

Replaces the 2n numerical perturbation simulations used by EmpiricalObservabilityMatrix with a single jax.jacfwd call, giving the exact Jacobian dY/dx₀ in one forward pass.

Output attributes match those of EmpiricalObservabilityMatrix so this class can be used as a drop-in replacement.

Parameters:

• jax_simulator (JaxSimulator) – A configured JaxSimulator instance.

• x0 (array-like or dict) – Initial state, shape (n,) or dict.

• u_seq (array-like or dict) – Input sequence, shape (w, m) or dict.

• eps (float, optional) – Accepted for API compatibility but not used (the Jacobian is exact).

class pybounds.JaxSlidingEmpiricalObservabilityMatrix(jax_simulator, t_sim, x_sim, u_sim, w)

Bases: object

Sliding observability matrix computed via JAX vmap + jacfwd.

Batches all sliding windows into a single vmapped jax.jacfwd call, giving exact Jacobians for every window in one XLA kernel launch.

Output attributes match those of SlidingEmpiricalObservabilityMatrix (O_sliding, O_df_sliding, O_time, O_index, t_sim).

Parameters:

• jax_simulator (JaxSimulator) – A configured JaxSimulator instance.

• t_sim (array-like, shape (T,)) – Time vector for the trajectory.

• x_sim (array-like or dict, shape (T, n)) – State trajectory.

• u_sim (array-like or dict, shape (T, m)) – Input trajectory.

• w (int) – Window size in time steps.

get_observability_matrix()

Return a copy of the sliding O_df list.