Warning

You are reading a version of the website built against the unstable main branch. This content is liable to change without notice and may be inappropriate for your use case. You can find the documentation for the current stable release here.

firedrake.ensemble package

Submodules

firedrake.ensemble.ensemble module

class firedrake.ensemble.ensemble.Ensemble(comm, M, **kwargs)[source]

Bases: object

allreduce(f, f_reduced=None, op=<mpi4py.MPI.Op object>)[source]

Allreduce a firedrake.function.Function f into f_reduced.

Parameters:
Returns:

The result of the reduction.

Return type:

firedrake.function.Function | Cofunction

Raises:

ValueError – If Function communicators mismatch each other or the ensemble spatial communicator, or if the Functions are in different spaces

bcast(f, root=0)[source]

Broadcast a firedrake.function.Function f over ensemble_comm from ensemble_rank root.

Parameters:
Returns:

The result of the broadcast.

Return type:

firedrake.function.Function | Cofunction

Raises:

ValueError – If the Function communicator mismatches the ensemble.comm.

property ensemble_rank

The rank of the local ensemble member.

property ensemble_size

The number of ensemble members.

iallreduce(f, f_reduced=None, op=<mpi4py.MPI.Op object>)[source]

Allreduce (non-blocking) a firedrake.function.Function f into f_reduced.

Parameters:
Returns:

MPI request.

Return type:

mpi4py.MPI.Request

Raises:

ValueError – If Function communicators mismatch each other or the ensemble spatial communicator, or if the Functions are in different spaces

ibcast(f, root=0)[source]

Broadcast (non-blocking) a firedrake.function.Function f over ensemble_comm ensemble_rank root.

Parameters:
Returns:

MPI request.

Return type:

mpi4py.MPI.Request

Raises:

ValueError – If the Function communicator mismatches the ensemble.comm.

irecv(f, source=-1, tag=-1)[source]

Receive (non-blocking) a firedrake.function.Function f over ensemble_comm from another ensemble_rank.

Parameters:
Returns:

MPI request.

Return type:

mpi4py.MPI.Request

Raises:

ValueError – If the Function communicator mismatches the ensemble.comm.

ireduce(f, f_reduced=None, op=<mpi4py.MPI.Op object>, root=0)[source]

Reduce (non-blocking) a firedrake.function.Function f into f_reduced.

Parameters:
  • f – The a firedrake.function.Function to reduce.

  • f_reduced – The result of the reduction. Must be in the same FunctionSpace() as f.

  • op – MPI reduction operator. Defaults to MPI.SUM.

  • root – The ensemble rank to reduce to.

Returns:

MPI request.

Return type:

mpi4py.MPI.Request

Raises:

ValueError – If Function communicators mismatch each other or the ensemble spatial communicator, or if the Functions are in different spaces

isend(f, dest, tag=0)[source]

Send (non-blocking) a firedrake.function.Function f over ensemble_comm to another ensemble_rank.

Parameters:
Returns:

MPI request.

Return type:

mpi4py.MPI.Request

Raises:

ValueError – If the Function communicator mismatches the ensemble.comm.

isendrecv(fsend, dest, sendtag=0, frecv=None, source=-1, recvtag=-1)[source]

Send (non-blocking) a firedrake.function.Function fsend and receive a firedrake.function.Function frecv over ensemble_comm to/from other ensemble_rank.

fsend and frecv do not need to be in the same function space.

Parameters:
Returns:

MPI request objects (one for each of fsend and frecv).

Return type:

list[mpi4py.MPI.Request]

Raises:

ValueError – If the Function communicators mismatches each other or the ensemble.comm.

recv(f, source=-1, tag=-1, status=None)[source]

Receive (blocking) a firedrake.function.Function f over ensemble_comm from another ensemble_rank.

Parameters:
Returns:

f with the received data.

Return type:

firedrake.function.Function | Cofunction

Raises:
  • ValueError – If the Function communicator mismatches the ensemble.comm.

  • ValueError – If the number of statuses provided is not the number of subfunctions of f.

reduce(f, f_reduced=None, op=<mpi4py.MPI.Op object>, root=0)[source]

Reduce a firedrake.function.Function f into f_reduced.

Parameters:
  • f – The firedrake.function.Function to reduce.

  • f_reduced – The result of the reduction. Must be in the same FunctionSpace() as f.

  • op – MPI reduction operator. Defaults to MPI.SUM.

  • root – The ensemble rank to reduce to.

Returns:

The result of the reduction.

Return type:

firedrake.function.Function | Cofunction

Raises:

ValueError – If Function communicators mismatch each other or the ensemble spatial communicator, or if the Functions are in different spaces

send(f, dest, tag=0)[source]

Send (blocking) a firedrake.function.Function f over ensemble_comm to another ensemble_rank.

Parameters:
Raises:

ValueError – If the Function communicator mismatches the ensemble.comm.

sendrecv(fsend, dest, sendtag=0, frecv=None, source=-1, recvtag=-1, statuses=None)[source]

Send (blocking) a firedrake.function.Function fsend and receive a firedrake.function.Function frecv over ensemble_comm to/from other ensemble_rank.

fsend and frecv do not need to be in the same function space but do need to have the same number of subfunctions.

Parameters:
Returns:

frecv with the received data.

Return type:

firedrake.function.Function | Cofunction

Raises:
  • ValueError – If the Function communicators mismatches each other or the ensemble.comm.

  • ValueError – If the number of statuses provided is not the number of subfunctions of f.

sequential(*, synchronise=False, reverse=False, **kwargs)[source]

Context manager for executing code on each ensemble member consecutively (ordered by increasing ensemble_rank).

Any data in kwargs will be made available in the returned context and will be communicated forward after each ensemble member exits. firedrake.function.Function or Cofunction kwargs will be sent with the corresponding Ensemble methods.

For example:

with ensemble.sequential(index=0) as ctx:
    print(ensemble.ensemble_rank, ctx.index)
    ctx.index += 2

Would print:

0 0
1 2
2 4
3 6
...

If reverse is True then the ensemble ranks will be looped through in decreasing order i.e. ensemble_rank == (ensemble_size - 1) will run first, then ensemble_rank == (ensemble_size - 2) etc.

Parameters:
  • synchronise – If True then MPI_Barrier will be called on the global_comm at the beginning and end of this method.

  • reverse – If True then will iterate through spatial comms in order of decreasing ensemble_rank.

  • kwargs – Data to be passed forward by each rank and made available in the returned ctx.

firedrake.ensemble.ensemble_function module

class firedrake.ensemble.ensemble_function.EnsembleCofunction(function_space)[source]

Bases: EnsembleFunctionBase

A mixed finite element Cofunction distributed over an ensemble.

Parameters:

function_space (EnsembleDualSpace) – The function space of the cofunction.

class firedrake.ensemble.ensemble_function.EnsembleFunction(function_space)[source]

Bases: EnsembleFunctionBase

A mixed Function defined on a Ensemble. The subcomponents are distributed over the ensemble members, and are specified locally in an EnsembleFunctionSpace.

Parameters:

function_space (EnsembleFunctionSpace.) – The function space of the Function.

Notes

Passing an EnsembleDualSpace to EnsembleFunction will return an instance of EnsembleCofunction.

This class does not carry UFL symbolic information, unlike a firedrake.function.Function. UFL expressions can only be defined locally on each ensemble member using a firedrake.function.Function from EnsembleFunction.subfunctions.

norm(*args, **kwargs)[source]

Compute the norm of the function.

Any arguments are forwarded to norm().

class firedrake.ensemble.ensemble_function.EnsembleFunctionBase(function_space)[source]

Bases: EnsembleFunctionMixin

A mixed (co)function defined on a Ensemble. The subcomponents are distributed over the ensemble members, and are specified locally in an EnsembleFunctionSpace.

Parameters:

function_space – The function space of the (co)function.

Notes

Passing an EnsembleDualSpace to EnsembleFunction will return an instance of EnsembleCofunction.

This class does not carry UFL symbolic information, unlike a Function. UFL expressions can only be defined locally on each ensemble member using a \(~firedrake.function.Function\) from EnsembleFunction.subfunctions.

assign(other, subsets=None)[source]

Set the EnsembleFunction to the value of another EnsembleFunction other.

Parameters:
  • other (EnsembleFunction) – The value to assign from.

  • subsets (Collection[Optional[pyop3.Index]]) – One subset for each local firedrake.function.Function. None elements will be ignored. The values of each local function will only be assigned on the nodes on the corresponding subset.

copy()[source]

Return a deep copy of the EnsembleFunction.

function_space()[source]
riesz_representation(**kwargs)[source]

Return the Riesz representation of this EnsembleFunction with respect to the given Riesz map.

Internally delegates to the firedrake.function.Function.riesz_representation() of each component.

Parameters:
  • riesz_map – The Riesz map to use (\(l2\), \(L2\), or \(H1\)). This can also be a callable.

  • kwargs – other arguments to be passed to the firedrake.riesz_map.

property subfunctions[source]

The (co)functions on the local ensemble member.

vec()[source]

Context manager for the global PETSc.Vec with read/write access.

It is invalid to access the Vec outside of a context manager.

vec_ro()[source]

Context manager for the global PETSc.Vec with read only access.

It is invalid to access the Vec outside of a context manager.

vec_wo()[source]

Context manager for the global PETSc.Vec with write only access.

It is invalid to access the Vec outside of a context manager.

zero(subsets=None)[source]

Set values to zero.

Parameters:

subsets (Collection[pyop3.Index | None]) – One subset for each local firedrake.function.Function. None elements will be ignored. The values of each local function will only be zeroed on the nodes on the corresponding subset.

firedrake.ensemble.ensemble_functionspace module

class firedrake.ensemble.ensemble_functionspace.EnsembleDualSpace(local_spaces, ensemble)[source]

Bases: EnsembleFunctionSpaceBase

A mixed dual function space defined on an ensemble.Ensemble. The subcomponents are distributed over the ensemble members, but are specified locally on each ensemble member.

Parameters:
  • local_spaces (Collection) – The list of dual function spaces on the local ensemble.comm.

  • ensemble (\(.ensemble.Ensemble\)) – The communicator that the function space is defined over.

Notes

Passing a list of dual local_spaces to EnsembleFunctionSpace will return an instance of EnsembleDualSpace.

This class does not carry UFL symbolic information, unlike a FiredrakeDualSpace. UFL expressions can only be defined locally on each ensemble member using a FiredrakeDualSpace from \(EnsembleDualSpace.local_spaces\).

Examples

If U=CG1, V=DG0, and W=U*V, we can have the nested mixed dual space U*xV*xV*xW*xU*. This can be distributed over an ensemble.Ensemble with two ensemble members by splitting into [U*xV*]x[V*xW*xU*]. The following code creates the corresponding EnsembleDualSpace:

ensemble = Ensemble(COMM_WORLD, COMM_WORLD.size//2)
mesh = UnitIntervalMesh(8, comm=ensemble.comm)
U = FunctionSpace(mesh, "CG", 1)
V = FunctionSpace(mesh, "DG", 0)
W = U*V

if ensemble.ensemble_rank == 0:
    local_spaces = [U.dual(), V.dual()]
else:
    local_spaces = [V.dual(), W.dual(), U.dual()]

efs0 = EnsembleDualSpace(local_spaces, ensemble)
efs1 = EnsembleFunctionSpace(local_spaces, ensemble)
class firedrake.ensemble.ensemble_functionspace.EnsembleFunctionSpace(local_spaces, ensemble)[source]

Bases: EnsembleFunctionSpaceBase

A mixed primal function space defined on an Ensemble. The subcomponents are distributed over the ensemble members, but are specified locally on each ensemble member.

Parameters:
  • local_spaces (Collection) – The list of primal function spaces on the local Ensemble.comm.

  • ensemble (Ensemble) – The communicator that the function space is defined over.

Notes

Passing a list of dual local_spaces to EnsembleFunctionSpace will return an instance of EnsembleDualSpace.

This class does not carry UFL symbolic information, unlike a FunctionSpace. UFL expressions can only be defined locally on each ensemble member using a FunctionSpace from \(EnsembleFunctionSpace.local_spaces\).

Examples

If U=CG1, V=DG0, and W=UxV, we can have the nested mixed space UxVxVxWxU. This can be distributed over an ensemble.Ensemble with two ensemble members by splitting into [UxV]x[VxWxU]. The following code creates the corresponding EnsembleFunctionSpace:

ensemble = Ensemble(COMM_WORLD, COMM_WORLD.size//2)
mesh = UnitIntervalMesh(8, comm=ensemble.comm)
U = FunctionSpace(mesh, "CG", 1)
V = FunctionSpace(mesh, "DG", 0)
W = U*V

if ensemble.ensemble_rank == 0:
    local_spaces = [U, V]
else:
    local_spaces = [V, W, U]

efs = EnsembleFunctionSpace(local_spaces, ensemble)
class firedrake.ensemble.ensemble_functionspace.EnsembleFunctionSpaceBase(local_spaces, ensemble)[source]

Bases: object

Base class for mixed function spaces defined on an Ensemble. The subcomponents are distributed over the ensemble members, and are specified locally.

Parameters:
  • local_spaces (Collection) – The list of function spaces on the local ensemble.comm.

  • ensemble (\(~.ensemble.Ensemble\)) – The communicator that the function space is defined over.

Notes

Passing a list of dual local_spaces to EnsembleFunctionSpace will return an instance of EnsembleDualSpace.

This class does not carry UFL symbolic information, unlike a FunctionSpace. UFL expressions can only be defined locally on each ensemble member using a FunctionSpace from \(EnsembleFunctionSpace.local_spaces\).

property comm

The spatial communicator from the Ensemble communicator.

create_vec()[source]

Return a PETSc Vec on the Ensemble.global_comm with the same layout as an EnsembleFunction or EnsembleCofunction in this function space.

dual()[source]

The dual to this function space. A EnsembleDualSpace if self is a EnsembleFunctionSpace, and vice-versa.

property ensemble

The Ensemble that the function space is defined over

property ensemble_comm

The ensemble communicator from the Ensemble communicator.

property global_comm

The global communicator from the Ensemble communicator.

property global_spaces_offset[source]

Index of the first local subspace in the global mixed space.

property layout_vec[source]
property local_spaces

The FunctionSpace on the local ensemble.comm.

mesh()[source]

The Mesh on the local ensemble.comm.

property nglobal_dofs[source]

The total number of dofs across all subspaces on all ensemble ranks.

property nglobal_spaces[source]

The total number of subspaces across all ensemble ranks.

property nlocal_comm_dofs[source]

The total number of dofs across all subspaces on the local ensemble.comm.

property nlocal_rank_dofs[source]

The total number of dofs across all subspaces on the local MPI rank.

property nlocal_spaces[source]

The number of subspaces on this ensemble rank.

firedrake.ensemble.ensemble_mat module

firedrake.ensemble.ensemble_mat.EnsembleBlockDiagonalMat(block_mats, row_space, col_space)[source]

A Mat for a block diagonal matrix defined over an Ensemble. Each block acts on a single subspace of an EnsembleFunctionSpace. This is a convenience function to create a PETSc.Mat with a EnsembleBlockDiagonalMatCtx Python context.

Parameters:
  • block_mats (Iterable[PETSc.Mat]) – The PETSc Mats for each block. On each ensemble rank there must be as many Mats as there are local subspaces of row_space and col_space, and the Mat sizes must match the sizes of the corresponding subspaces.

  • row_space – The function space that the matrix acts on. Must have the same number of subspaces on each ensemble rank as col_space.

  • col_space – The function space for the result of the matrix action. Must have the same number of subspaces on each ensemble rank as row_space.

Returns:

The PETSc.Mat with an EnsembleBlockDiagonalMatCtx Python context.

Return type:

PETSc.Mat

class firedrake.ensemble.ensemble_mat.EnsembleBlockDiagonalMatCtx(block_mats, row_space, col_space)[source]

Bases: EnsembleMatCtxBase

A python Mat context for a block diagonal matrix defined over an Ensemble. Each block acts on a single subspace of an EnsembleFunctionSpace.

Parameters:
  • block_mats (Iterable[PETSc.Mat]) – The PETSc Mats for each block. On each ensemble rank there must be as many Mats as there are local subspaces of row_space and col_space, and the Mat sizes must match the sizes of the corresponding subspaces.

  • row_space – The function space that the matrix acts on. Must have the same number of subspaces on each ensemble rank as col_space.

  • col_space – The function space for the result of the matrix action. Must have the same number of subspaces on each ensemble rank as row_space.

Notes

This is a python context, not an actual PETSc.Mat. To create the corresponding PETSc.Mat users should call EnsembleBlockDiagonalMat().

mult_impl(A, x, y)[source]
setUp(mat)[source]
view(mat, viewer=None)[source]
class firedrake.ensemble.ensemble_mat.EnsembleMatCtxBase(row_space, col_space)[source]

Bases: object

Base class for python type Mats defined over an Ensemble.

Parameters:
  • row_space – The function space that the matrix acts on. Must have the same number of subspaces on each ensemble rank as col_space.

  • col_space – The function space for the result of the matrix action. Must have the same number of subspaces on each ensemble rank as row_space.

Notes

The main use of this base class is to enable users to implement the matrix action as acting on and resulting in an EnsembleFunction. This is done by implementing the mult_impl method.

mult(A, x, y)[source]

Apply the action of the matrix to x, putting the result in y.

This method will be called by PETSc with x and y as Vecs, and acts as a wrapper around the mult_impl method which has x and y as EnsembleFunction for convenience. y is not guaranteed to be zero on entry.

Parameters:
  • A (PETSc.Mat) – The PETSc matrix that self is the python context of.

  • x (PETSc.Vec) – The vector acted on by the matrix.

  • y (PETSc.Vec) – The result of the matrix action.

mult_impl(A, x, y)[source]

Apply the action of the matrix to x, putting the result in y.

y is not guaranteed to be zero on entry. This is a convenience method allowing the matrix action to be implemented in terms of EnsembleFunction input and outputs by inheriting classes.

Parameters:
  • A (PETSc.Mat) – The PETSc matrix that self is the python context of.

  • x – The vector acted on by the matrix.

  • y – The result of the matrix action.

firedrake.ensemble.ensemble_pc module

class firedrake.ensemble.ensemble_pc.EnsembleBJacobiPC[source]

Bases: EnsemblePCBase

A python PC context for a block Jacobi method defined over an Ensemble. Each block acts on a single subspace of an EnsembleFunctionSpace and is (approximately) solved with its own KSP, which defaults to -ksp_type preonly.

Available options:

  • -pc_use_amat - use Amat to apply block of operator in inner Krylov method

  • -sub_%d - set options for the %d’th block, numbered from ensemble rank 0.

  • -sub_ - set default options for all blocks.

Notes

Currently this is only implemented for EnsembleBlockDiagonalMatCtx matrices.

apply_impl(pc, x, y)[source]
initialize(pc)[source]
prefix = 'ebjacobi_'

The options prefix of this PC.

update(pc)[source]
view(pc, viewer=None)[source]
class firedrake.ensemble.ensemble_pc.EnsemblePCBase[source]

Bases: PCBase

Base class for python type PCs defined over an Ensemble.

The pc operators must be python Mats with EnsembleMatCtxBase.

Notes

The main use of this base class is to enable users to implement the preconditioner action as acting on and resulting in an EnsembleFunction. This is done by implementing the apply_impl method.

apply(pc, x, y)[source]
apply_impl(pc, x, y)[source]
initialize(pc)[source]
needs_python_pmat = True

Set this to False if the P matrix needs to be Python (matfree).

firedrake.ensemble.ensemble_pc.obj_name(obj)[source]

Module contents