mf6adj.adj module

class mf6adj.adj.Mf6Adj(adj_filename, lib_name, logging_level='INFO', logging_filename=None, working_directory=None)[source]

Bases: object

MODFLOW 6 adjoint solver interface.

Parameters:

  • adj_filename (str) – Adjoint input filename.

  • lib_name (str) – MODFLOW 6 shared library path.

  • logging_level (str or int, optional) – Logging level (DEBUG, INFO, WARNING, ERROR, or CRITICAL).

  • logging_filename (str or pl.Path, optional) – Optional log filename. If omitted, logging is limited to the console.

  • working_directory (str or pl.Path, optional) – Working directory. If omitted, the current directory is used.

finalize()[source]

Close the API and file handles.

perturbation_method(pert_mult=1.01)[source]

Calculate finite-difference perturbation sensitivities.

This utility perturbs active parameter entries one at a time, reruns the forward simulation, and estimates sensitivity using a forward-difference quotient. The resulting sensitivities can be compared directly with adjoint-based sensitivities for verification during development.

Parameters:

pert_mult (float, default 1.01) – Multiplicative perturbation factor applied to each parameter value. The perturbation increment is computed as epsilon = value * (pert_mult - 1.0).

Returns:

Dataframe with one row per perturbation and columns containing perturbation metadata (for example parameter, index, epsilon, and node/layer labels where applicable) plus finite-difference sensitivities for each configured performance measure.

Return type:

DataFrame

solve_adjoint(hdf5_adjoint_solution_fname=None, skip_solve=False, csv_summary=False, linear_solver=None, linear_solver_kwargs={}, use_precon=True, jacobi_preconditioner=None, precon_kwargs={}, singular_test=False, tikhonov=0.0, dvclose=1e-06, rclose=0.001, dvscale=False)[source]

Solve for the adjoint state, one performance measure at a time.

Parameters:

  • hdf5_adjoint_solution_fname (PathLike, optional) – HDF5 file to write the adjoint solution. If omitted, a default name based on the performance-measure name is used.

  • skip_solve (bool, optional) – Skip the adjoint solve for time steps with no performance-measure entries.

  • csv_summary (bool, optional) – Write a CSV summary of the sensitivity information.

  • linear_solver (str or callable, optional) – Sparse linear solver to use. If None, either a direct solver or bicgstab is selected based on model size. If a string, supported values are "direct" and "bicgstab". A compatible solver callable may also be supplied.

  • linear_solver_kwargs (dict, optional) – Keyword arguments passed to linear_solver.

  • use_precon (bool, optional) – Use a preconditioner with the iterative linear solver.

  • jacobi_preconditioner (str, optional) – Use Jacobi preconditioner with the iterative linear solver. If None, the ILU preconditioner will be used. If a string, supported values are "point" and "block".

  • precon_kwargs (dict, optional) – Keyword arguments passed to the preconditioner setup. For the default ILU preconditioner, these are passed to spilu. When jacobi_preconditioner="block", the block_size key sets the block size.

  • singular_test (bool, optional) – Test for a singular matrix and apply Tikhonov regularization when needed.

  • tikhonov (float, optional) – Tikhonov regularization value.

  • dvclose (float, optional) – Custom convergence criterion based on the maximum absolute change between consecutive iterates.

  • rclose (float, optional) – Custom convergence criterion based on the maximum absolute residual.

  • dvscale (bool, optional) – Scale lambda and the right-hand side to improve iterative solver convergence for large lambda values.

Returns:

Composite sensitivity summaries keyed by performance-measure name.

Return type:

dict[str, DataFrame]

solve_forward_model(verbose=True, force_k_update=False, sp_pert_dict=None, pert_save=False, hdf5_name=None, solve_func_ptr=None, presolve_func_ptr=None, postsolve_func_ptr=None)[source]

Solve the forward model and store adjoint inputs in HDF5.

The forward model is run for all MODFLOW 6 time steps, and the solution components needed for the adjoint solve are harvested and written to the HDF5 file.

Parameters:

  • verbose (bool, optional) – Whether to report progress to stdout.

  • force_k_update (bool, optional) – Force MODFLOW 6 to reprocess the K and K33 arrays. Used only during perturbation testing.

  • sp_pert_dict (dict, optional) – Perturbed boundary information used during perturbation testing.

  • pert_save (bool, optional) – Save additional information for perturbation testing.

  • hdf5_name (PathLike, optional) – Output HDF5 filename for forward-solution components. If omitted, a generic time-stamped filename is created.

  • solve_func_ptr (callable, optional) – Callback invoked with the modflowapi.ModflowApi instance before each solver iteration. If omitted, no callback is run.

  • presolve_func_ptr (callable, optional) – Callback invoked with the modflowapi.ModflowApi instance at the start of each time step, before the solve loop begins. If omitted, no callback is run.

  • postsolve_func_ptr (callable, optional) – Callback invoked with the modflowapi.ModflowApi instance after each time step is finalized. If omitted, no callback is run.

Returns:

Perturbation-testing data when pert_save is True; otherwise None.

Return type:

tuple[dict, dict] or None