fields.mixins.dense_mathops.DenseFieldDMOMixin.element_wise_partial_derivatives#
- DenseFieldDMOMixin.element_wise_partial_derivatives(out: _Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | complex | bytes | str | _NestedSequence[complex | bytes | str] | None = None, output_axes: Sequence[str] | None = None, *, as_array: bool = False, buffer_class: Type[BufferBase] | None = None, buffer_registry: BufferRegistry | None = None, buffer_args: Sequence[Any] | None = None, buffer_kwargs: Dict | None = None, **kwargs) _SupDFDMOs [source]#
Compute the element-wise partial derivatives of the field.
This method computes the coordinate-wise partial derivatives of the field, treating each scalar component independently. It returns the covariant gradient of each element of the field with respect to the grid’s coordinate directions.
\[\phi \mapsto \left( \frac{\partial \phi}{\partial x^1}, \dots, \frac{\partial \phi}{\partial x^n} \right)\]For a vector or tensor field, the derivative is applied independently to each component in the field’s trailing axes.
Hint
This wraps the grid-level method
dense_element_wise_partial_derivatives()
, which in turn calls the low-level routinedense_element_wise_partial_derivatives()
.- Parameters:
out (
array-like
, optional) – An optional buffer in which to store the result. This can be used to reduce memory usage when performing computations. The shape of out must be compliant with broadcasting rules (see Notes). out may be a buffer or any other array-like object.output_axes (
list
ofstr
, optional) –The axes of the coordinate system over which the result should span. By default, the dependence is calculated internally.
This argument may be specified to expand the number of axes onto which the output field is computed. output_axes must be a superset of the
axes
of the calling field.**kwargs – Additional keyword arguments passed to the low-level operation
dense_element_wise_partial_derivatives()
.in_chunks (
bool
, optional) – Whether to perform the computation in chunks. This can help reduce memory usage during the operation but will increase runtime due to increased computational load. If input buffers are all fully-loaded into memory, chunked performance will only marginally improve; however, if buffers are lazy loaded, then chunked operations will significantly improve efficiency. Defaults toFalse
.edge_order (
{1, 2}
, optional) – Order of the finite difference scheme to use when computing derivatives. Seenumpy.gradient()
for more details on this argument. Defaults to2
.pbar (
bool
, optional) – Whether to display a progress bar whenin_chunks=True
.pbar_kwargs (
dict
, optional) – Additional keyword arguments passed to the progress bar utility. These can be any valid arguments totqdm.tqdm()
.as_array (
bool
, optional) – IfTrue
, then no post-processing occurs and an array is returned.buffer_class (
type
, optional) –Class to use when wrapping the result buffer, e.g.,
fields.buffers.core.ArrayBuffer
orfields.buffers.core.UnytArrayBuffer
.Defaults to buffer resolution to determine a fitting buffer for the resulting array result.
buffer_registry (
BufferRegistry
, optional) – Optional registry to use when resolving the buffer class. This is eventually passed on tofields.buffers.base.buffer_from_array()
.buffer_args (optional) – arguments to pass to
fields.buffers.base.buffer_from_array()
.buffer_kwargs (optional) – arguments to pass to
fields.buffers.base.buffer_from_array()
.
- Returns:
The partial derivatives of the field, computed along each spatial coordinate direction.
If
as_array=False
(default), returns a newDenseField
whose element shape is extended by an additional dimension of size ndim, corresponding to the partial derivatives \(\partial_\mu\).If
as_array=True
, returns a raw NumPy array with shape(grid_shape over output_axes, ..., element_shape, ndim)
where element_shape refers to the shape of each scalar/vector/tensor component in the field.
- Return type:
Notes
Input and Output Shapes
The input field must have shape
(grid_shape, ..., element_shape)
where:
grid_shape is the shape of the domain over the field’s spatial axes.
element_shape represents any trailing axes used to encode vector or tensor components.
The output will append a new axis of length ndim, corresponding to the partial derivative with respect to each spatial coordinate. The resulting shape is:
(grid_shape over `output_axes`, ..., element_shape, ndim)
Examples:
A scalar field on a 2D grid → shape
(Nx, Ny, 2)
A 3-vector field on a 3D grid → shape
(Nx, Ny, Nz, 3, 3)
Chunking Behavior
If
in_chunks=True
, the operation is evaluated over grid chunks using a streaming strategy. Each chunk is automatically extended with a 1-cell halo in every direction to preserve stencil accuracy for finite differences.Chunked evaluation is particularly useful when:
Working with large or out-of-core fields (e.g., HDF5-backed)
Minimizing peak memory use
Avoiding full-domain materialization for intermediate results
Buffer Class Customization
If
as_array=False
, the output is wrapped in a newDenseField
using the specified buffer_class, buffer_registry, and buffer construction arguments.If
as_array=True
, no wrapping occurs, and a raw NumPy array is returned. In this case, buffer configuration options are ignored.See also
dense_element_wise_partial_derivatives
Grid-level implementation this method wraps.
dense_element_wise_partial_derivatives
Lower-level numerical routine.