Lorenz Models#

Lorenz63([configs])

Implementations of the Chaotic Lorenz-63 model

Lorenz96([configs])

Implementations of the Chaotic Lorenz-96 model

create_Lorenz63_model([sigma, rho, beta, ...])

A simple interface to creating an instance of Lorenz63.

create_Lorenz96_model([nx, F, dt, output_dir])

A simple interface to creating an instance of Lorenz96.

Implementations of multiple variants of the Lorenz model.

class Lorenz63Configs(*, debug=False, verbose=False, output_dir='./_PYOED_RESULTS_', model_name='Lorenz-63: Three-Variable Model', screen_output_iter=1, file_output_iter=1, time_integration=<factory>, num_prognostic_variables=None, space_discretization=<factory>, sigma=10.0, rho=28.0, beta=2.6666666666666665, ic=<factory>, dt=0.01, t_eps=1e-08)[source]#

Bases: TimeDependentModelConfigs

Configuration dataclass for the Lorenz-63 model. Recall that the Lorenz-63 model is given by the equations

\[\begin{split}\frac{d x}{d t} &= \sigma (y-x) \\ \frac{d y}{d t} &= x(\rho-z) - y \\ \frac{d z}{d t} &= xy - \beta z \\\end{split}\]
Parameters:

  • verbose (bool) – a boolean flag to control verbosity of the object.

  • debug (bool) – a boolean flag that enables adding extra functionlity in a debug mode

  • output_dir (str | Path) – the base directory where the output files will be saved.

  • model_name (str) – name of the model. Default is None.

  • screen_output_iter (int) – iteration interval for screen output. Default is 1. Note that this should be a positive integer to enforce proper effect.

  • file_out_iter – iteration interval for file output. Default is 1. Note that this should be a positive integer to enforce proper effect.

  • time_integration (dict | None) –

    dictionary holding time integration configurations:

    • scheme: string specifying the time integration scheme (e.g., ‘RK4’, ‘RK45’, ‘BDF’, etc.). Default is None.

    • stepsize: float specifying the time integration stepsize. Default is None.

    • adaptive: bool specifying whether the time integration is adaptive. Default is False.

  • num_prognostic_variables (int | None) – number of prognostic variables in the model. Default is None. Must be a positive integer if not None.

  • space_discretization (dict | None) –

    dictionary holding space discretization configurations. Contains:

    • scheme: string specifying the space discretization scheme (e.g., ‘FD’, ‘FE’, ‘BE’, etc.). Default is None.

  • sigma (float) – \(\sigma\). Default is 10.0. Must be positive.

  • rho (float) – \(\rho\). Default is 28.0. Must be positive.

  • beta (float) – \(\beta\). Default is 8.0/3.0. Must be positive.

  • ic (ndarray) – initial condition. Default is [1.0, 1.0, 1.0].

  • dt (float) – time integration step size. Default is 0.01. Must be positive.

  • t_eps (float) – tolerance for time step comparison. Default is 1e-8. Must be positive and smaller than dt.

sigma: float#
rho: float#
beta: float#
ic: ndarray#
dt: float#
t_eps: float#
__init__(*, debug=False, verbose=False, output_dir='./_PYOED_RESULTS_', model_name='Lorenz-63: Three-Variable Model', screen_output_iter=1, file_output_iter=1, time_integration=<factory>, num_prognostic_variables=None, space_discretization=<factory>, sigma=10.0, rho=28.0, beta=2.6666666666666665, ic=<factory>, dt=0.01, t_eps=1e-08)#
class Lorenz63(configs=None)[source]#

Bases: TimeDependentModel

Implementations of the Chaotic Lorenz-63 model

\[\begin{split}\frac{d x}{d t} &= \sigma (y-x) \\ \frac{d y}{d t} &= x(\rho-z) - y \\ \frac{d z}{d t} &= xy - \beta z \\\end{split}\]

This model is a toy model in meteorology and exhibit a notable chaotic behavior for specific values of the parameters \(\sigma, \rho, \beta\).

Time integration is carried out using a simple implicit Euler method, employing the Newton-Raphson iterations for which the Jacobian of the resiual term is required.

Parameters:

configs (Lorenz63Configs | dict | None) – Configurations of the model, either as an instance of Lorenz63Configs, a dictionary, or None. The default is None, which uses the default configurations.

__init__(configs=None)[source]#
create_initial_condition()[source]#

Create the initial condition for the Lorenz 63 model

Returns:

1D numpy array holding initial condition values.

validate_configurations(configs, raise_for_invalid=True)[source]#

Check the passed configuratios and make sure they are conformable with each other, and with current configurations once combined. This guarantees that any key-value pair passed in configs can be properly used

Note

Here only the locally-defined configurations in Lorenz63Configs are validated. Finally, super classes validators are called.

Parameters:

  • configs (dict | Lorenz63Configs) – full or partial (subset) configurations to be validated

  • raise_for_invalid (bool) – if True raise TypeError for invalid configrations type/key. Default True

Returns:

flag indicating whether passed configurations dictionary is valid or not

Raises:

  • AttributeError – if any (or a group) of the configurations does not exist in the model configurations Lorenz63Configs.

  • PyOEDConfigsValidationError – if the configurations are invalid and raise_for_invalid is set to True.

Return type:

bool

state_vector(init_val=0)[source]#

Create an instance of model state vector. Here, this is a 1D Numpy array with three entries corresponding to the Lorenz 63 variables.

Parameters:

init_val (float) – value assigned to entries of the state vector

Returns:

1d numpy array

is_state_vector(state)[source]#

Test whether the passed state vector is valid or not

integrate_state(state, tspan, checkpoints=None, maxiter=200, tol=1e-10, verbose=False)[source]#

Simulate/integrate the mdoel starting from the initial state over the passed checkpoints.

Parameters:

  • state – data structure holding the initial model state

  • tspan – (t0, tf) iterable with two entries specifying of the time integration window

  • checkpoints – times at which to store the computed solution, must be sorted and lie within tspan. If None (default), use points selected by the solver [t0, t1, …, tf].

  • maxiter (int) – maximum number of iterations of the Newton Raphson solver

  • tol (float) – tolerance of the Newton Raphson solver; here taken as the norm of the update

  • verbose (bool) – output progress to screen if True. If set to False scr_out_iter is discarede, i.e., nothing is printed to screen`

Returns:

a list holding the timespan, and a list holding the model trajectory with entries corresponding to the simulated model state at entries of checkpoints starting from checkpoints[0] and ending at checkpoints[-1].

Raises:

AssertionError if tspan is not valid, or checkpoints are not within tspan

Jacobian_T_matvec(state, eval_at_t, eval_at, dt=None, sparse=False)[source]#

Evaluate and return the product of the Jacobian (of the right-hand-side) of the model (TLM) transposed, by a model state.

Parameters:

  • state – state to multiply the Jacobian by

  • eval_at_t – time at which the Jacobian is evaluated

  • eval_at – state around which the Jacobian is evaluated

  • dt (float) – the step size

Returns:

the product of the Jacobian transposed (adjoint operator) by a model state.

get_model_grid()[source]#

return a copy of the model grid

property sigma#
property rho#
property beta#
property ic#
property dt#
property t_eps#
class Lorenz96Configs(*, debug=False, verbose=False, output_dir='./_PYOED_RESULTS_', model_name='Lorenz-96 Model', screen_output_iter=1, file_output_iter=1, time_integration=<factory>, num_prognostic_variables=None, space_discretization=<factory>, nx=40, F=8.0, dt=0.01, t_eps=1e-08)[source]#

Bases: TimeDependentModelConfigs

Configurations for the Chaotic Lorenz-96 model

\[\frac{d x_i}{d t} = (x_{i+1} - x_{i-2})x_{i-1} - x_{i} + F ,\, i=1,2,\dots, n,\, t\in (0, t_f]\]

This model is a simplified model that describes an arbitrary atmospheric quantity as it evolves on a circular array of sites, undergoing forcing, dissipation, and rotation invariant advection.

Parameters:

  • verbose (bool) – a boolean flag to control verbosity of the object.

  • debug (bool) – a boolean flag that enables adding extra functionlity in a debug mode

  • output_dir (str | Path) – the base directory where the output files will be saved.

  • model_name (str) – name of the model. Default is None.

  • screen_output_iter (int) – iteration interval for screen output. Default is 1. Note that this should be a positive integer to enforce proper effect.

  • file_out_iter – iteration interval for file output. Default is 1. Note that this should be a positive integer to enforce proper effect.

  • time_integration (dict | None) –

    dictionary holding time integration configurations:

    • scheme: string specifying the time integration scheme (e.g., ‘RK4’, ‘RK45’, ‘BDF’, etc.). Default is None.

    • stepsize: float specifying the time integration stepsize. Default is None.

    • adaptive: bool specifying whether the time integration is adaptive. Default is False.

  • num_prognostic_variables (int | None) – number of prognostic variables in the model. Default is None. Must be a positive integer if not None.

  • space_discretization (dict | None) –

    dictionary holding space discretization configurations. Contains:

    • scheme: string specifying the space discretization scheme (e.g., ‘FD’, ‘FE’, ‘BE’, etc.). Default is None.

nx: int#
F: float#
dt: float#
t_eps: float#
__init__(*, debug=False, verbose=False, output_dir='./_PYOED_RESULTS_', model_name='Lorenz-96 Model', screen_output_iter=1, file_output_iter=1, time_integration=<factory>, num_prognostic_variables=None, space_discretization=<factory>, nx=40, F=8.0, dt=0.01, t_eps=1e-08)#
class Lorenz96(configs=None)[source]#

Bases: TimeDependentModel

Implementations of the Chaotic Lorenz-96 model

\[\frac{d x_i}{d t} = (x_{i+1} - x_{i-2})x_{i-1} - x_{i} + F ,\, i=1,2,\dots, n,\, t\in (0, t_f]\]

This model is a simplified model that describes an arbitrary atmospheric quantity as it evolves on a circular array of sites, undergoing forcing, dissipation, and rotation invariant advection.

Time integration is carried out using a simple implicit Euler method, employing the Newton-Raphson iterations for which the Jacobian of the resiual term is required.

Parameters:

configs (Lorenz96Configs | dict | None) – Configurations of the model, either as an instance of Lorenz96Configs, a dictionary, or None. The default is None, which uses the default configurations.

__init__(configs=None)[source]#
validate_configurations(configs, raise_for_invalid=True)[source]#

Check the passed configuratios and make sure they are conformable with each other, and with current configurations once combined. This guarantees that any key-value pair passed in configs can be properly used

Note

Here only the locally-defined configurations in Lorenz96Configs are validated. Finally, super classes validators are called.

Parameters:

  • configs (dict | Lorenz96Configs) – full or partial (subset) configurations to be validated

  • raise_for_invalid (bool) – if True raise TypeError for invalid configrations type/key. Default True

Returns:

flag indicating whether passed configurations dictionary is valid or not

Raises:

  • AttributeError – if any (or a group) of the configurations does not exist in the model configurations Lorenz96Configs.

  • PyOEDConfigsValidationError – if the configurations are invalid and raise_for_invalid is set to True.

Return type:

bool

create_initial_condition()[source]#

Create the initial condition for the Lorenz 96 model. Here, it is obtained by adding a small perturbation to the equilibrium conditions and apply time integration for a few time steps and consider the last state as initial condition

Returns:

1D numpy array holding initial condition values.

state_vector(init_val=0)[source]#

Create an instance of model state vector. Here, this is a 1D Numpy array with n entries corresponding to the Lorenz 96 variables.

Parameters:

init_val (float) – value assigned to entries of the state vector

Returns:

1d numpy array

is_state_vector(state)[source]#

Test whether the passed state vector is valid or not

integrate_state(state, tspan, checkpoints=None, maxiter=200, tol=1e-10, verbose=False)[source]#

Simulate/integrate the mdoel starting from the initial state over the passed checkpoints.

Parameters:

  • state – data structure holding the initial model state

  • tspan – (t0, tf) iterable with two entries specifying of the time integration window

  • checkpoints – times at which to store the computed solution, must be sorted and lie within tspan. If None (default), use points selected by the solver [t0, t1, …, tf].

  • maxiter (int) – maximum number of iterations of the Newton Raphson solver

  • tol (float) – tolerance of the Newton Raphson solver; here taken as the norm of the update

  • verbose (bool) – output progress to screen if True.

Returns:

a list holding the timespan, and a list holding the model trajectory with entries corresponding to the simulated model state at entries of checkpoints starting from checkpoints[0] and ending at checkpoints[-1].

Raises:

AssertionError if tspan is not valid, or checkpoints are not within tspan

Jacobian_T_matvec(state, eval_at_t, eval_at, dt=None, sparse=True)[source]#

Evaluate and return the product of the Jacobian (of the right-hand-side) of the model (TLM) transposed, by a model state.

Parameters:

  • state – state to multiply the Jacobian by

  • eval_at_t – time at which the Jacobian is evaluated

  • eval_at – state around which the Jacobian is evaluated

  • dt (float) – the step size

Returns:

the product of the Jacobian transposed (adjoint operator) by a model state.

get_model_grid()[source]#

return a copy of the model grid

property nx#
property F#
property dt#
property t_eps#
create_Lorenz63_model(sigma=10.0, rho=28.0, beta=2.6666666666666665, ic=(1, 1, 1), dt=0.001, output_dir='./_PYOED_RESULTS_')[source]#

A simple interface to creating an instance of Lorenz63.

Returns:

an instance of Lorenz63

create_Lorenz96_model(nx=40, F=8, dt=0.01, output_dir='./_PYOED_RESULTS_')[source]#

A simple interface to creating an instance of Lorenz96.

Parameters:

  • nx (int) – the dimension (number of variables)

  • F (float) – forcing term

  • dt (float) – default time integration step size

  • output_dir – Path to folder (will be created if doesn’t exist) in which to write reports, output, etc.

Returns:

an instance of Lorenz96