4.2 Layout utilities
The layout routine determines which nodes get which lattice sites and
in what linear order the sites are stored. It has entry points that
allow a user to access single site data extracted from a QDP lattice
field. The layout must be created before any operations on QDP field
objects are allowed. If a user removes data from a QDP lattice object
(see QDP_expose or QDP_extract) and wishes to manipulate
the data on a site-by-site basis, the global entry points provided
here are needed to locate the site data.
The current QDP/C implementation allows only hypercubic layouts with
the same sublattice dimensions on every node.
It would be relatively easy to add other layouts if the need arised.
Defining the layout
Prior to creating the layout the layout parameters must be defined.
This is done through function calls.
| Syntax | void QDP_set_latsize(int nd, int size[]);
| | Meaning | Sets number of spacetime dimensions and lattice size.
No default. Must always be set.
| | Example | QDP_set_latsize(4, size);
|
|
| Syntax | void QDP_create_layout(void);
| | Meaning | Lays out the sites.
| | Example | QDP_create_layout();
|
|
All layout parameters must be initialized through the set function
calls prior to creating the layout.
After creating the layout the following global variables are accessible.
The predefined lattice subsets for specifying even, odd, and
global subsets of the lattice:
QDP_Subset QDP_even, QDP_odd, QDP_all;
The even and odd subsets are elements of a two-element subset array
QDP_even_odd, such that
QDP_even = QDP_even_odd[0];
QDP_odd = QDP_even_odd[1];
It also creates the nearest-neighbor shifts
QDP_shift QDP_neighbor[];
for each coordinate direction.
And finally the variable
int QDP_sites_on_node;
gives the number of sites assigned to a node by the layout utility.
Note that this may vary between nodes.
The following global entry points are provided by the
QDP_create_layout procedure:
Number of dimensions
| Syntax | int QDP_ndim(void);
| | Meaning | Returns the number of dimensions.
| | Example | ndim = QDP_ndim();
|
|
Length of lattice in a given direction
| Syntax | int QDP_coord_size(int i);
| | Meaning | Returns length of lattice in direction i.
| | Example | nx = QDP_coord_size(0);
|
|
Length of lattice in all directions
| Syntax | void QDP_latsize(int latsize[]);
| | Meaning | Returns lattice dimensions into array latsize.
| | Example | QDP_latsize(latsize);
|
|
Length of lattice in all directions
| Syntax | size_t QDP_volume(void);
| | Meaning | Returns lattice volume.
| | Example | vol = QDP_volume();
|
|
Node number of site
| Syntax | int QDP_node_number(int x[]);
| | Meaning | Returns logical node number containing site x.
| | Example | node = QDP_node_number(x);
|
|
Linear index of site
| Syntax | int QDP_index(int x[]);
| | Meaning | Returns the linearized index for the lattice site x.
| | Example | k = QDP_index(x);
|
|
The linear index returned by QDP_index ranges from 0 to
QDP_sites_on_node - 1.
Number of sites on a node
| Syntax | int QDP_numsites(int node);
| | Meaning | Return the number of sites on a node. Same as QDP_sites_on_node
if node = QDP_this_node
| | Example | k = QDP_numsites(i);
|
|
Map node and linear index to coordinate
| Syntax | void QDP_get_coords(int x[], int node, int index);
| | Meaning | Returns site coordinates x for the given node
node and linear index index.
| | Example | QDP_get_coords(x, 0, 31);
|
|
Defining the spacetime coordinate
| Syntax | void QDP_I_eq_coord(QDP_Int *r, int i);
| | Meaning | The ith spacetime coordinate.
| | Example | QDP_Int *coord_z;
QDP_I_eq_coord(coord_z, 2);
|
|
The call QDP_I_eq_coord(&coord[i],i) fills an integer lattice
field coord[i] with a value on each site equal to the integer
value of the ith space-time coordinate on that site.