gemseo / core / derivatives

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

• 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:

dict[str, ndarray]

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:

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

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.

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, relax_factor, linear_solver='DEFAULT', matrix_type='sparse', **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 (Iterable[str]) – The coupling variables.

• relax_factor (float | int) – The relaxation factor.

• linear_solver (str) –

The name of the linear solver.

By default it is set to “DEFAULT”.

• matrix_type (str) –

The representation of the matrix dR/dy (sparse or linear operator).

By default it is set to “sparse”.

• **linear_solver_options (Any) – The options passed to the linear solver factory.

Returns:

The Newton step -[dR/dy]^-1 . R as a dict of steps per coupling variable.

Return type:

dict[str, ndarray]

compute_sizes(functions, variables, couplings, residual_variables=None)[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] | None) – The mapping of residuals of disciplines to their respective state variables.

Raises:

ValueError – When the size of some variables could not be determined.

Return type:

None

dfun_dvar(function, variables, n_variables)[source]

Forms the matrix of partial derivatives of a function.

Given disciplinary Jacobians dJi(v0…vn)/dvj, fill the sparse Jacobian: | | | dJi/dvj | | |

Parameters:
• function (str) – The function to differentiate.

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

• n_variables (int) – The number of variables.

Returns:

The full Jacobian matrix.

Return type:

dok_matrix

dres_dvar(residuals, variables, n_residuals, n_variables, matrix_type='sparse', transpose=False)[source]

Form the matrix of partial derivatives of residuals.

Given disciplinary Jacobians dYi(Y0…Yn)/dvj, fill the sparse Jacobian: | | | dRi/dvj | | | (Default value = False)

Parameters:
• residuals (Iterable[str]) – The residuals.

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

• n_residuals (int) – The number of residuals.

• n_variables (int) – The number of variables.

• matrix_type (str) –

The type of the matrix.

By default it is set to “sparse”.

• transpose (bool) –

Whether to transpose the matrix.

By default it is set to False.

Returns:

The jacobian of dres_dvar.

Raises:

TypeError – When the matrix type is unknown.

Return type:

dok_matrix | LinearOperator

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 (Iterable[str]) – The functions to plot.

• variables (Iterable[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, otherwise coupled_jacobian_ + filepath + .pdf.

• markersize (float | None) – 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 (Mapping[str, Any]) – 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:

ndarray

split_jac(coupled_system, variables)[source]

Split a Jacobian dict into a dict of dict.

Parameters:
• coupled_system (Mapping[str, ndarray | dok_matrix]) – The derivatives to split.

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

Returns:

The Jacobian.

Return type:

dict[str, ndarray | dok_matrix]

total_derivatives(in_data, functions, variables, couplings, linear_solver='DEFAULT', mode='auto', matrix_type='sparse', use_lu_fact=False, exec_cache_tol=None, force_no_exec=False, 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 (Iterable[str]) – The functions to differentiate.

• variables (Iterable[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 (str) –

The linearization mode (auto, direct or adjoint).

By default it is set to “auto”.

• matrix_type (str) –

The representation of the matrix dR/dy (sparse or linear operator).

By default it is set to “sparse”.

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

• force_no_exec (bool) –

Whether the discipline is not re-executed, the cache is loaded anyway.

By default it is set to False.

• 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:

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

The name of the adjoint mode.

AUTO_MODE: ClassVar[str] = 'auto'

The name of the auto-mode.

AVAILABLE_MAT_TYPES: ClassVar[tuple[str]] = ('sparse', 'linear_operator')

The enumeration of the available matrix types.

AVAILABLE_MODES: ClassVar[tuple[str]] = ('direct', 'adjoint', 'auto', 'reverse')

The enumeration of the available modes.

DIRECT_MODE: ClassVar[str] = 'direct'

The name of the direct mode.

LINEAR_OPERATOR: ClassVar[str] = 'linear_operator'

The name for linear operators.

REVERSE_MODE: ClassVar[str] = 'reverse'

The name of the reverse mode.

SPARSE: ClassVar[str] = 'sparse'

The name for sparse matrices.

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.

sizes: dict[str, int]

The number of elements of a given str.

gemseo.core.derivatives.jacobian_assembly.default_dict_factory()[source]

Instantiates a defaultdict(None) object.

Return type:

dict[Any, None]

gemseo.core.derivatives.jacobian_assembly.none_factory()[source]

Returns None…

To be used for defaultdict

Return type:

None