dragonfly_sim.utils.derived_fields

Derived fields and the chain rule through them.

A derived field is a Function the residual (or a force functional) reads that is not one of the unknowns, but is itself a function of the state U, the angle of attack alpha and/or the mesh coordinates x:

the Green-Gauss gradient G = M^-1 b(U, alpha, x) (core/reconstruction.py) the cell centres c = C x (core/reconstruction.py) the wall distance d = d(x) (core/wall_distance.py)

For R(U, f(U, alpha, x), alpha, x) every total derivative picks up one chain term per field,

dR/dU = dR/dU|_f + sum_f (dR/df) (df/dU) dR/dalpha = dR/dalpha|_f + sum_f (dR/df) (df/dalpha) dR/dx = dR/dx|_f + sum_f (dR/df) (df/dx)

and the same holds for a scalar functional J. A DerivedField supplies the three right-hand factors; DerivedFieldChainRule assembles the partial derivatives with UFL and combines them. With no derived fields nothing here is used, and the model’s derivative assemblers are the plain UFL ones.

Classes

`DerivedField`	Interface. function is the dolfinx Function the forms read.
`DerivedFieldChainRule`	Total derivatives of a residual form F (rank 1) or a functional J
`_ChainedMeshOperator`	Python-Mat context: y = A_x v + sum_k A_k (X_k v), and its transpose.

Functions

`_assemble_mat`(form)
`_assemble_vec`(form)
`_nonempty`(form)	The form with derivatives expanded, or None if it is identically zero.
`_shell_matrix`(A_x, chains)
`destroy_chained_operator`(M)	Free a residual_mesh_operator result and the matrices it holds now.
`destroy_operator`(obj)	Destroy a PETSc Mat or Vec. A python-context Mat's context frees what it
`diagonal_mass_inverse`(V, dx)	1/\|K\| per dof of a DG0 (blocked) space V: the inverse of its diagonal
`mesh_coordinate_argument`(form, coordinate_space)	The Argument a mesh-coordinate derivative of form is taken along.

Module Contents

class dragonfly_sim.utils.derived_fields.DerivedField

Interface. function is the dolfinx Function the forms read.

update() recompute the field at the current state and mesh update_geometry() refresh whatever depends on the mesh only (called

after mesh motion, before update())

state_jacobian() PETSc Mat d(field)/dU (only if depends_on_state) alpha_vector() PETSc Vec d(field)/dalpha, or None mesh_jacobian() PETSc Mat d(field)/dx, columns in the mesh’s

coordinate_space, or None

alpha_vector()

discard(obj): Free a matrix or vector returned by state_jacobian / alpha_vector / mesh_jacobian once the caller is done with it. A field that caches them keeps its own (override); a python-context operator also frees what its context holds.

mesh_jacobian()

release_cache(): Free whatever the field caches between calls (nothing by default).

state_jacobian()

update()

update_geometry()

depends_on_state = False

function = None

class dragonfly_sim.utils.derived_fields.DerivedFieldChainRule(mesh_obj, u, fields, alpha_var=None, jit_options=None)

Total derivatives of a residual form F (rank 1) or a functional J (rank 0) through a list of DerivedFields. Compiled forms are cached per (form id, field) on this object, so reuse one instance per model.

_compiled(key, factory)

_partial_field(form, key, field): dform/dfield: a matrix form (rank-1 form) or a vector form (rank 0).

functional_alpha(J, key): dJ/dalpha (total) as a number. Collective.

functional_mesh(J, key): dJ/dx (total) as a Vec on the mesh’s coordinate_space.

functional_state(J, key): dJ/dU (total) as a Vec in the state layout.

residual_alpha(F, key, out): out <- dR/dalpha (total); out is a Vec in the residual’s layout.

residual_mesh_operator(F, key): dR/dx (total) as a PETSc python Mat with mult / multTranspose.

update()

_forms

alpha_var = None

fields

jit_options

mesh_obj

u

class dragonfly_sim.utils.derived_fields._ChainedMeshOperator(A_x, chains)

Python-Mat context: y = A_x v + sum_k A_k (X_k v), and its transpose.

mult(mat, v, y)

multTranspose(mat, w, y)

A_x

_work

chains

dragonfly_sim.utils.derived_fields._assemble_mat(form)

dragonfly_sim.utils.derived_fields._assemble_vec(form)

dragonfly_sim.utils.derived_fields._nonempty(form): The form with derivatives expanded, or None if it is identically zero.

dragonfly_sim.utils.derived_fields._shell_matrix(A_x, chains)

dragonfly_sim.utils.derived_fields.destroy_chained_operator(M): Free a residual_mesh_operator result and the matrices it holds now. Left to the garbage collector, a parallel petsc4py object is only queued, and freed at the next PETSc.garbage_cleanup; for a 3D RANS operator that is several GB held into the next adjoint.

dragonfly_sim.utils.derived_fields.destroy_operator(obj): Destroy a PETSc Mat or Vec. A python-context Mat’s context frees what it owns in its destroy(mat) method, which PETSc calls with the Mat.

dragonfly_sim.utils.derived_fields.diagonal_mass_inverse(V, dx): 1/|K| per dof of a DG0 (blocked) space V: the inverse of its diagonal mass matrix, as a Vec in V’s layout.

dragonfly_sim.utils.derived_fields.mesh_coordinate_argument(form, coordinate_space): The Argument a mesh-coordinate derivative of form is taken along.