qlat.field_utils — Field Utility Functions

Source: qlat/qlat/field_utils.pyx

Note: Update this document when updating the source file.

Outline

  1. Overview

  2. Field Expansion

  3. Communication Plans

  4. Fast Fourier Transform

  5. Norm and Square Root

  6. Coordinate Shifting

  7. Field Shuffling

  8. Examples

Overview

field_utils provides standalone utility functions that operate on lattice fields. These functions handle halo expansion, communication planning, FFT, norms, element-wise operations, coordinate shifts, and data redistribution (shuffling) across MPI nodes.

Field Expansion

f_e = field_expanded(f, expansion_left, expansion_right)

Create a copy of field f on an expanded geometry with the given halo widths on each side. The returned field has the same data on the original sites and undefined values in the halo.

Function

Description

field_expanded(f, expansion_left, expansion_right)

Return a new field on the expanded geometry

refresh_expanded(field, comm_plan=None)

Refresh the halo data via MPI communication

refresh_expanded_1(field)

Refresh halo using a single-direction communication pattern

Communication Plans

The CommMarks and CommPlan classes manage field halo communication.

cp = make_field_expand_comm_plan(comm_marks)

Class / Function

Description

CommMarks

A Field(ElemTypeInt8t) marking which sites need communication

CommPlan

A precomputed communication plan derived from CommMarks

make_field_expand_comm_plan(comm_marks)

Build a CommPlan from a CommMarks field

CommPlan supports copy and assignment (@=).

Fast Fourier Transform

The FastFourierTransform class applies FFT to one or more fields.

fft = mk_fft(is_forward, is_only_spatial=False, is_normalizing=False, mode_fft=1)
fields_out = fft * fields_in   # apply FFT (returns copies)

Class / Function

Description

FastFourierTransform(fft_infos, ...)

Construct an FFT operator for specified directions

mk_fft(is_forward, ...)

Factory: create a standard 3D or 4D FFT operator

Parameters for mk_fft:

  • is_forward — True for forward FFT, False for inverse.

  • is_only_spatial — If True, transform only directions 0, 1, 2.

  • is_normalizing — If True, apply 1/sqrt(N) normalization.

  • mode_fft — FFT implementation mode (0 or 1).

When applied via *, FastFourierTransform accepts a single FieldBase or a list of FieldBase objects. Returns a list (or single field if one was given).

Norm and Square Root

Function

Description

qnorm_field(f)

Per-site squared norm; returns SelectedFieldRealD or SelectedPointsRealD

sqrt_field(f)

Element-wise square root; dispatches by field type

sqrt_field supports FieldRealD, SelectedFieldRealD, and SelectedPointsRealD. The underlying type-specific helpers are sqrt_field_real_d, sqrt_selected_field_real_d, and sqrt_selected_points_real_d.

Coordinate Shifting

sf = field_shift(f, shift)        # shift any FieldBase
sf = field_char_shift(f, shift)   # shift a FieldChar directly

Function

Description

field_shift(f, shift)

Return a new shifted copy of f; self is unchanged

field_char_shift(f, shift)

Low-level shift for FieldChar

shift is a Coordinate specifying the cyclic displacement. Roughly: shifted_field[(xg + shift) % total_site] == original_field[xg].

Field Shuffling

Shuffling redistributes field data across MPI nodes according to a new node geometry.

f_list = shuffle_field(f, new_size_node)
shuffle_field_back(f, f_list, new_size_node)   # reassemble in-place

Function

Description

shuffle_field(f, new_size_node)

Split f into sub-fields for the new node layout

shuffle_field_back(f, f_list, new_size_node)

Reassemble f from shuffled sub-fields (modifies f in-place)

shuffle_field_char(f, new_size_node)

Low-level shuffle for FieldChar

shuffle_field_char_back(fc, f_list, new_size_node)

Low-level reassemble for FieldChar

Examples

import qlat as q

q.begin_with_mpi([[1, 1, 1, 4]])

geo = q.Geometry(q.Coordinate([4, 4, 4, 8]))
f = q.FieldRealD(geo, 1)
f.set_zero()

# Expand the field halo by 1 site on each side
f_e = q.field_expanded(f, 1, 1)
print(f"Expanded n_sites: {f_e.n_sites}")

# FFT (forward, spatial only) — requires ComplexD field
f_c = q.FieldComplexD(geo, 1)
f_c.set_zero()
fft = q.mk_fft(True, is_only_spatial=True)
f_fft = fft * f_c

# Norm
norm = f.qnorm()
print(f"qnorm: {norm}")

# Square root
f_sqrt = q.sqrt_field(f)

# Shift by (1,0,0,0)
# Note: field_shift swaps data out of the original field
norm_before = f.qnorm()
f_shifted = q.field_shift(f, q.Coordinate([1, 0, 0, 0]))

q.end_with_mpi()