fdvar.adjoint package¶

class fdvar.adjoint.EnsembleAdjVec(subvec, ensemble: Ensemble | None = None)¶

Bases: OverloadedType

A vector of AdjFloat distributed over an Ensemble.

Analagous to the EnsembleFunction and EnsembleCofunction types but for AdjFloat.

Implements basic OverloadedType functionality to be used as a Control or functional.

Parameters:

subvec (list[AdjFloat] | EnsembleAdjVec) – The local part of the vector. If subvec is another EnsembleAdjVec then a copy will be created.
ensemble – The firedrake.Ensemble communicator. Ignored if subvec is an EnsembleAdjVec.

Submodules¶

fdvar.adjoint.ensemble_adjvec module¶

class fdvar.adjoint.ensemble_adjvec.EnsembleAdjVec(subvec, ensemble: Ensemble | None = None)¶

Bases: OverloadedType

A vector of AdjFloat distributed over an Ensemble.

Analagous to the EnsembleFunction and EnsembleCofunction types but for AdjFloat.

Implements basic OverloadedType functionality to be used as a Control or functional.

Parameters:

subvec (list[AdjFloat] | EnsembleAdjVec) – The local part of the vector. If subvec is another EnsembleAdjVec then a copy will be created.
ensemble – The firedrake.Ensemble communicator. Ignored if subvec is an EnsembleAdjVec.

fdvar.adjoint.ensemble_operations module¶

fdvar.adjoint.ensemble_operations.reduction(ensemble: Ensemble, src: EnsembleFunction | EnsembleCofunction | EnsembleAdjVec) → Function | Cofunction | AdjFloat¶

fdvar.adjoint.ensemble_operations.broadcast(ensemble: Ensemble, src: Function | Cofunction | AdjFloat, dst: EnsembleFunction | EnsembleCofunction | EnsembleAdjVec, root: int | None = None) → EnsembleFunction | EnsembleCofunction | EnsembleAdjVec¶

class fdvar.adjoint.ensemble_operations.EnsembleCommunicationBase(ensemble: Ensemble, root: int | None = None)¶

Bases: AbstractReducedFunctional

property controls: list[Control]¶: Return the list of controls on which this functional depends.

property functional: Function | Cofunction | AdjFloat¶

abstract property src¶

abstract property dst¶

property ensemble: Ensemble¶

property root: int | None¶

__call__(values)¶

Compute the reduced functional with supplied control value.

Parameters:

values ([pyadjoint.OverloadedType]) – If you have multiple controls this should be a list of new values for each control in the order you listed the controls to the constructor. If you have a single control it can either be a list or a single object. Each new value should have the same type as the corresponding control.

Returns:

The computed value. Often of type: AdjFloat.

Return type:

OverloadedType

tlm(m_dot)¶

Return the action of the tangent linear model of the functional.

The tangent linear model is evaluated w.r.t. the control on a vector m_dot, around the last supplied value of the control.

Parameters:

m_dot ([pyadjoint.OverloadedType]) – The direction in which to compute the action of the tangent linear model.

Returns:

The action of the tangent linear model in the direction m_dot.: Should be an instance of the same type as the functional.

Return type:

pyadjoint.OverloadedType

derivative(adj_input, apply_riesz: bool = False)¶

Return the derivative of the functional w.r.t. the control.

Using the adjoint method, the derivative of the functional with respect to the control, around the last supplied value of the control, is computed and returned.

Parameters:

adj_input – The adjoint value to the functional result. Required if the functional is not scalar-valued, or if the functional is an intermediate result in the computation of an outer functional.
apply_riesz – If True, apply the Riesz map of each control in order to return a primal gradient rather than a derivative in the dual space.

Returns:

The derivative with respect to the control.: If apply_riesz is False, should be an instance of the type dual to that of the control. If apply_riesz is True should have the same type as the control.

Return type:

pyadjoint.OverloadedType

hessian(m_dot, hessian_input=None, evaluate_tlm: bool = True, apply_riesz: bool = False)¶

Return the action of the Hessian of the functional.

The Hessian is evaluated w.r.t. the control on a vector m_dot.

Using the second-order adjoint method, the action of the Hessian of the functional with respect to the control, around the last supplied value of the control, is computed and returned.

Parameters:

m_dot ([pyadjoint.OverloadedType]) – The direction in which to compute the action of the Hessian.
hessian_input (pyadjoint.OverloadedType) – The Hessian value for the functional result. Required if the functional is not scalar-valued, or if the functional is an intermediate result in the computation of an outer functional.
evaluate_tlm (bool) – If True, will evaluate the tangent linear model before evaluating the Hessian. If False, assumes that the tape is already populated with the tangent linear values and does not evaluate them.
apply_riesz (bool) – If True, apply the Riesz map of each control in order to return the (primal) Riesz representer of the Hessian action.

Returns:

The action of the Hessian in the direction m_dot.: If apply_riesz is False, should be an instance of the type dual to that of the control. If apply_riesz is True should have the same type as the control.

Return type:

pyadjoint.OverloadedType

class fdvar.adjoint.ensemble_operations.EnsembleReduce(src: EnsembleFunction | EnsembleCofunction | EnsembleAdjVec, root: int | None = None)¶

Bases: EnsembleCommunicationBase

property src: EnsembleFunction | EnsembleCofunction | EnsembleAdjVec¶

property dst: Function | Cofunction | AdjFloat¶

forward(src: EnsembleFunction | EnsembleCofunction | EnsembleAdjVec) → Function | Cofunction | AdjFloat¶

backward(src: Function | Cofunction | AdjFloat) → EnsembleFunction | EnsembleCofunction | EnsembleAdjVec¶

class fdvar.adjoint.ensemble_operations.EnsembleBcast(dst: EnsembleFunction | EnsembleCofunction | EnsembleAdjVec, root: int | None = None)¶

Bases: EnsembleCommunicationBase

property src: Function | Cofunction | AdjFloat¶

property dst: EnsembleFunction | EnsembleCofunction | EnsembleAdjVec¶

forward(src: Function | Cofunction | AdjFloat) → EnsembleFunction | EnsembleCofunction | EnsembleAdjVec¶

backward(src: EnsembleFunction | EnsembleCofunction | EnsembleAdjVec) → Function | Cofunction | AdjFloat¶

class fdvar.adjoint.ensemble_operations.EnsembleTransform(functional: EnsembleFunction | EnsembleCofunction | EnsembleAdjVec, controls: Control | Sequence[Control], rfs: list[AbstractReducedFunctional])¶

Bases: AbstractReducedFunctional

property controls: list[Control]¶: Return the list of controls on which this functional depends.

property functional: EnsembleFunction | EnsembleCofunction | EnsembleAdjVec¶

property rfs: list[AbstractReducedFunctional]¶

property ensemble: Ensemble¶

Compute the reduced functional with supplied control value.

Parameters:

values ([pyadjoint.OverloadedType]) – If you have multiple controls this should be a list of new values for each control in the order you listed the controls to the constructor. If you have a single control it can either be a list or a single object. Each new value should have the same type as the corresponding control.

Returns:

The computed value. Often of type: AdjFloat.

Return type:

OverloadedType

Return the action of the tangent linear model of the functional.

The tangent linear model is evaluated w.r.t. the control on a vector m_dot, around the last supplied value of the control.

Parameters:

m_dot ([pyadjoint.OverloadedType]) – The direction in which to compute the action of the tangent linear model.

Returns:

The action of the tangent linear model in the direction m_dot.: Should be an instance of the same type as the functional.

Return type:

pyadjoint.OverloadedType

Return the derivative of the functional w.r.t. the control.

Using the adjoint method, the derivative of the functional with respect to the control, around the last supplied value of the control, is computed and returned.

Parameters:

adj_input – The adjoint value to the functional result. Required if the functional is not scalar-valued, or if the functional is an intermediate result in the computation of an outer functional.
apply_riesz – If True, apply the Riesz map of each control in order to return a primal gradient rather than a derivative in the dual space.

Returns:

The derivative with respect to the control.: If apply_riesz is False, should be an instance of the type dual to that of the control. If apply_riesz is True should have the same type as the control.

Return type:

pyadjoint.OverloadedType

Return the action of the Hessian of the functional.

The Hessian is evaluated w.r.t. the control on a vector m_dot.

Using the second-order adjoint method, the action of the Hessian of the functional with respect to the control, around the last supplied value of the control, is computed and returned.

Parameters:

m_dot ([pyadjoint.OverloadedType]) – The direction in which to compute the action of the Hessian.
hessian_input (pyadjoint.OverloadedType) – The Hessian value for the functional result. Required if the functional is not scalar-valued, or if the functional is an intermediate result in the computation of an outer functional.
evaluate_tlm (bool) – If True, will evaluate the tangent linear model before evaluating the Hessian. If False, assumes that the tape is already populated with the tangent linear values and does not evaluate them.
apply_riesz (bool) – If True, apply the Riesz map of each control in order to return the (primal) Riesz representer of the Hessian action.

Returns:

The action of the Hessian in the direction m_dot.: If apply_riesz is False, should be an instance of the type dual to that of the control. If apply_riesz is True should have the same type as the control.

Return type:

pyadjoint.OverloadedType

class fdvar.adjoint.ensemble_operations.EnsembleShift(x: EnsembleFunction | EnsembleCofunction | EnsembleAdjVec, ensemble: Ensemble)¶

Bases: EnsembleCommunicationBase

property src: EnsembleFunction | EnsembleCofunction | EnsembleAdjVec¶

property dst: EnsembleFunction | EnsembleCofunction | EnsembleAdjVec¶

forward(x: EnsembleFunction | EnsembleCofunction | EnsembleAdjVec) → EnsembleFunction | EnsembleCofunction | EnsembleAdjVec¶

backward(x: EnsembleFunction | EnsembleCofunction | EnsembleAdjVec) → EnsembleFunction | EnsembleCofunction | EnsembleAdjVec¶

fdvar.adjoint.reduced_functional_pipeline module¶

class fdvar.adjoint.reduced_functional_pipeline.ReducedFunctionalPipeline(*rfs: Iterable[AbstractReducedFunctional])¶

Bases: AbstractReducedFunctional

Class representing the composition of two or more reduced functionals.

For two reduced functionals J1: X->Y and J2: Y->Z, the composition is:

(J1 o J2): X -> Z = J2(J1(x))

and, if X* and Z* are the dual spaces of X and Z, the derivative is:

d(J1 o J2): Z* -> X* = J1.derivative(J2.derivative(adj_input))

The control of J2 must be in the same space as the functional of J1.

The TLM and Hessian actions have the same forward/backward composition. The composition of three or more reduced functionals follows.

Parameters:: *rfs – A list of the reduced functionals J1,J2,…,Jn

property controls: list[Control]¶: Return the list of controls on which this functional depends.

property functional: OverloadedType¶

property reduced_functionals: list[AbstractReducedFunctional]¶

__call__(values: OverloadedType) → OverloadedType¶

Compute the reduced functional with supplied control value.

Parameters:

values ([pyadjoint.OverloadedType]) – If you have multiple controls this should be a list of new values for each control in the order you listed the controls to the constructor. If you have a single control it can either be a list or a single object. Each new value should have the same type as the corresponding control.

Returns:

The computed value. Often of type: AdjFloat.

Return type:

OverloadedType

derivative(adj_input: OverloadedType = 1.0, apply_riesz: bool = False) → OverloadedType¶

Return the derivative of the functional w.r.t. the control.

Using the adjoint method, the derivative of the functional with respect to the control, around the last supplied value of the control, is computed and returned.

Parameters:

adj_input – The adjoint value to the functional result. Required if the functional is not scalar-valued, or if the functional is an intermediate result in the computation of an outer functional.
apply_riesz – If True, apply the Riesz map of each control in order to return a primal gradient rather than a derivative in the dual space.

Returns:

The derivative with respect to the control.: If apply_riesz is False, should be an instance of the type dual to that of the control. If apply_riesz is True should have the same type as the control.

Return type:

pyadjoint.OverloadedType

tlm(m_dot: OverloadedType) → OverloadedType¶

Return the action of the tangent linear model of the functional.

The tangent linear model is evaluated w.r.t. the control on a vector m_dot, around the last supplied value of the control.

Parameters:

m_dot ([pyadjoint.OverloadedType]) – The direction in which to compute the action of the tangent linear model.

Returns:

The action of the tangent linear model in the direction m_dot.: Should be an instance of the same type as the functional.

Return type:

pyadjoint.OverloadedType

hessian(m_dot: OverloadedType, hessian_input: OverloadedType | None = None, evaluate_tlm: bool = True, apply_riesz: bool = False) → OverloadedType¶

Return the action of the Hessian of the functional.

The Hessian is evaluated w.r.t. the control on a vector m_dot.

Using the second-order adjoint method, the action of the Hessian of the functional with respect to the control, around the last supplied value of the control, is computed and returned.

Parameters:

m_dot ([pyadjoint.OverloadedType]) – The direction in which to compute the action of the Hessian.
hessian_input (pyadjoint.OverloadedType) – The Hessian value for the functional result. Required if the functional is not scalar-valued, or if the functional is an intermediate result in the computation of an outer functional.
evaluate_tlm (bool) – If True, will evaluate the tangent linear model before evaluating the Hessian. If False, assumes that the tape is already populated with the tangent linear values and does not evaluate them.
apply_riesz (bool) – If True, apply the Riesz map of each control in order to return the (primal) Riesz representer of the Hessian action.

Returns:

The action of the Hessian in the direction m_dot.: If apply_riesz is False, should be an instance of the type dual to that of the control. If apply_riesz is True should have the same type as the control.

Return type:

pyadjoint.OverloadedType