DOF (Degree-of-Freedom) Arrays

class meshmode.dof_array.DOFArray(actx, data)

This array type holds degree-of-freedom arrays for use with Discretization, with one entry in the DOFArray for each ElementGroupBase. The arrays contained within a DOFArray are expected to be logically two-dimensional, with shape (nelements, ndofs_per_element), where nelements is the same as nelements of the associated group. ndofs_per_element is typically, but not necessarily, the same as nunit_dofs of the associated group. The entries in this array are further arrays managed by array_context.

One main purpose of this class is to describe the data structure, i.e. when a DOFArray occurs inside of further numpy object array, the level representing the array of element groups can be recognized (by people and programs).

array_context

An meshmode.array_context.ArrayContext.

entry_dtype

The (assumed uniform) numpy.dtype of the group arrays contained in this instance.

__len__()

__getitem__(i)

The following methods and attributes are implemented to mimic the functionality of ndarrays. They require the DOFArray to be thaw()ed.

shape

size

copy()

fill(value)

conj()

real

imag

This object supports arithmetic, comparisons, and logic operators.

Note

DOFArray instances support elementwise <, >, <=, >=. (numpy object arrays containing arrays do not.)

Basic in-place operations are also supported. Note that not all array types provided by meshmode.array_context.ArrayContext implementations support in-place operations. Those based on lazy evaluation are a salient example.

__iadd__(arg)

Parameters

arg – can be a Number or another DOFArray.

__isub__(arg)

__imul__(arg)

__itruediv__(arg)

__iand__(arg)

__ixor__(arg)

__ior__(arg)

Note

DOFArray instances can be pickled and unpickled while the context manager array_context_for_pickling is active. If, for an array to be pickled, the ArrayContext given to array_context_for_pickling() does not agree with array_context, the array is frozen and rethawed. If array_context is None, the DOFArray is thaw()ed into the array context given to array_context_for_pickling().

meshmode.dof_array.obj_or_dof_array_vectorize(f, ary)

Works like obj_array_vectorize(), but recurses on object arrays and also tolerates one final ‘layer’ of DOFArrays.

meshmode.dof_array.obj_or_dof_array_vectorized(f, ary)

Works like obj_array_vectorize(), but recurses on object arrays and also tolerates one final ‘layer’ of DOFArrays.

meshmode.dof_array.obj_or_dof_array_vectorize_n_args(f, *args)

Apply the function f elementwise to all entries of any object arrays or DOFArrays in args. All such arrays are expected to have the same shape (but this is not checked). Equivalent to an appropriately-looped execution of:

result[idx] = f(obj_array_arg1[idx], arg2, obj_array_arg3[idx])

Return an array of the same shape as the arguments consisting of the return values of f. If the elements of arrays found in args are further object arrays, recurse. If a DOFArray is found, apply f to its entries. If non-object-arrays are found, apply f to those.

meshmode.dof_array.obj_or_dof_array_vectorized_n_args(f, *args)

Apply the function f elementwise to all entries of any object arrays or DOFArrays in args. All such arrays are expected to have the same shape (but this is not checked). Equivalent to an appropriately-looped execution of:

result[idx] = f(obj_array_arg1[idx], arg2, obj_array_arg3[idx])

Return an array of the same shape as the arguments consisting of the return values of f. If the elements of arrays found in args are further object arrays, recurse. If a DOFArray is found, apply f to its entries. If non-object-arrays are found, apply f to those.

meshmode.dof_array.thaw(actx, ary)

Call thaw() on the element group arrays making up the DOFArray, using actx.

Vectorizes over object arrays of DOFArrays.

Parameters

• actx (meshmode.array_context.ArrayContext) –

• ary (Union[meshmode.dof_array.DOFArray, numpy.ndarray]) –

Return type

numpy.ndarray

meshmode.dof_array.freeze(ary)

Call freeze() on the element group arrays making up the DOFArray, using the ArrayContext in ary.

Vectorizes over object arrays of DOFArrays.

Parameters

ary (Union[meshmode.dof_array.DOFArray, numpy.ndarray]) –

Return type

numpy.ndarray

meshmode.dof_array.flatten(ary)

Convert a DOFArray into a “flat” array of degrees of freedom, where the resulting type of the array is given by the DOFArray.array_context.

Array elements are laid out contiguously, with the element group index varying slowest, element index next, and intra-element DOF index fastest.

Vectorizes over object arrays of DOFArrays.

Parameters

ary (Union[meshmode.dof_array.DOFArray, numpy.ndarray]) –

Return type

Any

meshmode.dof_array.unflatten(actx, discr, ary, ndofs_per_element_per_group=None)

Convert a ‘flat’ array returned by flatten() back to a DOFArray.

Parameters

• ndofs_per_element – Optional. If given, an iterable of numbers representing the number of degrees of freedom per element, overriding the numbers provided by the element groups in discr. May be used (for example) to handle DOFArrays that have only one DOF per element, representing some per-element quantity.

• actx (meshmode.array_context.ArrayContext) –

• ary (Union[Any, numpy.ndarray]) –

• ndofs_per_element_per_group (Optional[Iterable[int]]) –

Return type

meshmode.dof_array.DOFArray

Vectorizes over object arrays.

meshmode.dof_array.array_context_for_pickling(actx)

For the current thread, set the array context to be used for pickling and unpickling DOFArrays to actx.

New in version 2021.x.

Parameters

actx (meshmode.array_context.ArrayContext) –

Array Contexts

meshmode.array_context.make_loopy_program(domains, statements, kernel_data=['...'], name='mm_actx_kernel')

Return a loopy.LoopKernel suitable for use with ArrayContext.call_loopy().

class meshmode.array_context.ArrayContext

An interface that allows a Discretization to create and interact with arrays of degrees of freedom without fully specifying their types.

empty(shape, dtype)

zeros(shape, dtype)

empty_like(ary)

zeros_like(ary)

from_numpy(array)

Returns

the numpy.ndarray array converted to the array context’s array type. The returned array will be thaw()ed.

Parameters

array (numpy.ndarray) –

to_numpy(array)

Returns

array, an array recognized by the context, converted to a numpy.ndarray. array must be thaw()ed.

call_loopy(program, **kwargs)

Execute the loopy program program on the arguments kwargs.

program is a loopy.LoopKernel or loopy.LoopKernel. It is expected to not yet be transformed for execution speed. It must have loopy.Options.return_dict set.

Returns

a dict of outputs from the program, each an array understood by the context.

np

Provides access to a namespace that serves as a work-alike to numpy. The actual level of functionality provided is up to the individual array context implementation, however the functions and objects available under this namespace must not behave differently from numpy.

As a baseline, special functions available through loopy (e.g. sin, exp) are accessible through this interface.

Callables accessible through this namespace vectorize over object arrays, including meshmode.dof_array.DOFArray.

freeze(array)

Return a version of the context-defined array array that is ‘frozen’, i.e. suitable for long-term storage and reuse. Frozen arrays do not support arithmetic. For example, in the context of Array, this might mean stripping the array of an associated command queue, whereas in a lazily-evaluated context, it might mean that the array is evaluated and stored.

Freezing makes the array independent of this ArrayContext; it is permitted to thaw() it in a different one, as long as that context understands the array format.

thaw(array)

Take a ‘frozen’ array and return a new array representing the data in array that is able to perform arithmetic and other operations, using the execution resources of this context. In the context of Array, this might mean that the array is equipped with a command queue, whereas in a lazily-evaluated context, it might mean that the returned array is a symbol bound to the data in array.

The returned array may not be used with other contexts while thawed.

New in version 2020.2.

class meshmode.array_context.PyOpenCLArrayContext(queue, allocator=None, wait_event_queue_length=None)

A ArrayContext that uses pyopencl.array.Array instances for DOF arrays.

context

A pyopencl.Context.

queue

A pyopencl.CommandQueue.

allocator

A PyOpenCL memory allocator. Can also be None (default) or False to use the default allocator. Please note that running with the default allocator allocates and deallocates OpenCL buffers directly. If lots of arrays are created (e.g. as results of computation), the associated cost may become significant. Using e.g. pyopencl.tools.MemoryPool as the allocator can help avoid this cost.

meshmode.array_context.pytest_generate_tests_for_pyopencl_array_context(metafunc)

Parametrize tests for pytest to use a pyopencl array context.

Performs device enumeration analogously to pyopencl.tools.pytest_generate_tests_for_pyopencl().

Using the line:

from meshmode.array_context import pytest_generate_tests_for_pyopencl             as pytest_generate_tests

in your pytest test scripts allows you to use the arguments ctx_factory, device, or platform in your test functions, and they will automatically be run for each OpenCL device/platform in the system, as appropriate.

It also allows you to specify the PYOPENCL_TEST environment variable for device selection.