qlat.selected_field_types — Typed Selected-Field Classes¶
Source: qlat/qlat/selected_field_types.pyx.in
Note: Update this document when updating the source file.
Outline¶
Overview¶
selected_field_types is a template module (.pyx.in) that generates concrete
SelectedField{Type} subclasses of SelectedFieldBase for every lattice data
type. Each generated class stores field data only on a subset of lattice sites
identified by a FieldSelection, reducing memory and communication costs when
only part of the lattice is needed.
All selected-field classes are registered in selected_field_type_dict:
selected_field_type_dict[ElemTypeRealD] returns SelectedFieldRealD.
Generated Types¶
The template generates SelectedField variants for all 16 element types:
Category |
Classes |
|---|---|
Complex matrices |
|
Complex scalars |
|
Real scalars |
|
Integer types |
|
Construction¶
sf = SelectedFieldRealD() # empty (uninitialized)
sf = SelectedFieldRealD(fsel) # allocate with field selection
sf = SelectedFieldRealD(fsel, multiplicity) # with given multiplicity
fsel is a FieldSelection object specifying which lattice sites are selected.
Properties¶
Property |
Type |
Description |
|---|---|---|
|
|
Number of selected sites |
|
|
Total lattice dimensions |
|
|
Number of elements per site |
|
|
Size of one element in bytes |
|
|
The lattice geometry |
Assignment and Copying¶
The @= operator assigns data. It does not change self.fsel.
sf1 @= sf2 # SelectedField ← SelectedField (fsel may differ)
sf @= f # SelectedField ← Field (scatter into selected sites)
sf @= sp # SelectedField ← SelectedPoints
Method |
Description |
|---|---|
|
Deep copy; returns a new |
|
Set all elements to zero |
|
Swap contents with another |
|
Swap raw bytes with a |
|
Swap raw bytes with a |
Mutation Operations¶
sf.set_zero() # zero all elements
sf.set_rand(rng, upper=1.0, lower=0.0) # uniform random
sf.set_rand_g(rng, center=0.0, sigma=1.0) # Gaussian random
Method |
Description |
|---|---|
|
Global squared norm (scalar float) |
|
Per-site squared norm → |
Shifting and Reflection¶
sf_shifted = sf.shift(shift, is_reflect=False)
Return a new shifted SelectedField. self is not modified. If shift is
None and is_reflect is False, returns a plain copy.
I/O Operations¶
total_bytes = sf.read_direct(filename)
total_bytes = sf.write_direct(filename)
total_bytes = sf.read_sfr_direct(sfr, filename) # from ShuffledFieldsReader
total_bytes = sf.write_sfw_direct(sfw, filename) # via ShuffledFieldsWriter
sf.write_sfw_direct(sfw, filename, skip_if_exist=True) # skip if already written
The shuffled I/O methods (read_sfr_direct, write_sfw_direct) use a
ShuffledBitSet cache from the reader/writer for efficient data transfer.
NumPy Buffer Protocol¶
All selected-field types support zero-copy NumPy access:
arr = np.asarray(sf) # shape: (n_elems, multiplicity, *element_shape)
The buffer protocol follows the same conventions as Field{Type} but with
n_elems (selected sites) instead of n_sites (local sites).
Serialization¶
state = sf.__getstate__() # serialize (single-node only)
sf.__setstate__(state) # deserialize (single-node only)
Serialization only works when running on a single node or when all nodes hold identical data.
Selected-Field Type Dictionary¶
from qlat.field_type_dict import selected_field_type_dict
SelectedFieldRealD = selected_field_type_dict[ElemTypeRealD]
Examples¶
import qlat as q
import numpy as np
q.begin_with_mpi([1, 1, 1, 4])
geo = q.Geometry(q.Coordinate([4, 4, 4, 8]))
# Create a field and populate it
f = q.FieldRealD(geo, 1)
rng = q.RngState("seed-1")
f.set_rand_g(rng)
# Build a field selection (select all sites)
fsel = q.FieldSelection(geo, 0)
# Create a selected field
sf = q.SelectedFieldRealD(fsel, 1)
sf @= f # scatter from full field
print(f"n_elems: {sf.n_elems}")
# Access as NumPy array
arr = np.asarray(sf)
print(f"Shape: {arr.shape}")
# Norm
norm = sf.qnorm()
print(f"qnorm: {norm}")
# Copy and shift
sf_copy = sf.copy()
sf_shifted = sf.shift(q.Coordinate([1, 0, 0, 0]))
q.end_with_mpi()