Execution and fields¶

These types connect logical fields to host or device execution. Backend setup and support constraints belong in the GPU path decision guide; halo layout choices are explained in Halo exchange.

`pfc::data::Field`¶

template<typename T, typename MemorySpace = pfc::HostSpace> class Field¶

The one owning field container: DataBuffer + Box3i + halo + geometry-by-value.

Logical indices (i, j, k) are local (0-based on the owned box). Halo cells are addressable in [-storage_halo, n + storage_halo) on each axis. halo_width() is the iteration halo and does not imply allocated padding; face-halo layouts can have storage_halo == 0 with a nonzero iteration halo.

apply(), operator() and value-taking for_each_owned() require host storage. data() points to the selected memory space, including a device pointer for device fields. Use with_host_read()/with_host_view() for host-side device access; index-only iteration does not itself dereference device storage.

Template Parameters:

T – Element type (e.g. double, std::complex<double>).
MemorySpace – Placement tag (HostSpace default; CUDASpace/HIPSpace from the runtime headers). Selects the DataBuffer backend via memory_space_to_backend_t.

Public Functions

inline Field(const pfc::Domain &domain, const pfc::Box3i &owned_box, int halo_width = 0)¶

Construct from the global Domain, the local owned index box, and a halo width. Allocates prod(size + 2*halo) zero-initialized cells.

halo_width is both the storage padding and the default iteration halo (PaddedBrick convention). Prefer the four-argument overload when migrating unpadded LocalField face-halo layouts (storage 0, iteration n).

Throws:: std::invalid_argument – on a negative halo or an inconsistent box.

inline Field(const pfc::Domain &domain, const pfc::Box3i &owned_box, int storage_halo, int iteration_halo)¶

Construct with independent storage padding and iteration halo.

storage_halo sizes the buffer (prod(size + 2*storage_halo)).
iteration_halo is what halo_width() / for_each_interior report — matching LocalField’s metadata halo on an unpadded buffer.

Face-halo FD stacks use storage_halo=0 and iteration_halo=order/2. PaddedBrick-style fields use equal values for both.

inline std::size_t size() const noexcept¶: Total allocated cells, including halo padding.

inline std::vector<T> &vec()¶: Host std::vector view of the buffer (FFT / legacy APIs).

Note

HostSpace only — device-backed fields have no host std::vector primary storage.

inline pfc::field::FieldView<T> view() const noexcept¶: Read-only non-owning view (host space only): data + local extents + spacing + origin of the local box’s low corner.

inline pfc::field::FieldOutput<T> output() noexcept¶: Mutable non-owning view over the storage (host space only).

inline const pfc::Box3i &box() const noexcept¶: Owned (interior) index box, in global index coordinates.

inline int storage_halo() const noexcept¶: Storage padding width (cells added on each side of the owned box).

inline int halo_width() const noexcept¶

Iteration / stencil halo (LocalField-compatible).

For padded fields this equals storage_halo(). For unpadded face-halo layouts it is the metadata width used by for_each_interior and FDGradient factories, while storage stays tightly packed.

inline pfc::Int3 local_size() const noexcept¶: Per-axis count of owned cells (halo excluded).

inline pfc::Int3 size3() const noexcept¶: LocalField-compatible alias of local_size().

inline pfc::Int3 global_size() const noexcept¶: Global domain extents {Nx, Ny, Nz} (LocalField-compatible).

inline pfc::Int3 lower_global() const noexcept¶: Global index of local (0,0,0) (LocalField-compatible).

inline int padded_extent(int axis) const noexcept¶: Per-axis padded extent (owned + both storage-halo slabs).

inline pfc::Int3 global(int i, int j, int k) const noexcept¶: Global index (gi, gj, gk) of local logical (i, j, k).

inline pfc::Real3 coords(int i, int j, int k) const noexcept¶: Physical coordinates of local logical (i, j, k).

template<typename Fn> inline void for_each_owned(Fn &&fn) const¶

Visit every owned cell in x-fastest order.

Callable may be any of (auto-detected):

void(int i, int j, int k)
void(double x, double y, double z, T value) (LocalField-compatible)
void(const Real3& x, T value) (LocalField-compatible)

template<typename Fn> inline void for_each_interior(Fn &&fn) const¶

Iterate interior [hw, n-hw) per axis (LocalField-compatible).

Callable may be either of:

void(double x, double y, double z, T value)
void(const Real3& x, T value)

template<typename Fn> inline void apply(Fn &&fn)¶: Fill every owned cell by sampling fn at its physical coords. Accepts T(double,double,double) or T(const Real3&). A host-side write, so the device copy (if any) is marked stale.

inline const Residency &residency() const noexcept¶: Host/device coherence state (see residency.hpp).

inline void note_device_write() noexcept¶: Record that a device kernel wrote the device buffer (host mirror stale).

inline void note_host_write() noexcept¶: Record a host-side write (device mirror stale). Public for axpy helpers.

inline void sync_to_device()¶: Push the host mirror to the device buffer when the device copy is stale. No-op for a host-space field. Call before a device kernel reads this field — the sync the audit-4.1 bug omitted.

template<typename Fn> inline void with_host_view(Fn &&fn)¶: Bracket a host-side access. Ensures the host data is current (pulling device->host for a device field), invokes fn(T* data, std::size_t size) over the padded host buffer, then marks the host side authoritative (device copy stale).

template<typename Fn> inline void with_host_read(Fn &&fn) const¶

Pull a current host snapshot without marking the device stale.

with_host_view is a write bracket: after it returns the host mirror is authoritative and the next device use copies that mirror back, including halo cells. A read-only download of owned cells must not do that — the 3-D HIP growth dumper GPU-faulted after a few MPI-IO snapshots for this reason. 2-D dumps survived because the halo traffic is smaller.

Public Static Attributes

static constexpr bool is_host_space¶: True when this field’s memory space is host-accessible (no device mirror).

Execution and fields¶

pfc::data::Field¶

`pfc::data::Field`¶