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 (Optional[Tensor]) – 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

add_(other, *, alpha=1.0)

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

Parameters

• self (FieldType) –

• other (Union[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().