gemseo.core.derivatives.jacobian_assembly module#

Coupled derivatives calculations.

class AssembledJacobianOperator(*args, **kwargs)[source]#

Bases: LinearOperator

Representation of the assembled 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], Iterator[tuple[RealOrComplexArray, JacobianAssembly.JacobianPosition]]]) -- 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.

class 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_settings)[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_settings (Any) -- The optional parameters.

Returns:

The Jacobian of total coupled derivatives.

Return type:

dict[str, RealArray]

direct_mode(functions, n_variables, n_couplings, dres_dx, dres_dy, dfun_dx, dfun_dy, linear_solver='DEFAULT', use_lu_fact=False, **linear_solver_settings)[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_settings (Any) -- The optional parameters.

Returns:

The Jacobian of the total coupled derivatives.

Return type:

dict[str, dok_matrix]

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 JacobianAssembly(coupling_structure)[source]#

Bases: object

Assembly of Jacobians.

Typically, assemble discipline's Jacobians into a system Jacobian.

Parameters:

coupling_structure (CouplingStructure) -- The CouplingStructure 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)

Parameters:
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 | AssembledJacobianOperator

compute_dimension(names)[source]#

Compute the total number of functions/variables/couplings of the full system.

Parameters:

names (Iterable[str]) -- The names of the inputs or the outputs.

Returns:

The dimension if the system.

Return type:

int

compute_newton_step(in_data, couplings, linear_solver='DEFAULT', matrix_type=JacobianType.MATRIX, residuals=None, resolved_residual_names=(), **linear_solver_settings)[source]#

Compute the Newton step for the coupled system of disciplines residuals.

Parameters:

  • in_data (Mapping[str, RealArray]) -- 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".

  • residuals (RealOrComplexArray | None) -- The residuals vector, if None use residuals.

  • resolved_residual_names (Collection[str]) --

    The names of residual variables.

    By default it is set to ().

  • **linear_solver_settings (Any) -- The options passed to the linear solver factory.

Returns:

The Newton step - relax_factor . [∂R/∂y]^-1 . R as an array of steps for which the order is given by the couplings argument. Whether the linear solver converged.

Return type:

tuple[RealOrComplexArray, bool]

compute_sizes(functions, variables, couplings, residual_variables=mappingproxy({}))[source]#

Compute the number of scalar functions, variables and couplings.

Parameters:

  • functions (Iterable[str]) -- The functions to differentiate.

  • variables (Iterable[str]) -- The differentiation variables.

  • couplings (Iterable[str]) -- The coupling variables.

  • residual_variables (Mapping[str, str]) --

    The mapping of residuals of disciplines to their respective state variables.

    By default it is set to {}.

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='', 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) --

    The file name to save to. If empty, coupled_jacobian.pdf is used, otherwise coupled_jacobian_ + filepath + .pdf.

    By default it is set to "".

  • markersize (float | None) -- The size of the markers.

Returns:

The file name.

Return type:

str

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]
Parameters:

  • in_data (StrKeyMapping) -- The values prescribed for the calculation of the residuals (Y0_t,...Yn_t).

  • var_names (Iterable[str]) -- The names of variables associated with the residuals (R).

Returns:

The residuals array.

Return type:

RealOrComplexArray

set_newton_differentiated_ios(couplings)[source]#

Set the differentiated inputs and outputs for the Newton algorithm.

Also ensures that JacobianAssembly.sizes contains the sizes of all the coupling sizes needed for Newton.

Parameters:

couplings (Collection[str]) -- The coupling variables.

Return type:

None

split_jac(coupled_system, variables)[source]#

Split a Jacobian dict into a dict of dict.

Parameters:

  • coupled_system (Mapping[str, RealOrComplexArray | dok_matrix]) -- The derivatives to split.

  • variables (Iterable[str]) -- The variables wrt which the differentiation is performed.

Returns:

The Jacobian.

Return type:

dict[str, dict[str, RealOrComplexArray | dok_matrix]]

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=mappingproxy({}), **linear_solver_settings)[source]#

Compute the Jacobian of total derivatives of the coupled system.

Parameters:

  • in_data (StrKeyMapping) -- 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 Discipline.cache.

    By default it is set to True.

  • linear_solver_settings -- The options passed to the linear solver factory.

  • residual_variables (Mapping[str, str]) --

    a mapping of residuals of disciplines to their respective state variables.

    By default it is set to {}.

  • **linear_solver_settings (Any) -- The options passed to the linear solver factory.

Returns:

The total coupled derivatives.

Raises:

ValueError -- When the linearization_mode is incorrect.

Return type:

dict[str, dict[str, RealOrComplexArray]] | dict[Any, dict[Any, None]]

coupled_system: CoupledSystem#

The coupled derivative system of residuals.

coupling_structure: CouplingStructure#

The considered coupling structure.

disciplines: dict[str, Discipline]#

The disciplines, stored using their name.

sizes: dict[str, int]#

The number of elements of a given str.

default_dict_factory()[source]#

Instantiates a defaultdict(None) object.

Return type:

dict[Any, None]

none_factory()[source]#

Returns None...

To be used for defaultdict

Return type:

None