coffee.grid package

Submodules

coffee.grid.grid module

Grid objects represent the computational, spatial, domain.

Each grid object understands it’s own discretisation as well as how

class coffee.grid.grid.ABCBoundary(*args, **kwargs)

Bases: object

The abstract base class for boundary classes.

A boundary class manages data associated to ghost points and the slices specifying which data points should be communicated between MPI nodes.

Suppose that our computational domain is a line, represented as the array:

domain = be.linspace(0,1,num=11)

This grid has two external boundaries at indices 0 and -1. A subclass of ABCBoundary will generate a list of slices:

[slice(0,None,None)

that when applied to domain extract the values of the boundary points.

Suppose that our computational domain is a line now represented as two sub-domains:

domain_1 = be.linspace(0,1,num=11)[:6]
domain_2 = be.linspace(0,1,num=11)[5:]

Each array now has an external boundary, which represents a boundary of the global computational domain, and an internal boundary, which represents an artifical boundary generated by the representation of the global domain as two different arrays.

A subclass of ABCBoundary should draw a distinction between internal boundaries and external boundaries. This is so that system objects can handle each type of boundary differently. The design goal is for the lists to be iterated over in the system object so that each boundary of each type can be appropriately treated.

DIRECTION_ERROR = ValueError('Direction must be +/- 1')

LEFT = -1

RIGHT = 1

abstract external_slice(shape, dimension, direction)

Returns a tuple which, when applied to a data array, gives the data on the extenal boundaries of the grid.

Parameters:

• shape (tuple of ints) – The shape of the array to be communicated. For example the shape of a numpy array representing the computational domain.

• dimension (int) – Which dimension do we need the list of slices for?

• direction (int) – Which direction do we need the slice for?

Returns:

A list containing the slices that extract the data on the boundary.

Return type:

list of slices

external_slices(shape)

Returns a list of tuples. Each tuple contains an integer, representing the dimension, a direction and the result of calling external_slice(shape, dimension, direction).

This is a convenience method to make iteration over external boundaries easy for the user.

Parameters:

shape (tuple of ints) – The shape of the computational domain. For example if the computational domain is a numpy array then the shape is the numpy shape of the array.

Returns:

Each tuple of slices represents the sub array of the computational domain that made up of external boundary points.

Return type:

list of tuples of slices

abstract ghost_points(dimension, direction)

Returns the number of ghost points for the specified dimension and direction.

Parameters:

• dimension (int) – Which dimension of the domain are we asking for the number of ghost points?

• direction (int) – Of the one dimensional array representing the given dimension, which end of the array are we interested in knowing about the ghost points?

Returns:

The number of ghost points for the specified boundary.

Return type:

int

abstract internal_slice(shape, dimension, direction)

Returns a tuple of slices which, when applied to a data array, gives the data to be communicated to neighbouring grids.

Parameters:

• shape (tuple of ints) – The shape of the array to be communicated. For example the shape of a numpy array representing the computational domain.

• dimension (int) – Which dimension do we need the list of slices for?

• direction (int) – Which direction do we need the slice for?

Returns:

A list containing the slices that extract the data on the boundary.

Return type:

tuple of slices

class coffee.grid.grid.ABCGrid(shape, bounds, name='Grid', comparison=None, mpi=None, boundary_data=None, *args, **kwds)

Bases: object

The abstract base class for Grid objects.

A grid class understands both the total computational domain as well as the domain associated to the particular MPI node that computation is performed on. Each grid object wraps a boundary object and abstracts the boundary object api.

abstract property axes

barrier()

Provides an easy way to call the MPI_Barrier() method via the mpi.mpiinterface object.

collect_data(data)

Wraps mpi.mpiinterfaces.collect_data().

See mpi.mpiinterfaces.collect_data() for documentation.

communicate(data, ghost_point_processor=None)

Wraps the mpi.mpiinterface.communicate() method.

The ghost_point_processor is an arbitary function that takes the data and the returned information of the mpi.mpiinterfaces.communicate() method, called b_values here. It must modify these data structure in place. It is called directly before the now modified data and b_values is returned.

Parameters:

• data – The data to be communicated

• ghost_point_processor (function(data, grid.ABCBoundary)) –

Returns:

The first element of the tuple is the data that was passed to this method. The second element is the returned information to the mpi.mpiinterfaces.communicate() method.

Return type:

tuple

external_slices(data_shape)

Wraps ABCBoundary.external_slices.

See ABCBoundary.external_slices() for documentation.

property meshes

Generates numpy arrays of grid points.

The method uses be.lib.stride_tricks.as_strided to cut down on computational time. It relies on information in the object itself to handle shape, number of points and values.

The meshes are useful for vectorised functions when computing things like initial data for the system.

Returns:

A list of the coordinate values by dimension.

Return type:

list of numpy.ndarray

abstract property step_sizes

class coffee.grid.grid.GeneralBoundary(ghost_points, internal_slices, external_slices)

Bases: ABCBoundary

GeneralBoundary implements ABCBoundary for grids in an mpi context with arbitrary ghost points and arbitrary interal and external slices fixed at run time.

The ghost points variable must be an array or tuple with one entry for each dimension. Each entry is a 2-tuple giving the number of ghost points in the negative and positive directions for that axis.

The data slices variable is an array with one entry for each dimension. Each entry is a tuple of slices which when applied to the data stored in a tslice gives the data to be communicated / received.

external_slices(shape, dimension, direction)

See ABCBoundary.external_slices() for documentation.

ghost_points(dimension, direction)

See ABCBoundary.ghost_points() for documentation.

class coffee.grid.grid.GeneralGrid(shape, bounds, periods, comparison=None, name=None, *args, **kwds)

Bases: ABCGrid

An implementation of ABCGrid that allows for periodic dimensions.

It currently does not allow for use in conjunction with MPI. Note that UniformCart and a period MPI network topology are compatible, however.

property axes

Returns the coordinate values over each dimension.

Return type:

numpy.ndarray

property full_grid

Returns a GeneralGrid object that represents the total computational domain, rather than just the domain used by this MPI node.

Of course, since GeneralGrid’s don’t use MPI, this method returns self. It is included for compatibility.

Return type:

GeneralGrid

property step_sizes

Returns a numpy array containing the fixed step size in each dimension.

Return type:

numpy.ndarray

class coffee.grid.grid.MPIBoundary(ghost_points, internal_points, mpi_comm=None, *args, **kwargs)

Bases: ABCBoundary

MPIBoundary implements the ABCBoundary class, it assumes use of an underlying MPI.Cartcomm object wrapped by mpi4py.

The numbers of ghost points and “internal points” can be specified directly using arrays of two tuples. If the grid is two dimensional the, for example, the array of ghost points and internal points will look like:

[(a, b), (c, d)]

The tuple (a, b) gives the ghost / internal points for the first dimension. The int a gives the number of ghost / internal points for the left direction and b gives the number for the right direction. Similarly for (c,d).

external_slice(shape, dimension, direction)

See ABCBoundary.external_slice() for documentation.

ghost_points(dimension, direction)

See ABCBoundary.ghost_points() for documentation.

internal_slice(shape, dimension, direction)

See ABCBoundart.internal_slice() for documentation.

The first tuple in the return of the function is the list of slices that identifies the data to be sent. The second tuple is the list of slices that identifies the data to be received.

Note that the return variable for this method is inconsistent with the ABCBoundary method. The ABCBoundary method should be updated.

Return type:

A 2-tuple of lists of tuples of ints

source_and_dest(dimension, direction)

A wrapper for the MPI_Cart_Shift function via mpi4py.

To be used in conjuction with a wrapper for MPI_Sendrecv.

Parameters:

• dimension (int) – The dimension of the shift

• direction (int) – The direction of the shift

Returns:

A tuple of ints, (source, destination), where source is the rank of the mpi node that is the source of the data to be sent and destination is the rank of the mpi node that is to receive the data.

Return type:

tuple of ints

class coffee.grid.grid.SimpleMPIBoundary(ghost_points, *args, **kwargs)

Bases: MPIBoundary

SimpleMPIBoundary is for boundaries in mpi contexts with a fixed number of ghost points in every direction and dimension and the “internal points” equal to the ghost points.

class coffee.grid.grid.SingleCartesianGridBoundary(*args, **kwargs)

Bases: ABCBoundary

Implements ABCBoundary for a simulation on a single grid with no mpi dependence.

That is a grid with no internal boundaries and every grid “edge” an external boundary. There are no ghost points.

class coffee.grid.grid.UniformCart(shape, bounds, mpi_comm=None, comparison=None, name=None, *args, **kwds)

Bases: ABCGrid

An implementation of ABCGrid that assumes that the grid has uniform steps and is Cartesian.

property axes

Returns the coordinate values over each dimension.

Return type:

numpy.ndarray

property full_grid

Returns a UniformCart object that represents the total computational domain, rather than just the domain used by this MPI node.

Return type:

UniformCart

property step_sizes

Returns a numpy array containing the fixed step size in each dimension.

Return type:

numpy.ndarray

Module contents