qimpy.grid.Field

class Field(grid, *, shape_batch=(), data=None)

Bases: Gradable[FieldType]

Abstract base class for scalar/vector fields in real/reciprocal space. Provides common operators for fields in either space, but any fields used must specifically be in real (FieldR and FieldC), full-reciprocal (FieldG) or half-reciprocal (FieldH) space.

Parameters:

grid (Grid) –
shape_batch (Sequence[int]) –
data (Tensor) –

__init__(grid, *, shape_batch=(), data=None)

Initialize to zeros or specified data.

Parameters:

grid (Grid) – Associated grid, which determines last three dimensions of data
shape_batch (Sequence[int]) – Optional preceding batch dimensions for vector fields, arrays of scalar fields etc. Not used if data is provided.
data (Tensor | None) – Initial data if provided; initialize to zero otherwise

Return type:

None

Methods

`__init__`	Initialize to zeros or specified data.
`add_`	Add in-place with optional scale factor (Mirroring torch.Tensor.add_).
`clone`	Create field with cloned data (deep copy).
`convolve`	Convolve scalar field by reciprocal-space kernel_tilde.
`divergence`	Divergence of field.
`dot`	Compute broadcasted inner product \(\int a^\dagger b\).
`dtype`	Data type for the Field type
`get_origin_index`	Return index into local data of the spatial index = 0 component(s), which corresponds to r = 0 for real-space fields and to the G = 0 component for reciprocal-space fields.
`gradient`	Gradient of field.
`integral`	Compute integral over unit cell, retaining batch dimensions in output.
`laplacian`	Laplacian of field.
`norm`	Norm of a field, defined by \(\sqrt{\int \|a\|^2}\).
`offset_grid_mine`	Offset of local grid dimensions into global grid for Field type
`read`	Read field from cp_path.
`requires_grad_`	Set whether gradient with respect to this object is needed.
`shape_grid`	Global grid shape for the Field type
`shape_grid_mine`	Local grid shape (last 3 data dimensions) for the Field type
`to`	Switch field to a grid that is different in shape or parallelization.
`vdot`	Vector-space dot product of data summed over all dimensions.
`write`	Write field to cp_path.
`zeros_like`	Create zero Field with same grid and batch dimensions.

Attributes

`is_complex`	Whether this represents a complex scalar field.
`is_tilde`	Whether this field is in reciprocal space.
`o`	Slice of data corresponding to `get_origin_index()`.
`requires_grad`	Return whether gradient with respect to this object is needed.
`grid`	Associated grid that determines dimensions of field
`data`	Underlying data, with last three dimensions on grid
`grad`	optional gradient (of energy) with respect to this object.

add_(other, *, alpha=1.0)

Add in-place with optional scale factor (Mirroring torch.Tensor.add_).

Parameters:

self (FieldType) –
other (FieldType | float) –
alpha (float) –

Return type:

FieldType

clone()

Create field with cloned data (deep copy).

Parameters:: self (FieldType) –
Return type:: FieldType

convolve(kernel_tilde, reduction='')

Convolve scalar field by reciprocal-space kernel_tilde. Amounts to an elementwise multiply for reciprocal space fields, but involve a forward and inverse fourier transform for real space fields. If specified, reduction must be an einsum index expression to contract certain indices of self and kernel_tilde (in that order).

Parameters:

self (FieldType) –
kernel_tilde (Tensor) –
reduction (str) –

Return type:

FieldType

divergence(dim=0)

Divergence of field. A dimension of length 3 at dim, by default at the beginning, is contracted against the gradient operator.

Parameters:

self (FieldType) –
dim (int) –

Return type:

FieldType

dot(other)

Compute broadcasted inner product \(\int a^\dagger b\). This includes appropriate volume / mesh prefactors to convert it to an integral. Batch dimensions must be broadcastable together. Note that a ^ b is exactly equivalent to a.dot(b).

Parameters:

self (FieldType) –
other (FieldType) –

Return type:

Tensor

abstract dtype()

Data type for the Field type

Return type:: dtype

get_origin_index(): Return index into local data of the spatial index = 0 component(s), which corresponds to r = 0 for real-space fields and to the G = 0 component for reciprocal-space fields. Returns an empty index if the origin component is not local to this process. The o property provides convenient access to data at this index.

gradient(dim=0)

Gradient of field. A new batch dimension of length 3 is inserted at the location specified by dim, by default at the beginning.

Parameters:

self (FieldType) –
dim (int) –

Return type:

FieldType

integral()

Compute integral over unit cell, retaining batch dimensions in output.

Return type:: Tensor

laplacian()

Laplacian of field.

Parameters:: self (FieldType) –
Return type:: FieldType

norm()

Norm of a field, defined by \(\sqrt{\int |a|^2}\). Returns a real tensor with shape equal to batch dimensions.

Parameters:: self (FieldType) –
Return type:: Tensor

abstract offset_grid_mine()

Offset of local grid dimensions into global grid for Field type

Return type:: tuple[int, …]

read(cp_path)

Read field from cp_path.

Parameters:: cp_path (CheckpointPath) –
Return type:: None

abstract shape_grid()

Global grid shape for the Field type

Return type:: tuple[int, …]

abstract shape_grid_mine()

Local grid shape (last 3 data dimensions) for the Field type

Return type:: tuple[int, …]

abstract to(grid)

Switch field to a grid that is different in shape or parallelization.

Parameters:

self (FieldType) –
grid (Grid) –

Return type:

FieldType

vdot(other)

Vector-space dot product of data summed over all dimensions. (Scalar contraction needed for the Pulay or Minimizer algorithm templates.)

Parameters:

self (FieldType) –
other (FieldType) –

Return type:

float

write(cp_path)

Write field to cp_path.

Parameters:: cp_path (CheckpointPath) –
Return type:: None

zeros_like()

Create zero Field with same grid and batch dimensions.

Parameters:: self (FieldType) –
Return type:: FieldType

data: torch.Tensor: Underlying data, with last three dimensions on grid

grid: Grid: Associated grid that determines dimensions of field

abstract property is_complex: bool: Whether this represents a complex scalar field. Note that a real scalar field has complex Fourier transform coefficients, but would still be considered real here (i.e. this is False for FieldH).

abstract property is_tilde: bool: Whether this field is in reciprocal space. (Corresponding variable names are typically suffixed by ‘_tilde’.)

property o: Tensor: Slice of data corresponding to get_origin_index().