Bateman-Burgers Model#

Burgers1D([configs])

Implementation of one-dimensional Bateman-Burgers' equation model.

Burgers2D([configs])

Implementations of the two-dimensional Bateman-Burgers' model, whose convective form is defined below:

create_Burgers_1D_model([domain, nu, nx, ...])

A simple interface to creating an instance of Burgers1D.

create_Burgers_2D_model([domain, nu, nx, ...])

A simple interface to creating an instance of Burgers2D.

Bateman Burger’s Equation model(s) (1D/2D)

class Burgers1DConfigs(*, debug=False, verbose=False, output_dir='./_PYOED_RESULTS_', model_name='Burgers-1D', screen_output_iter=1, file_output_iter=1, time_integration=<factory>, num_prognostic_variables=None, space_discretization=<factory>, domain=(0, 1), nu=0.01, nx=101, dt=0.01, t_eps=1e-06)[source]#

Bases: TimeDependentModelConfigs

Configuration class for the one-dimensional Bateman-Burgers’ model, given by the equation:

\[\frac{\partial u}{\partial t} + u \frac{\partial u}{\partial x} = \nu \frac{\partial^2 u}{\partial^2 x},\, x\in[0, L],\, t\in (0, t_f]\]
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.

  • domain (tuple[float, float]) – boundary of the spatial domain. Default is (0, 1)

  • nu (float) – kinematic viscosity

  • nx (int) – number of spatial discretization points (of the domain)

  • dt (float) – default time integration step size

domain: tuple[float, float]#
nu: float#
nx: int#
dt: float#
t_eps: float#
__init__(*, debug=False, verbose=False, output_dir='./_PYOED_RESULTS_', model_name='Burgers-1D', screen_output_iter=1, file_output_iter=1, time_integration=<factory>, num_prognostic_variables=None, space_discretization=<factory>, domain=(0, 1), nu=0.01, nx=101, dt=0.01, t_eps=1e-06)#
class Burgers1D(configs=None)[source]#

Bases: TimeDependentModel

Implementation of one-dimensional Bateman-Burgers’ equation model.

\[\frac{\partial u}{\partial t} + u \frac{\partial u}{\partial x} = \nu \frac{\partial^2 u}{\partial^2 x},\, x\in[0, L],\, t\in (0, t_f]\]

This model is equivalent to the Navier-Stokes equation for incompressible flow with the pressure term removed. We assume Dirichlet homogeneous boundary conditions: \(u(0, t) = u(L, t) = 0,\, t \in (0, t_f]\), and as initial conditions we use the smooth function: \(u(x, 0) = x \sin(x) \sin(\pi x) \exp{(x/10)}\).

Spatial grid is equally-spaced based on the configurations passed upon initialization. We are using finite differences for spatial discretization.

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 – an object containing configurations of the one-dimensional Burgers’ model. See Burgers1DConfigs for more details.

__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 Burgers1DConfigs are validated. Finally, super classes validators are called.

Parameters:

  • configs (dict | Burgers1DConfigs) – 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 Burgers1DConfigs.

  • 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 associated with the passed model grid points We are assuming initial condition defined as \(\sin(x) \sin(\pi x) \exp{(0.1 x)}\) where \(x\) is a model grid point.

Returns:

numpy array (same shape as model_grid associated with the model) holding initial condition values.

state_vector(init_val=0)[source]#

Create an instance of model state vector. Here, this is a 1D Numpy array of size equal to the model grid.

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, 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].

  • 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=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.

exact_solution(t)[source]#

Exact solution for verification

get_model_grid()[source]#

return a copy of the model grid

property domain: tuple[float, float]#

return the domain of the model

property nu: float#

return the kinematic viscosity

property nx: int#

return the number of spatial discretization points

property dt: float#

return the time integration step size

property t_eps: float#

return the time epsilon

class Burgers2DConfigs(*, debug=False, verbose=False, output_dir='./_PYOED_RESULTS_', model_name='Burgers-2D', screen_output_iter=1, file_output_iter=1, time_integration=<factory>, num_prognostic_variables=None, space_discretization=<factory>, domain=((0, 1), (0, 1)), nu=0.01, nx=101, ny=101, dt=0.001, t_eps=1e-06)[source]#

Bases: TimeDependentModelConfigs

Configuration class for the two-dimensional Bateman-Burgers’ model, given by the equation:

\[\begin{split}\frac{\partial u}{\partial t} + u \frac{\partial u}{\partial x} + v \frac{\partial u}{\partial y} &= \nu (\frac{\partial^2 u}{\partial^2 x} + \frac{\partial^2 u}{\partial^2 y} ), \\ \frac{\partial v}{\partial t} + u \frac{\partial v}{\partial x} + v \frac{\partial v}{\partial y} &= \nu (\frac{\partial^2 v}{\partial^2 x} + \frac{\partial^2 v}{\partial^2 y} ),\end{split}\]

for \(x\in[0, L_x],\, y\in[0, L_y],\, t\in (0, t_f]\). These equations can be also written in conservative form as follows,

\[\begin{split}\frac{\partial u}{\partial t} + \frac{\partial u^2}{\partial x} + \frac{\partial uv}{\partial y} &= \nu (\frac{\partial^2 u}{\partial^2 x} + \frac{\partial^2 u}{\partial^2 y} ), \\ \frac{\partial v}{\partial t} + \frac{\partial uv}{\partial x} + \frac{\partial v^2}{\partial y} &= \nu (\frac{\partial^2 v}{\partial^2 x} + \frac{\partial^2 v}{\partial^2 y} ).\end{split}\]

We assume a time-dependent non-zero Dirichlet boundary conditions, extracted from the following exact solution:

\[\begin{split}u(x,y,t) = \frac{3}{4} - \frac{1}{4[1+\exp(\frac{-4x+4y-t}{32\nu})]}, \\ v(x,y,t) = \frac{3}{4} + \frac{1}{4[1+\exp(\frac{-4x+4y-t}{32\nu})]}.\end{split}\]

Initial conditions are also defined from the equation above (at \(t=0\)).

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.

domain: tuple[tuple[float, float], tuple[float, float]]#
nu: float#
nx: int#
ny: int#
dt: float#
t_eps: float#
__init__(*, debug=False, verbose=False, output_dir='./_PYOED_RESULTS_', model_name='Burgers-2D', screen_output_iter=1, file_output_iter=1, time_integration=<factory>, num_prognostic_variables=None, space_discretization=<factory>, domain=((0, 1), (0, 1)), nu=0.01, nx=101, ny=101, dt=0.001, t_eps=1e-06)#
class Burgers2D(configs=None)[source]#

Bases: TimeDependentModel

Implementations of the two-dimensional Bateman-Burgers’ model, whose convective form is defined below:

\[\begin{split}\frac{\partial u}{\partial t} + u \frac{\partial u}{\partial x} + v \frac{\partial u}{\partial y} &= \nu (\frac{\partial^2 u}{\partial^2 x} + \frac{\partial^2 u}{\partial^2 y} ), \\ \frac{\partial v}{\partial t} + u \frac{\partial v}{\partial x} + v \frac{\partial v}{\partial y} &= \nu (\frac{\partial^2 v}{\partial^2 x} + \frac{\partial^2 v}{\partial^2 y} ),\end{split}\]

for \(x\in[0, L_x],\, y\in[0, L_y],\, t\in (0, t_f]\). These equations can be also written in conservative form as follows,

\[\begin{split}\frac{\partial u}{\partial t} + \frac{\partial u^2}{\partial x} + \frac{\partial uv}{\partial y} &= \nu (\frac{\partial^2 u}{\partial^2 x} + \frac{\partial^2 u}{\partial^2 y} ), \\ \frac{\partial v}{\partial t} + \frac{\partial uv}{\partial x} + \frac{\partial v^2}{\partial y} &= \nu (\frac{\partial^2 v}{\partial^2 x} + \frac{\partial^2 v}{\partial^2 y} ).\end{split}\]

We assume a time-dependent non-zero Dirichlet boundary conditions, extracted from the following exact solution:

\[\begin{split}u(x,y,t) = \frac{3}{4} - \frac{1}{4[1+\exp(\frac{-4x+4y-t}{32\nu})]}, \\ v(x,y,t) = \frac{3}{4} + \frac{1}{4[1+\exp(\frac{-4x+4y-t}{32\nu})]}.\end{split}\]

Initial conditions are also defined from the equation above (at \(t=0\)). Spatial grid is equally-spaced based on the configurations passed upon initialization. We are using finite differences for spatial discretization. Time integration is carried out using an explicit fourth-order Runge-Kutta method, which requires some attention to ensure stability.

Parameters:

configs (dict | Burgers2DConfigs | None) – An object containing configurations of the two-dimensional Burgers’ model.

__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 Burgers2DConfigs are validated. Finally, super classes validators are called.

Parameters:

  • configs (dict | Burgers2DConfigs) – 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 Burgers2DConfigs.

  • 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 associated with the passed model grid points We are assuming … initial condition defined as

\[\begin{split}u(x,y,t) = \frac{3}{4} - \frac{1}{4[1+\exp(\frac{-4x+4y}{32\nu})]}, \\ v(x,y,t) = \frac{3}{4} + \frac{1}{4[1+\exp(\frac{-4x+4y}{32\nu})]}.\end{split}\]

where \(x, y\) define the model grid coordinates.

Returns:

1D numpy array holding initial condition values.

set_boundary_condition(state, t)[source]#

Set the boundary conditions, defined using the followin relation:

\[\begin{split}u(x,y,t) = \frac{3}{4} - \frac{1}{4[1+\exp(\frac{-4x+4y-t}{32\nu})]}, \\ v(x,y,t) = \frac{3}{4} + \frac{1}{4[1+\exp(\frac{-4x+4y-t}{32\nu})]}.\end{split}\]
Returns:

numpy array with set boundary condition values.

state_vector(init_val=0)[source]#

Create an instance of model state vector. Here, this is a 1D Numpy array of length equal to double the length of the model grid (for u and v).

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, form='conv', verbose=False)[source]#

Simulate/integrate the model 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].

  • form – formulation of the 2D Burgers problem, either conv’ for convective or ‘cons’ for conservative. Default is convective formulation.

  • verbose (bool) – output progress to screen if True. If set to False, 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=True, form='conv')[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.

exact_solution(t)[source]#

Exact solution for verification

get_model_grid()[source]#

return a copy of the model grid

property domain: tuple#

retrieve the model domain

property nu: float#

retrieve the model diffusion coefficient

property nx: int#

retrieve the model x-discretization size

property ny: int#

retrieve the model y-discretization size

property dt: float#

retrieve the model time step size

property t_eps: float#

retrieve the model time epsilon

create_Burgers_1D_model(domain=(0, 1), nu=0.005, nx=101, dt=0.01, output_dir='./_PYOED_RESULTS_')[source]#

A simple interface to creating an instance of Burgers1D.

Parameters:

  • domain – boundary of the spatial domain. Default is (-1, 1)

  • nu (float) – kinematic viscosity – diffusion coefficient

  • nx (int) – number of spatial discretization points (of the domain)

  • 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 Burgers1D

create_Burgers_2D_model(domain=((0, 1), (0, 1)), nu=0.005, nx=101, ny=101, dt=0.01, output_dir='./_PYOED_RESULTS_')[source]#

A simple interface to creating an instance of Burgers2D.

Parameters:

  • domain – boundary of the spatial domain.

  • nu (float) – kinematic viscosity – diffusion coefficient

  • nx (int) – number of spatial discretization points (of the domain) in the x-direction

  • ny (int) – number of spatial discretization points in the y-direction

  • 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 AdvectionDiffusion1D