jacobian_assembly module¶
Coupled derivatives calculations.
- class gemseo.core.derivatives.jacobian_assembly.CoupledSystem[source]
Bases:
object
Compute coupled (total) derivatives of a system of residuals.
Use several methods:
direct or adjoint
factorized for multiple RHS
- adjoint_mode(functions, dres_dx, dres_dy_t, dfun_dx, dfun_dy, linear_solver='DEFAULT', use_lu_fact=False, **linear_solver_options)[source]
Compute the total derivative Jacobian in adjoint mode.
- Parameters:
functions (Iterable[str]) – The functions to differentiate.
dres_dx (dok_matrix | LinearOperator) – The Jacobian of the residuals wrt the design variables.
dres_dy_t (dok_matrix | LinearOperator) – The Jacobian of the residuals wrt the coupling variables.
dfun_dx (Mapping[str, dok_matrix]) – The Jacobian of the functions wrt the design variables.
dfun_dy (Mapping[str, dok_matrix]) – The Jacobian of the functions wrt the coupling variables.
linear_solver (str) –
The name of the linear solver.
By default it is set to “DEFAULT”.
use_lu_fact (bool) –
Whether to factorize dres_dy_t once.
By default it is set to False.
**linear_solver_options (Any) – The optional parameters.
- Returns:
The Jacobian of total coupled derivatives.
- Return type:
- direct_mode(functions, n_variables, n_couplings, dres_dx, dres_dy, dfun_dx, dfun_dy, linear_solver='DEFAULT', use_lu_fact=False, **linear_solver_options)[source]
Compute the total derivative Jacobian in direct mode.
- Parameters:
functions (Iterable[str]) – The functions to differentiate.
n_variables (int) – The number of variables.
n_couplings (int) – The number of couplings.
dres_dx (dok_matrix | LinearOperator) – The Jacobian of the residuals wrt the design variables.
dres_dy (dok_matrix | LinearOperator) – The Jacobian of the residuals wrt the coupling variables.
dfun_dx (Mapping[str, dok_matrix]) – The Jacobian of the functions wrt the design variables.
dfun_dy (Mapping[str, dok_matrix]) – The Jacobian of the functions wrt the coupling variables.
linear_solver (str) –
The name of the linear solver.
By default it is set to “DEFAULT”.
use_lu_fact (bool) –
Whether to factorize dres_dy once.
By default it is set to False.
**linear_solver_options (Any) – The optional parameters.
- Returns:
The Jacobian of the total coupled derivatives.
- Return type:
- DEFAULT_LINEAR_SOLVER: ClassVar[str] = 'DEFAULT'
The default linear solver.
- linear_problem: LinearProblem | None
The considered linear problem.
- lu_fact: int
The number of LU mode calls (adjoint or direct).
- n_adjoint_modes: int
The number of adjoint mode calls.
- n_direct_modes: int
The number of direct mode calls.
- n_linear_resolutions: int
The number of linear resolutions.
- class gemseo.core.derivatives.jacobian_assembly.JacobianAssembly(coupling_structure)[source]
Bases:
object
Assembly of Jacobians.
Typically, assemble discipline’s Jacobians into a system Jacobian.
- Parameters:
coupling_structure (MDOCouplingStructure) – The MDOCouplingStructure associated disciplines that form the coupled system.
- class DerivationMode(value)
Bases:
StrEnum
The derivation modes.
- ADJOINT = 'adjoint'
The adjoint resolution mode for MDAs, solves one system per output.
- AUTO = 'auto'
Automatic switch between direct, reverse or adjoint depending on data sizes.
- DIRECT = 'direct'
The direct Jacobian accumulation, chain rule from inputs to outputs, or derivation of an MDA that solves one system per input.
- REVERSE = 'reverse'
The reverse Jacobian accumulation, chain rule from outputs to inputs.
- class JacobianPosition(row_slice, column_slice, row_index, column_index)[source]
Bases:
NamedTuple
The position of the discipline’s Jacobians within the assembled Jacobian.
Create new instance of JacobianPosition(row_slice, column_slice, row_index, column_index)
- column_index: int
The column index of the disciplinary Jacobian within the assembled Jacobian when defined blockwise.
- column_slice: slice
The column slice indicating where to position the disciplinary Jacobian within the assembled Jacobian when defined as an array.
- row_index: int
The row index of the disciplinary Jacobian within the assembled Jacobian when defined blockwise.
- row_slice: slice
The row slice indicating where to position the disciplinary Jacobian within the assembled Jacobian when defined as an array.
- class JacobianType(value)[source]
Bases:
StrEnum
The available types for the Jacobian matrix.
- LINEAR_OPERATOR = 'linear_operator'
Jacobian as a SciPy
LinearOperator
implementing the appropriate method to perform matrix-vector products.
- MATRIX = 'matrix'
Jacobian matrix in Compressed Sparse Row (CSR) format.
- assemble_jacobian(functions, variables, is_residual=False, jacobian_type=JacobianType.MATRIX)[source]
Form the Jacobian as a SciPy
LinearOperator
.- Parameters:
functions (Collection[str]) – The functions to differentiate.
variables (Collection[str]) – The differentiation variables.
is_residual (bool) –
Whether the functions are residuals.
By default it is set to False.
jacobian_type (JacobianType) –
The type of representation for the Jacobian ∂f/∂v.
By default it is set to “matrix”.
- Returns:
The Jacobian ∂f/∂v in the specified type.
- Return type:
csr_matrix | JacobianOperator
- compute_dimension(names)[source]
Compute the total number of functions/variables/couplings of the full system.
- compute_newton_step(in_data, couplings, relax_factor, linear_solver='DEFAULT', matrix_type=JacobianType.MATRIX, **linear_solver_options)[source]
Compute the Newton step for the coupled system of disciplines residuals.
- Parameters:
in_data (Mapping[str, Any]) – The input data.
couplings (Collection[str]) – The coupling variables.
linear_solver (str) –
The name of the linear solver.
By default it is set to “DEFAULT”.
matrix_type (JacobianType) –
The representation of the matrix ∂R/∂y (sparse or linear operator).
By default it is set to “matrix”.
**linear_solver_options (Any) – The options passed to the linear solver factory.
- Returns:
The Newton step -[∂R/∂y]^-1 . R as a dict of steps per coupling variable.
- Return type:
- compute_sizes(functions, variables, couplings, residual_variables=None)[source]
Compute the number of scalar functions, variables and couplings.
- Parameters:
- Raises:
ValueError – When the size of some variables could not be determined.
- Return type:
None
- plot_dependency_jacobian(functions, variables, save=True, show=False, filepath=None, markersize=None)[source]
Plot the Jacobian matrix.
Nonzero elements of the sparse matrix are represented by blue squares.
- Parameters:
functions (Collection[str]) – The functions to plot.
variables (Collection[str]) – The variables.
show (bool) –
Whether the plot is displayed.
By default it is set to False.
save (bool) –
Whether the plot is saved in a PDF file.
By default it is set to True.
filepath (str | None) – The file name to save to. If None,
coupled_jacobian.pdf
is used, otherwisecoupled_jacobian_ + filepath + .pdf
.markersize (float | None) – size of the markers
- Returns:
The file name.
- Return type:
- residuals(in_data, var_names)[source]
Form the matrix of residuals wrt coupling variables.
Given disciplinary explicit calculations Yi(Y0_t,…Yn_t), fill the residual matrix:
[Y0(Y0_t,...Yn_t) - Y0_t] [ ] [Yn(Y0_t,...Yn_t) - Yn_t]
- split_jac(coupled_system, variables)[source]
Split a Jacobian dict into a dict of dict.
- total_derivatives(in_data, functions, variables, couplings, linear_solver='DEFAULT', mode=DerivationMode.AUTO, matrix_type=JacobianType.MATRIX, use_lu_fact=False, exec_cache_tol=None, execute=True, residual_variables=None, **linear_solver_options)[source]
Compute the Jacobian of total derivatives of the coupled system.
- Parameters:
in_data – The input data dict.
functions (Collection[str]) – The functions to differentiate.
variables (Collection[str]) – The differentiation variables.
couplings (Iterable[str]) – The coupling variables.
linear_solver (str) –
The name of the linear solver.
By default it is set to “DEFAULT”.
mode (DerivationMode) –
The linearization mode (auto, direct or adjoint).
By default it is set to “auto”.
matrix_type (JacobianType) –
The representation of the matrix ∂R/∂y (sparse or linear operator).
By default it is set to “matrix”.
use_lu_fact (bool) –
Whether to factorize dres_dy once, unsupported for linear operator mode.
By default it is set to False.
exec_cache_tol (float | None) – The discipline cache tolerance to when calling the linearize method. If None, no tolerance is set (equivalent to tol=0.0).
execute (bool) –
Whether to start by executing the discipline with the input data for which to compute the Jacobian; this allows to ensure that the discipline was executed with the right input data; it can be almost free if the corresponding output data have been stored in the
MDODiscipline.cache
.By default it is set to True.
linear_solver_options – The options passed to the linear solver factory.
residual_variables (Mapping[str, str] | None) – a mapping of residuals of disciplines to their respective state variables.
**linear_solver_options (Any) – The options passed to the linear solver factory.
- Returns:
The total coupled derivatives.
- Raises:
ValueError – When the linearization_mode is incorrect.
- Return type:
- coupled_system: CoupledSystem
The coupled derivative system of residuals.
- coupling_structure: MDOCouplingStructure
The considered coupling structure.
- disciplines: dict[str, MDODiscipline]
The MDODisciplines, stored using their name.
- n_newton_linear_resolutions: int
The number of Newton linear resolutions.
- class gemseo.core.derivatives.jacobian_assembly.JacobianOperator(*args, **kwargs)[source]
Bases:
LinearOperator
Representation of the Jacobian as a SciPy
LinearOperator
.- Parameters:
functions (Iterable[str]) – The functions to differentiate.
variables (Iterable[str]) – The differentiation variables.
n_functions (int) – The number of functions components.
n_variables (int) – The number of variables components.
get_jacobian_generator (Callable[[Iterable[str], Iterable[str], bool], Generator]) – The method to iterate over the Jacobians associated with the provided functions and variables.
is_residual (bool) –
Whether the functions are residuals.
By default it is set to False.
- gemseo.core.derivatives.jacobian_assembly.default_dict_factory()[source]
Instantiates a defaultdict(None) object.
- gemseo.core.derivatives.jacobian_assembly.none_factory()[source]
Returns None…
To be used for defaultdict
- Return type:
None