2D Subsurface (Poisson) Model (FEniCS)#

Subsurf2D([configs])

A two dimensional Subsurface modeling model.

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 utilizes fenics (dolfin) if supported

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

  • 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

  • random_seed (int | None) – random seed to control synthetic ground truth generation if random noise is choosen for that.

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.

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]#

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

Parameters:

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

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

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) –

two methods are supported now:

  • ’random’: create noramlly distributed noise vector

  • ’deterministic’: this creates a predefined IC, given a hard-coded expression; will be fixed/updated/extended as needed

Returns:

numpy array (same shape as model_grid associated with the model) 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 state vector

Returns:

1d numpy array

state_vector(init_val=0, return_np=True)[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

is_parameter_vector(parameter)[source]#

Test whether the passed parameter vector is valid or not

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

Solve the forward problem (parameter -> state)

solve_adjoint(adj_rhs, eval_at=None, solve_for_param=True, return_np=True, verbose=False)[source]#
Solve the variational adjoint problem;

and optionally solve for parameter!

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

  • parameter – parameter at which the Hessian is evaluated

  • state – state resulting by solving the forward problem using the passed parameter.

  • H_dir – direction in which to evaluate the Hessian (2nd-order derivative)

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

  • parameter – parameter at which the Hessian is evaluated

  • state – state resulting by solving the forward problem using the passed parameter.

  • H_dir – direction in which to evaluate the Hessian (2nd-order derivative)

  • u_inc – incremental adjoint returned by solve_incremental_forward()

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 x

Parameters:

  • vec – model state/parameter vector

  • target (str) – string identifying whether vec is a state or a parameter vector

  • show_mesh (bool) – show/hide mesh lines

  • mesh_linewidth

  • mesh_linecolor

  • clean_xy_ticks

  • xlim

  • ylim

  • title

  • fontsize

  • cmap

  • alpha

  • add_colorbar

  • saveto – filename/path to save plot to (format is set to ‘pdf’ not part of the filename)

  • verbose (bool) – screen verbosity

get_model_grid()[source]#

Return a numpy array representation of the model grid

property true_initial_condition#
property state_dof#

dof/FunctionSpace correspnding the the model state

property parameter_dof#

dof/functionspace correspnding the the model parameter

property nx#

Number of grid points in the x-direction

property ny#

Number of grid points in the y-direction

property mesh_elements#

Type of mesh elements

property mesh_elements_degree#

Degree of mesh elements

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)

  • ny (int)

  • mesh_elements (str)

  • mesh_elements_degree

Returns:

an instance of Subsurf2D with passed settings