2D Subsurface (Poisson) Model#

Subsurf2D([configs])

A two dimensional Subsurface modeling model implementing the nonlinear Poisson equation \(-\nabla \cdot (e^m \nabla u) = f\) on the unit square, where \(m\) is the log-permeability field (parameter) and \(u\) is the hydraulic head (state).

create_Subsurf2D_model([nx, ny, ...])

A simple interface to creating an instance of Subsurf2D.

A module that provides implementation(s) of Poisson Equations model(s). This module uses FEniCSx (dolfinx 0.10) and PETSc.

class Subsurf2DConfigs(*, debug=False, verbose=False, output_dir='./_PYOED_RESULTS_', model_name='Subsurf2D', screen_output_iter=1, file_output_iter=1, nx=64, ny=64, mesh_elements='Lagrange', mesh_elements_degree=(1, 2), random_seed=123)[source]#

Bases: TimeIndependentModelConfigs

Configurations for the Subsurf2D model.

Parameters:

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

  • debug (bool) – a boolean flag that enables adding extra functionality 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.

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

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

  • mesh_elements (str) – name/type of finite elements; ‘Lagrange’ is the default value

  • mesh_elements_degree (tuple[int, int]) – degree of mesh elements (parameter, state)

  • random_seed (int | None) – random seed to control synthetic ground truth generation

nx: int#
ny: int#
mesh_elements: str#
mesh_elements_degree: tuple[int, int]#
random_seed: int | None#
__init__(*, debug=False, verbose=False, output_dir='./_PYOED_RESULTS_', model_name='Subsurf2D', screen_output_iter=1, file_output_iter=1, nx=64, ny=64, mesh_elements='Lagrange', mesh_elements_degree=(1, 2), random_seed=123)#
class Subsurf2D(configs=None)[source]#

Bases: TimeIndependentModel, RandomNumberGenerationMixin

A two dimensional Subsurface modeling model implementing the nonlinear Poisson equation \(-\nabla \cdot (e^m \nabla u) = f\) on the unit square, where \(m\) is the log-permeability field (parameter) and \(u\) is the hydraulic head (state).

Uses FEniCSx (dolfinx 0.10) and PETSc.

Parameters:

configs (dict) – an object holding model configurations. See Subsurf2DConfigs

__init__(configs=None)[source]#

Initialize the random number generator

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

Validate the passed configurations.

Parameters:

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

  • raise_for_invalid (bool) – if True raise for invalid configurations

Returns:

True if valid, False otherwise

Return type:

bool

create_initial_condition(method='sin', return_np=True)[source]#

Create the initial condition associated with the passed model grid points.

Parameters:

method (str) – ‘random’, ‘sin’, or ‘deterministic’

Returns:

numpy array or PETSc.Vec holding initial condition values.

parameter_vector(init_val=0, return_np=True)[source]#

Create an instance of model parameter vector.

Parameters:

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

Returns:

1-D numpy array (return_np=True) or PETSc.Vec (return_np=False).

state_vector(init_val=0, return_np=True)[source]#

Create an instance of model state vector.

Parameters:

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

Returns:

1-D numpy array (return_np=True) or PETSc.Vec (return_np=False).

is_state_vector(state)[source]#

Test whether the passed state vector is valid.

is_parameter_vector(parameter)[source]#

Test whether the passed parameter vector is valid.

solve_forward(parameter, return_np=True, verbose=False)[source]#

Solve the forward problem (parameter → state): \(-\nabla \cdot (e^m \nabla u) = f\) with \(u = x_1\) on all boundaries.

Parameters:

  • parameter – log-permeability field (numpy array or PETSc.Vec)

  • return_np (bool) – return numpy array (True) or PETSc.Vec (False)

Returns:

state vector

solve_adjoint(adj_rhs, eval_at=None, solve_for_param=True, return_np=True, verbose=False)[source]#

Solve the variational adjoint problem and optionally recover the parameter (misfit gradient).

Parameters:

  • adj_rhs – adjoint right-hand side (numpy array or PETSc.Vec, state space)

  • eval_at – parameter at which to evaluate (numpy array or PETSc.Vec)

  • solve_for_param (bool) – if True, project adjoint to parameter space

  • return_np (bool) – return numpy array

Returns:

adjoint or parameter-space gradient

solve_incremental_forward(H_dir, parameter, state=None, return_np=True, verbose=False)[source]#

Solve the incremental forward problem (Hessian-vector product direction).

Parameters:

  • H_dir – direction in which to evaluate the Hessian (parameter space)

  • parameter – current parameter

  • state – current forward state (computed if None)

  • return_np (bool) – return numpy or PETSc.Vec

Returns:

incremental forward state

solve_incremental_adjoint(H_dir, parameter, adj, adj_res, state, u_inc=None, return_np=True, verbose=False)[source]#

Solve the incremental adjoint problem (second-order Hessian contribution).

Parameters:

  • H_dir – Hessian direction (parameter space)

  • parameter – current parameter

  • adj – adjoint state from solve_adjoint

  • adj_res – adjoint residual

  • state – current forward state

  • u_inc – incremental forward state (computed if None)

  • return_np (bool) – return numpy or PETSc.Vec

evaluate_second_order_sensitivities(H_dir, adj, inc_state, inc_adj, parameter, state=None, return_np=False, verbose=False)[source]#

Hessian-vector product of the data-misfit term in variational DA problems.

plot(vec, target='state', show_mesh=True, mesh_linewidth=0.1, mesh_linecolor='#FFAC67', clean_xy_ticks=True, xlim=None, ylim=None, title=None, fontsize=20, cmap='jet', alpha=0.95, dpi=800, add_colorbar=True, saveto=None, verbose=False)[source]#

Create a 2D triangulation plot of the passed state/parameter vector.

get_model_grid()[source]#

Return a numpy array of shape (n_dofs, 2) with the DOF coordinates.

property true_initial_condition#
property state_dof#

FunctionSpace corresponding to the model state.

property parameter_dof#

FunctionSpace corresponding to the model parameter.

property nx#
property ny#
property mesh_elements#
property mesh_elements_degree#
create_Subsurf2D_model(nx=64, ny=64, mesh_elements='Lagrange', mesh_elements_degree=(1, 2), output_dir='./_PYOED_RESULTS_')[source]#

A simple interface to creating an instance of Subsurf2D.

Parameters:

  • nx (int) – grid points in x-direction

  • ny (int) – grid points in y-direction

  • mesh_elements (str) – element family

  • mesh_elements_degree – (parameter_degree, state_degree)

Returns:

an instance of Subsurf2D with passed settings