ngclearn.utils.diffeq package

Submodules

ngclearn.utils.diffeq.ode_utils module

Routines and co-routines for ngc-learn’s differential equation integration backend.

Currently supported back-end forms of integration in ngc-learn include:

0) Euler integration (RK-1);

1) Midpoint method (RK-2);

2) Heun’s method (error-corrector RK-2);

3) Ralston’s method (error-corrector RK-2);

4) 4th-order Runge-Kutta method (RK-4);

ngclearn.utils.diffeq.ode_utils.get_integrator_code(integrationType)

Convenience function for mapping integrator type string to ngc-learn’s internal integer code value.

Parameters:

integrationType – string indicating integrator type (supported type: rk1` or euler, rk2 or midpoint, rk2_heun or heun, rk2_ralston or ralston, rk4)

Returns:

integator type integer code

ngclearn.utils.diffeq.ode_utils.leapfrog(t_curr, q_curr, p_curr, dfq, L, step_size, params)

ngclearn.utils.diffeq.ode_utils.solve_ode(method_name, t0, x0, T, dfx, dt, params=None, x_scale=1.0, sols_only=True)

ngclearn.utils.diffeq.ode_utils.step_euler(t, x, dfx, dt, params, x_scale=1.0)

Iteratively integrates one step forward via the Euler method, i.e., a first-order Runge-Kutta (RK-1) step.

Parameters:

• t – current time variable to advance by dt

• x – current variable values to advance/iteratively integrate (at time t)

• dfx – (ordinary) differential equation co-routine (as implemented in an ngc-learn component)

• dt – integration time step (also referred to as h in mathematics)

• params – tuple containing configuration values/hyper-parameters for the (ordinary) differential equation an ngc-learn component will provide

• x_scale – dampening factor to scale x by (Default: 1)

Returns:

variable values iteratively integrated/advanced to next step (t + dt)

ngclearn.utils.diffeq.ode_utils.step_heun(t, x, dfx, dt, params, x_scale=1.0)

Iteratively integrates one step forward via Heun’s method, i.e., a second-order Runge-Kutta (RK-2) error-corrected step. This method utilizes two (differential) function evaluations to estimate the solution at a given point in time. (Note: ngc-learn internally recognizes “rk2_heun” or “heun” for this routine)

Reference:

Ascher, Uri M., and Linda R. Petzold. Computer methods for ordinary

differential equations and differential-algebraic equations. Society for

Industrial and Applied Mathematics, 1998.

Parameters:

• t – current time variable to advance by dt

• x – current variable values to advance/iteratively integrate (at time t)

• dfx – (ordinary) differential equation co-routine (as implemented in an ngc-learn component)

• dt – integration time step (also referred to as h in mathematics)

• params – tuple containing configuration values/hyper-parameters for the (ordinary) differential equation an ngc-learn component will provide

• x_scale – dampening factor to scale x by (Default: 1)

Returns:

variable values iteratively integrated/advanced to next step (t + dt)

ngclearn.utils.diffeq.ode_utils.step_ralston(t, x, dfx, dt, params, x_scale=1.0)

Iteratively integrates one step forward via Ralston’s method, i.e., a second-order Runge-Kutta (RK-2) error-corrected step. This method utilizes two (differential) function evaluations to estimate the solution at a given point in time. (Note: ngc-learn internally recognizes “rk2_ralston” or “ralston” for this routine)

Reference:

Ralston, Anthony. “Runge-Kutta methods with minimum error bounds.”

Mathematics of computation 16.80 (1962): 431-437.

Parameters:

• t – current time variable to advance by dt

• x – current variable values to advance/iteratively integrate (at time t)

• dfx – (ordinary) differential equation co-routine (as implemented in an ngc-learn component)

• dt – integration time step (also referred to as h in mathematics)

• params – tuple containing configuration values/hyper-parameters for the (ordinary) differential equation an ngc-learn component will provide

• x_scale – dampening factor to scale x by (Default: 1)

Returns:

variable values iteratively integrated/advanced to next step (t + dt)

ngclearn.utils.diffeq.ode_utils.step_rk2(t, x, dfx, dt, params, x_scale=1.0)

Iteratively integrates one step forward via the midpoint method, i.e., a second-order Runge-Kutta (RK-2) step. (Note: ngc-learn internally recognizes “rk2” or “midpoint” for this routine)

Reference:

Ascher, Uri M., and Linda R. Petzold. Computer methods for ordinary

differential equations and differential-algebraic equations. Society for

Industrial and Applied Mathematics, 1998.

Parameters:

• t – current time variable to advance by dt

• x – current variable values to advance/iteratively integrate (at time t)

• dfx – (ordinary) differential equation co-routine (as implemented in an ngc-learn component)

• dt – integration time step (also referred to as h in mathematics)

• params – tuple containing configuration values/hyper-parameters for the (ordinary) differential equation an ngc-learn component will provide

• x_scale – dampening factor to scale x by (Default: 1)

Returns:

variable values iteratively integrated/advanced to next step (t + dt)

ngclearn.utils.diffeq.ode_utils.step_rk4(t, x, dfx, dt, params, x_scale=1.0)

Iteratively integrates one step forward via the midpoint method, i.e., a fourth-order Runge-Kutta (RK-4) step. (Note: ngc-learn internally recognizes “rk4” for this routine)

Reference:

Ascher, Uri M., and Linda R. Petzold. Computer methods for ordinary

differential equations and differential-algebraic equations. Society for

Industrial and Applied Mathematics, 1998.

Parameters:

• t – current time variable to advance by dt

• x – current variable values to advance/iteratively integrate (at time t)

• dfx – (ordinary) differential equation co-routine (as implemented in an ngc-learn component)

• dt – integration time step (also referred to as h in mathematics)

• params – tuple containing configuration values/hyper-parameters for the (ordinary) differential equation an ngc-learn component will provide

• x_scale – dampening factor to scale x by (Default: 1)

Returns:

variable values iteratively integrated/advanced to next step (t + dt)

ngclearn.utils.diffeq.odes module

In-built dynamical systems built on differential equations. Note that these systems are designed such that they directly operzte with ngc-learn’s ODE integration backend.

Currently in-built dynamical systems include:

0) A continuous linear 2D system;

1) A continuous cubic 2D system;

2) A Lorenz attractor system;

3) A continuous linear 3D system;

4) A continuous oscillator system.

ngclearn.utils.diffeq.odes.cubic_2D(t, x, params)

suggested init value - x0 = jnp.array([2., 0.])

Parameters:

• x – 2D vector type: jax array shape: (2,)

• t – Unused

• params – Unused

Returns:

[ -0.1 * x[0] ** 3 + 2.0 * x[1] ** 3, -2.0 * x[0] ** 3 - 0.1 * x[1] ** 3, ]; type: jax array, shape:(2,)

Return type:

2D vector

ngclearn.utils.diffeq.odes.linear_2D(t, x, params)

• suggested init value - x0 = jnp.array([3, -1.5])

Parameters:

• x – 2D vector type: jax array shape:(2,)

• t – Unused

• params – Unused

Returns:

[ -0.1 * x[0] + 2.0 * x[1], -2.0 * x[0] - 0.1 * x[1] ]; type: jax array, shape:(2,)

Return type:

2D vector

ngclearn.utils.diffeq.odes.linear_3D(t, x, params)

suggested init value - x0 = jnp.array([1, 1., -1])

Parameters:

• x – 3D vector type: jax array shape: (3,)

• t – Unused

• params – Unused

Returns:

[ -0.1 * x[0] + 2 * x[1], -2 * x[0] - 0.1 * x[1], -0.3 * x[2] ]; type: jax array, shape:(3,)

Return type:

3D vector

ngclearn.utils.diffeq.odes.lorenz(t, x, params)

suggested init value - x0 = jnp.array([-8, 7, 27])

Parameters:

• x – 3D vector type: jax array shape: (3,)

• t – Unused

• params – Unused

Returns:

[ 10 * (x[1] - x[0]), x[0] * (28 - x[2]) - x[1], x[0] * x[1] - 8 / 3 * x[2], ]; type: jax array, shape:(3,)

Return type:

3D vector

ngclearn.utils.diffeq.odes.oscillator(t, x, params, mu1=0.05, mu2=-0.01, omega=3.0, alpha=-2.0, beta=-5.0, sigma=1.1)

suggested init value - x0 = jnp.array([0.5, 0.05, 0.1])

Parameters:

• x – 3D vector type: jax array shape: (3,)

• t – Unused

• params – Unused

Returns:

[ mu1 * x[0] + sigma * x[0] * x[1], mu2 * x[1] + (omega + alpha * x[1] + beta * x[2]) * x[2] - sigma * x[0] ** 2, mu2 * x[2] - (omega + alpha * x[1] + beta * x[2]) * x[1], ]; type: jax array, shape:(3,)

Return type:

3D vector

Module contents