dymad.utils.sampling

Module Attributes

CTRL_MAP	Mapping of control sampler names to functions.
X0_MAP	Mapping of initial condition sampler names to functions.

Functions

chirp_control(*, t1, dim[, freq_range, ...])	Generate a chirp control signal.
gaussian_control(*, mean, std, t1, dt, dim)	Generate a Gaussian control signal.
gaussian_noise(*, mean, std, dim[, rng])	Generate additive Gaussian observation noise.
gaussian_x0(*, mean, std, dim[, rng])	Generate a Gaussian initial condition sampler.
grid_x0(*, bounds, dim[, n_points, rng])	Generate a grid-based initial condition sampler.
laplace_noise(*, loc, scale, dim[, rng])	Generate additive Laplace observation noise.
perturb_x0(*, bounds, dim, ref[, rng])	Generate a uniformly random initial condition sampler around a reference trajectory.
sine_control(*, dim[, num_components, ...])	Generate a sine control signal with multiple components.
sphere_control(*, radius, t1, dt, dim[, ...])	Generate a control signal on the surface of a sphere.
student_t_noise(*, df[, loc, scale, rng])	Generate additive Student-t observation noise.
uniform_noise(*, bounds, dim[, rng])	Generate additive uniform observation noise.
uniform_x0(*, bounds, dim[, rng])	Generate a uniformly random initial condition sampler.

Classes

TrajectorySampler(f[, g, config, rng, ...])

Sampler for generating trajectories.

dymad.utils.sampling.CTRL_MAP = {'chirp': <function chirp_control>, 'gaussian': <function gaussian_control>, 'sine': <function sine_control>, 'sphere': <function sphere_control>}

Mapping of control sampler names to functions.

class dymad.utils.sampling.TrajectorySampler(f, g=None, config=None, rng=None, config_mod=None)

Bases: object

Sampler for generating trajectories.

This class generates batches of trajectories based on a system defined by the functions f and g, which represent the system dynamics and observation model, respectively. The trajectories are sampled according to the configuration specified in the provided YAML file or dictionary.

The dynamics are

With input:

\[\begin{split}\begin{align*} \dot{x} &= f(t, x, u) \\ y &= g(t, x, u) \end{align*}\end{split}\]

Without input:

\[\begin{split}\begin{align*} \dot{x} &= f(t, x) \\ y &= g(t, x) \end{align*}\end{split}\]

Parameters:

• f (Callable[[float, Array, Array], Array]) – Function defining the system dynamics. It should take time t, state x, and control input u as arguments and return the state derivative. Or just f(t, x) if the system is autonomous (no control input).

• g (Callable[[float, Array, Array], Array], optional) – Function defining the observation model. It should take time t, state x, and control input u as arguments and return the observation. If not provided, it defaults to the identity function (g(t, x, u) = x). Or just g(t, x) if the system is autonomous (no control input).

• config (Union[str, Dict], optional) – Path to a YAML configuration file or a dictionary containing the configuration for the sampler. The configuration should specify the dimensions of the states, inputs, and observations, as well as control and initial condition specifications.

• rng (Union[int, np.random.Generator, None], optional) – Random number generator or seed for reproducibility. If an integer is provided, it is used to seed the default random number generator. If None, the default random generator is used.

• config_mod (Dict, optional) – Additional configuration parameters to modify the loaded configuration. This should be a dictionary that updates or overrides the values in the loaded configuration.

dymad.utils.sampling.X0_MAP = {'gaussian': <function gaussian_x0>, 'grid': <function grid_x0>, 'perturb': <function perturb_x0>, 'uniform': <function uniform_x0>}

Mapping of initial condition sampler names to functions.

dymad.utils.sampling.chirp_control(*, t1, dim, freq_range=(0.1, 2.0), amp_range=(0.5, 1.0), phase_range=(0.0, 360.0), method='linear', rng=None)

Generate a chirp control signal.

See scipy.signal.chirp for technical details.

Parameters:

• t1 (float) – The time at which f1 is specified, which can be shorter than the duration of signal.

• dim (int) – Dimension of the control signal.

• freq_range (Tuple[float, float]) – Frequency range (f0, f1) in Hz.

• amp_range (Tuple[float, float]) – Amplitude range (min, max).

• phase_range (Tuple[float, float]) – Phase range (min, max) in degrees. Default is (0, 360).

• method (str) – Method for temporal variation in frequency.

• rng (np.random.Generator) – Random number generator for sampling.

Returns:

A callable that takes a time grid and returns the chirp signal.

Return type:

Callable

dymad.utils.sampling.gaussian_control(*, mean, std, t1, dt, dim, mode='zoh', rng=None)

Generate a Gaussian control signal.

Parameters:

• mean (Union[float, Array]) –

  Mean of the Gaussian distribution.

  • If scalar, it is broadcasted to the dimension.

  • If an array, it should have shape (dim,).

• std (Union[float, Array]) –

  Standard deviation of the Gaussian distribution.

  • If scalar, it is broadcasted to the dimension.

  • If an array, it should have shape (dim,).

• t1 (float) – End time of the Gaussian signal.

• dt (float) – Time step for the Gaussian signal.

• dim (int) – Dimension of the control signal.

• mode (str) – Interpolation mode (‘zoh’, ‘linear’, ‘cubic’).

• rng (np.random.Generator) – Random number generator for sampling.

Returns:

A callable that takes a time grid and returns the Gaussian signal.

Return type:

Callable

dymad.utils.sampling.gaussian_noise(*, mean, std, dim, rng=None)

Generate additive Gaussian observation noise.

Return type:

Callable[[ndarray, int], ndarray]

dymad.utils.sampling.gaussian_x0(*, mean, std, dim, rng=None)

Generate a Gaussian initial condition sampler.

Parameters:

• mean (Union[float, Array]) –

  Mean of the Gaussian distribution.

  • If scalar, it is broadcasted to the dimension.

  • If an array, it should have shape (dim,).

• std (Union[float, Array]) –

  Standard deviation of the Gaussian distribution.

  • If scalar, it is broadcasted to the dimension.

  • If an array, it should have shape (dim,).

• dim (int) – Dimension of the initial condition.

• rng (np.random.Generator) – Random number generator for sampling.

Returns:

A callable that returns a sample from the Gaussian distribution.

Return type:

Callable

dymad.utils.sampling.grid_x0(*, bounds, dim, n_points=3, rng=None)

Generate a grid-based initial condition sampler.

Parameters:

• bounds (Union[float, Array]) –

  Bounds for the grid sampling.

  • If scalar, it is broadcasted to the dimension.

  • If an array, it should have shape (dim,2).

• dim (int) – Dimension of the initial condition.

• n_points (int) – Number of points in the grid for each dimension.

• rng (np.random.Generator) – Random number generator for sampling.

Returns:

A callable that takes an index and returns a sample from the grid-based initial condition.

Return type:

Callable

dymad.utils.sampling.laplace_noise(*, loc, scale, dim, rng=None)

Generate additive Laplace observation noise.

Return type:

Callable[[ndarray, int], ndarray]

dymad.utils.sampling.perturb_x0(*, bounds, dim, ref, rng=None)

Generate a uniformly random initial condition sampler around a reference trajectory.

Parameters:

• bounds (Union[float, Array]) –

  Bounds for the uniform sampling.

  • If scalar, it is broadcasted to the dimension.

  • If an array, it should have shape (dim,2).

• dim (int) – Dimension of the initial condition.

• ref (Array) – Reference trajectory to perturb, shape (n_steps, dim).

• rng (np.random.Generator) – Random number generator for sampling.

Returns:

A callable that takes an index and returns a perturbed sample.

Return type:

Callable

dymad.utils.sampling.sine_control(*, dim, num_components=1, freq_range=(0.1, 2.0), amp_range=(0.5, 1.0), phase_range=(0.0, 360.0), rng=None)

Generate a sine control signal with multiple components.

Parameters:

• dim (int) – Dimension of the control signal.

• num_components (int) – Number of sine components.

• freq_range (Tuple[float, float]) – Frequency range (f_min, f_max) in Hz.

• amp_range (Tuple[float, float]) – Amplitude range (min, max).

• phase_range (Tuple[float, float]) – Phase range (min, max) in degrees. Default is (0, 360).

• rng (np.random.Generator) – Random number generator for sampling.

Returns:

A callable that takes a time grid and returns the sine signal.

Return type:

Callable

dymad.utils.sampling.sphere_control(*, radius, t1, dt, dim, mode='zoh', rng=None)

Generate a control signal on the surface of a sphere.

Parameters:

• radius (Union[float, Array]) –

  Radius of the sphere.

  • If scalar, it is broadcasted to the dimension.

  • If an array, it should have shape (dim,).

• t1 (float) – End time of the control signal.

• dt (float) – Time step for the control signal.

• dim (int) – Dimension of the control signal.

• mode (str) – Interpolation mode (‘zoh’, ‘linear’, ‘cubic’).

• rng (np.random.Generator) – Random number generator for sampling.

Returns:

A callable that takes a time grid and returns the control signal on the sphere.

Return type:

Callable

dymad.utils.sampling.student_t_noise(*, df, loc=0.0, scale=1.0, dim, rng=None)

Generate additive Student-t observation noise.

Return type:

Callable[[ndarray, int], ndarray]

dymad.utils.sampling.uniform_noise(*, bounds, dim, rng=None)

Generate additive uniform observation noise.

Return type:

Callable[[ndarray, int], ndarray]

dymad.utils.sampling.uniform_x0(*, bounds, dim, rng=None)

Generate a uniformly random initial condition sampler.

Parameters:

• bounds (Union[float, Array]) –

  Bounds for the uniform sampling.

  • If scalar, it is broadcasted to the dimension.

  • If an array, it should have shape (dim,2).

• dim (int) – Dimension of the initial condition.

• rng (np.random.Generator) – Random number generator for sampling.

Returns:

A callable that takes an index and returns a sample from the uniform distribution.

Return type:

Callable