Home

QDP/C User Manual

1. Name Purpose Libqdp_common a QDP utilities libqdp_int a integer and boolean libqdp f a real and complex single precision libqdp d a real and complex double precision libqdp df a real and complex precision conversion libqdp f2 a 2 color single precision libqdp d2 a 2 color double precision libqdp df2 a 2 color precision conversion libqdp f3 a 3 color single precision libqdp d3 a 3 color double precision libqdp df3 a 3 color precision conversion libqdp_fn a N color single precision libqdp dn a N color double precision libqdp_dfn a N color precision conversion 2 3 Nonuniform color and precision Users wishing to vary color and precision within a single calculation must use specific type names and function names whenever these types and names differ from the prevailing precision and color If using different colors that the specified value then one must also include the necessary headers For example if a single precision SU 3 calculation also uses some SU 2 datatypes or operations the following preamble is appropriate define QDP_Precision F define QDP_Nc 3 Chapter 2 Compilation with QDP include lt qdp h gt include lt qdp_f2 h gt and the following linkage to get the corresponding libraries lqdp_f2 lqdp_f3 lqdp_f lqdp_int lqdp_common Note that the single double and conversion headers for the prevailing color are auto matically included t
2. AM _ Left multiplication by color matrix Syntax QDP T eqop M times T Type r QDP ColorMatrix a Type b subset QDP T veqop M times T Type r QDP_ColorMatrix a Type b subset int n Meaning r eqop a b Type V H D M P eqop eq peq meq eqm Chapter 5 Function Details 42 Left multiplication by adjoint of color matrix C Syntax QDP T eqop Ma times T Type r QDP_ColorMatrix a Type b subset QDP T veqop Ma times T Type r QDP ColorMatrix a Type b subset int n Meaning r eqop adjoint a b Type V H D M P eqop eq peq meq eqm Right multiplication by color matrix Syntax QDP P eqop P times M QDP DiracPropagator r QDP_ DiracPropagator a QDP ColorMatrix b subset Meaning r eqop a b eqop eq peq meq eqm Right multiplication by adjoint of color matrix C Syntax QDP T eqop T times Ma Type r Type a QDP ColorMatrix b subset Meaning r eqop a adjoint b Type M P eqop eq peq meq eqm Adjoint of color matrix times adjoint of color matrix Syntax QDP M eqop Ma times Ma QDP ColorMatrix r QDP_ColorMatrix a QDP ColorMatrix b subset Meaning r eqop adjoint a adjoint b eqop eq peq meq eqm Chapter 5 Function Details 43 Local inner product Syntax QDP C eqop T dot T QDP Complex r Type a Type b s
3. Chapter 5 Function Details Left multiplication by color matrix then shift Syntax QDP_T_eq_sM_times_sT Type r QDP_ColorMatrix a Type b QDP_Shift s QDP_ShiftDir d subset Meaning r shift a b Type V H D M P 5 2 Fills and random numbers Zero fills Syntax QDP_T_eq_zero Type r subset Meaning r 0 Type I R C V H D M P Constant fills Syntax QDP_T_eq_t Type r QLA Type a subset Meaning r a Type I R C V H D M P Fill color matrix with constant times identity Syntax QDP_M_eq_c QDP_ColorMatrix r QLA Complex a subset Meaning r al Seeding the random number generator field from an integer field Syntax QDP S eq seed i I QDP RandomState r QLA Int c QDP Int a subset Meaning seed r from constant c and field a Uniform random number fills Syntax QDP R eq random S QDP Real r QDP_RandomState a subset Meaning r uniform random number in 0 1 from seed a p A RK H Chapter 5 Function Details 30 Gaussian random number fills Syntax QDP T eq gaussian S Type r QDP RandomState a subset Meaning r normal gaussian from seed a Type R C V H D M P Function fills Syntax QDP T eq func Type r void func QLA Type dest int coords subset Meaning calls func amp r x x for all coordinates x in subset Type I R C V H D M P Functio
4. Chapter 5 Function Details Transpose Syntax QDP T eqop transpose T Type r Type a subset Meaning r eqop transpose a Type M P eqop eq peq meq eqm Complex conjugate Syntax QDP T eqop conj T Type r Type a subset Meaning r eqop conjugate a Type C V H D M P eqop eq peq meq eqm Hermitian conjugate Syntax QDP T eqop Ta Type r Type a subset Meaning r eqop adjoint a Type C M P eqop eq peq meq eqm Local squared norm uniform precision Syntax QDP R eq norm2 T QDP Real r Type a subset Meaning r norm2 a Type C V H D M P 5 4 Type conversion and component extraction and insertion Convert float to double Syntax QDP T eq T Type r Type a subset Meaning r a Type R C V H D M P Chapter 5 Function Details Convert double to float 33 Syntax QDP T eq T Type r Type a subset Meaning r a Type R C V H D M P Convert real to complex zero imaginary part Syntax QDP_C_eq_R QDP_Complex r QDP_Real a subset Meaning r at i0 Convert real and imaginary to complex Syntax QDP_C_eq_R_plus_i_R QDP_Complex r QDP_Real a QDP_Real b subset Meaning r atib Real Imaginary part of complex Syntax QDP_R_eq_func_C QDP_Real r QDP_Complex a subset Meaning r func a func re im Integer to real Sy
5. The integer return value is 0 for success and 1 for failure It is assumed the user has created the QDP String for the record metadata and the field for the data in advance The datatype of the record must match the field type Chapter 4 QDP Functions 19 Reading an array of fields C N Syntax int QDP vread T QDP Reader in QDP String record xml QDP Type field int n Meaning Reads the array of fields and its metadata from the next record in the specified file Type S I R C V H D M P Example QDP_ColorMatrix field 4 for i 0 i lt 4 i field i QDP create M QDP_vread_M reader record_xml field 4 The integer return value is 0 for success and 1 for failure It is assumed the user has created the QDP_String for the record metadata and the fields for the data in advance Reading only the record information It may be convenient to examine the record metadata first to decide whether to read or skip the accompanying binary data Syntax int QDP_read_record_info QDP_Reader in QDP_String record_ xml Meaning Reads the only the metadata from the next record in the specified file Example QDP read record info reader record xm1 A subsequent call to QDP read T returns a copy of the same metadata along with the lattice field Skipping to the next record Syntax int QDP next record QDP Reader in Meaning Advances to the beginning of the next record E
6. a Type b subset int n Meaning r c a b Type C V H D M P func plus minus J 5 8 Boolean operations Comparisons of integers and reals Syntax QDP_I_eq_T_func_T QDP_Int r Type a Type b subset Meaning r a func b Type I R func eq ne gt 1t ge le Copy under a mask Syntax QDP T eq T mask I Type r Type a QDP Int b subset Meaning r a if b is not 0 Type I R C V H D M P 5 9 Reductions Chapter 5 Function Details Global squared norm uniform precision Syntax QDP_r_eq_norm2_T QLA_Real r Type a subset QDP r veq norm2 T QLA Real r Type a subset int n Meaning r Sum norm2 a Type I R C V H D M P Global inner product Syntax QDP_r_eq_T_dot_T QLA_Real r Type a Type b subset QDP_r_veq_T_dot_T QLA_Real r Type a Type b subset int n Meaning r Sum Tra b Type I R z Syntax QDP c eq T dot T QLA Complex r Type a Type b subset QDP c veq T dot T QLA Complex r Type a Type b subset int n Meaning r Sum Tr adjoint a b Type C V H D M P Real part of global inner product Syntax QDP r eq re T dot T QLA Real r Type a Type b subset QDP r veq re T dot T QLA Real r Type al Type b subset int n Meaning r Sum Re Tr adjoint a b Type C V H D M P Global sums Syntax QDP_r_eq_sum_I QLA_
7. 3 Reading and writing QLA arrays lisse else 20 4 7 4 String Handling 0 00 eee eee eee 21 4 8 Temporary entry and exit from QDP 4 22 4 9 Optimization Calls 0 ccc ccc nan 25 5 Function Deballs asevsoxeue usw RPG sans 28 5 1 Functions involving shifts liiis cece eee eee eee 28 5 2 Fills and random numbers 0000 eee e esses 29 5 3 Unary Operations teti eect teens 30 5 4 Type conversion and component extraction and insertion 32 5 5 Binary operations with constants 0 0c cee eee eee ee 38 5 6 Binary operations with fields 0 0 0 0 cee cece eee eee 40 5 7 Ternary operations with fields 0 00 cee eee ee eee 43 5 8 Boolean operations 0000 cece eee hh 44 DO IRSQUCUIOLTIS osos Da nena a ute esae oa Rer eR Rh 44 Chapter 1 Introduction 1 1 Introduction This is the detailed user s guide for the C binding of the QDP Data Parallel Applications Programmer Interface developed under the auspices of the U S Department of Energy Scientific Discovery through Advanced Computing SciDAC program The QDP Level 2 API has the following features e Can specify a physical lattice of any size and number of dimensions e Automatically handles the layout of the lattice across the machine e Provides functions for creating and destroying fields on the lattice along with a large set of data parallel operations l
8. I R C V H D M P Example QLA Complex array nt QDP_c_eq_V_dot_V_multi array prop src timeslices nt QDP_write_vc writer record_xml array nt The integer return value is 0 for success and 1 for failure It is assumed the user has prepared the record metadata and the field data in advance 4 7 4 String Handling The file and record metadata is passed to QDP in QDP_string objects These can be created destroyed and converted to from C strings with the following routines Creating an empty QDP string Syntax QDP_String QDP_string_create void Meaning Creates an empty string Example fileinfo QDP string create Chapter 4 QDP Functions 22 Destroying a QDP string Syntax void QDP string destroy QDP String xm1 Meaning Frees the QDP string object and its contents Example QDP string destroy xml Set a QDP string from a C string a N Syntax void QDP string set QDP String qstring char cstring Meaning Sets the QDP string to contain a copy of the null terminated character array cstring Example QDP string fileinfo QDP string create QDP string set fileinfo string Copying a QDP string Syntax void QDP string copy QDP String dest QDP String src Meaning Copies the string Example QDP string copy newxml oldxml Accessing the string length Meaning Returns the length of the string Examp
9. ShiftDir that takes one of two predefined values QDP forward and QDP backward Shifts are treated syntactically as a modification of a QDP argument and are specified with a prefix s before the type abbreviation for the shifted field Thus for example QDP H eq sH r a dir sign s Chapter 4 QDP Functions 16 shifts the half fermion field a along direction dir forward or backward according to sign placing the result in the field r Nearest neighbor shifts are specified by values of the global shift QDP neighbor mu with mu in the range 0 Ndim 1 The sign is QDP forward for shifts from the positive direction and QDP backward for shifts from the negative direction That is for QDP forward and dir QDP neighbor mu r x a x mu For more general shifts the direction dir is specified by the object returned by QDP create shift or QDP create map and sign must be either QDP forward or QDP backward to specify the permutation or its inverse respectively The subset restriction applies to the destination field r Thus a nearest neighbor shift operation specifying the even subset shifts odd site values from the source a and places them on even site values on the destination field r Creating displacement shifts C N Syntax QDP_Shift QDP_create_shift int d Meaning Creates a shift defined by the displacement vector d Example int d 4 0 1 2 0 QDP_Shift knight 4 4 knight 2 3 QDP create
10. also be defined by limiting the range of return values to a single value i e 0 This procedure may be called more than once and sites may be assigned to more than one subset Thus for example an even site may also be assigned to a time slice subset and one of the subsets in a 32 level checkerboard scheme A subset definition remains valid until QDP destroy subset is called Defining a subset Subsets are defined through the data type QDP Subset S Syntax QDP_Subset QDP create subset int func int x void xargs void args int argsize int n Meaning Creates an array of n subsets based on func Example QDP_Subset ts nt ts QDP create subset timeslice NULL 0 nt where timeslice x NULL returns x 3 P The extra arguments args are passed directly to the function and saved in case the subset function is needed again when doing shifts involving the subset Therefore the function should not depend on any other global parameters that may change later in the program It is permissible to call QDP create subset with n 1 In this case the function must return zero if the site is in the subset and nonzero if not Note this is opposite the true false convention in C Chapter 4 QDP Functions 15 Destroying subsets Syntax void QDP_destroy_subset QDP_subset s Meaning Destroys all subsets created with s Example QDP_destroy_subset ts This procedure frees all memory associated with t
11. argv Meaning Starts QDP Example QDP initialize amp argc amp argv The routine QDP_initialize is called once by all nodes and starts QDP operations It initialiazes message passing if not already done but does not setup the site layout see QDP create layout and related functions It also defines the global variable int QDP this node specifying the logical node number of the current node Exit from QDP Syntax void QDP finalize void Meaning Exits QDP Example QDP_finalize This call provides for an orderly shutdown It is called by all nodes It also finalizes QMP only if it was initialized by QDP If profiling was turned on in any functions then node 0 will dump some statistics to stdout Then it returns control to the calling process Chapter 4 QDP Functions 8 Panic exit from QDP Syntax void QDP_abort int status Meaning Panic shutdown of the process Example QDP_abort 1 This routine may be called by one or more nodes It sends kill signals to all nodes and exits with exit status status Check for initialization Syntax int QDP_is_initialized void Meaning Checks if QDP is initialized Example if QDP is initialized QDP initialize amp argc amp argv Control profiling Syntax int QDP_profcontrol int new Meaning Controls profiling Example old QDP_profcontrol new Profiling results are only available for code that is compiled wi
12. coord_z QDP_I_eq_coord coord_z 2 The call QDP_I_eq_coord amp 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 4 3 Naming Conventions for Data Parallel Functions Data parallel functions are described in detail in Chapter 5 Function Details page 28 Here we desribe the naming conventions Data parallel function names are constructed with a pattern that suggests their functionality Thus the function QDP_V_eq_M_times_V c u b s carries out the product c x u x b x for all lattice coordinates x belonging to the subset s where c and b are pointers to lattice staggered fermion vector fields and u is a pointer to a lattice color matrix field The elements of the function name are separated by an underscore for readability All function names in this interface begin with QDP The specific name continues with a precision and color label as in QDP F3 V eq M times V for single precision SU 3 Then comes a string of elements that mimics the algebraic expression The next character V abbreviates the type for the destination operand in this case the argument c The abbreviations are listed in Chapter 3 Datatypes page 5 The next string eq specifies the assignment operator In this case it is a straight replacement but modifications are also supported as described Chapter 4 QDP Functions 12 below Then comes the
13. layout the layout parameters must be defined This is done through function calls C gt 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 P S Syntax void QDP_create_layout void Meaning Lays out the sites Example QDP_create_layout m 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 Chapter 4 QDP Functions Number of dimensions 10 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_coo
14. r QDP_ ColorMatrix a QDP DiracFermion b int dir int sign subset int n Meaning r spin reconstruct spin project a b dir sign dir sign eqop eq spproj peq_spproj meq_spproj eqm spproj J 5 5 Binary operations with constants Multiplication by integer constant Syntax QDP_I_eqop_i_times_I QDP_Int r QLA_Int a QDP_Int b subset Meaning r eqop a b eqop eq peq meq eqm Chapter 5 Function Details Multiplication by real constant Syntax QDP T eqop r times T Type r QLA Real a Type b subset QDP T veqop r times T Type r QLA Real al Type b subset int n Meaning r eqop a b Type R C V H D M P eqop eq peq meq eqm Multiplication by complex constant Syntax QDP T eqop c times T Type r QLA Complex a Type b subset QDP T veqop c times T Type r QLA Complex al Type b subset int n Meaning r eqop a b Type C V H D M P eqop eq peq meq eqm Multiplication by i Syntax QDP T eqop i T Type r Type a subset Meaning r eqopia Type C V H D M P eqop eq peq meq eqm Left multiplication by gamma matrix Syntax QDP T eq gamma times T Type r Type a int i subset Meaning r gamma i a Type D P Chapter 5 Function Details 40 Right multiplication by gamma matrix Syntax QDP P eq P times gamma
15. shift QDP Shift shift Meaning Frees memory associated with the map shift Example QDP destroy shift shift 4 7 I O utilities QDP provides a convenient interface to the QIO library which can read and write any lattice field in the SciDAC format including ILDG lattices It also provides routines for inserting metadata and global binary data into the files 4 7 1 Opening and closing binary files As with standard Unix a file must be opened before reading or writing However we distinguish file handles for both cases Open a file for reading Syntax QDP Reader QDP open read QDP String md char filename Meaning Opens a named file for reading and reads the file metadata Example QDP Reader infile QDP String file xml QDP string create infile QDP open read file xml filename The QDP Reader return value is the file handle used in subsequent references to the file A null return value signals an error The I O system takes responsibility for allocating and freeing space for the handle It is assumed the user has preperly created the QDP String that will hold the file metadata so it can be read from the head of the file and inserted The volume format see QDP open write below is autodetected so is not specified Open a file for writing DN Syntax QDP Writer QDP open write QDP String md char filename int volfmt Meaning Opens a named file for writing and writes t
16. this as soon as the result of a shift is no longer needed It can also be used to make sure that a field is not being used elsewhere without first being set since using a discarded field without first setting it produces an error Block size operations Syntax int QDP get block size void Meaning Returns the block size Chapter 4 QDP Functions 26 Syntax void QDP_set_block_size int bs Meaning Sets the block size These functions allow one to set the block size used for the operations on arrays of QDP fields Instead of running over all sites of each field individually it can run over a few sites for each field in turn and then move to the next few sites on each field and so on until all sites are done The number of sites done at a time is determined by the block size Memory alignment Syntax int QDP get mem align void Meaning Returns the default memory alignment Syntax void QDP set mem align int align Meaning Sets the default memory alignment Some architectures might perform better for fields with certain alignments This allows one to set the default alignment used when fields are created It only affects newly created fields Currently the default is set to 16 bytes if not set by the user which should be sufficient for most current platforms It is expected that the QDP library will automatically use whatever value is necessary to utilize the optimized QLA routines for
17. A Real r QDP_Int a QDP_Subset subset int n Meaning r i Sum subset i a Syntax QDP t eq sum T nulti QLA Type r Type a QDP Subset subset int n Meaning r i Sum subset i a Type R C V H D M P
18. QDP DiracPropagator r QDP_ DiracPropagator a int i subset Meaning r a gamma i 5 6 Binary operations with fields Elementary binary functions on integers Syntax QDP I eq I func I QDP Int r QDP Int a QDP Int b subset Meaning r a func b func lshift rshift mod max min or and xor Elementary binary functions on reals QDP R eq R func R QDP Real r QDP Real a QDP Real b S Syntax subset Meaning r a func b func mod max min pow atan2 Multiplying real by integer power of 2 Syntax QDP_R_eq_R_ldexp_I QDP_Real r QDP_Real a QDP_Int b subset Meaning r a 2 b Addition Syntax QDP T eq T plus T Type r Type a Type b subset QDP T veq T plus T Type r Type a Type b subset int n Meaning r at b Type I R C V H D M P Chapter 5 Function Details Subtraction S Syntax QDP T eq T ninus T Type r Type a Type b subset QDP T veq T minus T Type r Type a Type b subset int n Meaning r a b Type I R C V H D M P A Multiplication uniform types Syntax QDP_T_eqop_T_times_T Type r Type a Type b subset Meaning r eqop a b Type I R C P eqop eq peq meq eqm Division of integer real and complex fields Syntax QDP T eq T divide T Type r Type a Type b subset Meaning r a b Type I R C
19. QDP C User Manual Version 1 8 0 This document provides a detailed description of the C implementation of the SciDAC Level 2 QDP Data Parallel interface C DeTar and J C Osborn with the SciDAC Software Committee Table of Contents 1 JntrOGUCLIORz 2e RRREPEY E ERR R3 eR 1 2 Compilation with QDP s s206 s0s 62 0dse0me00 2 2 1 Header and macros weg eee ewe ei deena deeds meas 2 2 2 JLIBDrAarle8 2 e beet elegans bad be aee i de dod ag weed Placa RC eae 3 2 3 Nonuniform color and precision 00 eee eee e ee eee 3 3 L tsivD6Suaewaccsk ions d eae x a dn cie OR ten es 5 Bl Generic Names 54 2 ken haabe ed elo e E Lo ads 5 3 2 Specific Types for Color and Precision 5 3 3 Color and Precision Uniformity 000 0 cess ee eee 6 3 4 Breaking Color and Precision Uniformity 6 4 ODP PunctiotiB 2ec2299 o n wy axes 7 4 1 Entry and exit from QDP ES RA ee eee i 4 2 Layout utilitie8 2226s eph dds roto IUE wd eda ead od 8 4 8 Naming Conventions for Data Parallel Functions 11 4 4 Creating and destroying lattice fields 13 4 5 SSUDSeLS sero ve oS peeten eoi dad debts 14 AG nn PERPPP 15 AT OO BUS i Les apod veas deiude atiam aed d s idu na Ne A 17 4 7 1 Opening and closing binary files 17 4 7 2 Reading and writing QDP fields 18 4 7
20. QDP data Syntax void QDP reset T Type field Meaning Returns control of data values to QDP Type I R C V H D M P Example QDP reset M r This call signals to QDP that the user is ready to resume QDP operations with the data in the specified field Extracting QDP data Syntax void QDP extract T QLA Type dest Type src Meaning Copy data values from field src to array dest Type I R C V H D M P Example QDP_extract_M r a QDP_even The user must allocate space of size QDP_sites_on_node sizeof QLA_Type for the destination array before calling this function regardless of the size of the subset This function copies the data values contained in the QDP field src to the destination field Only values belonging to the specified subset are copied Any values in the destination array not associated with the subset are left unmodified The order of the data is given by QDP_index Since a copy is made QDP operations involving the source field may proceed without disruption Chapter 4 QDP Functions 24 Inserting QDP data Syntax void QDP_insert_T Type dest QLA Type src Meaning Inserts data values from QLA array src Type I R C V H D M P Example QDP_insert_M a r Only data associated with the specified subset are inserted Other values are unmodified The data order must conform to QDP_index This call analogous to a fill operation is permitted at any ti
21. Real r QDP_Int a subset Meaning r Suma Chapter 5 Function Details 46 Syntax QDP t eq sum T QLA Type r Type a subset Meaning r Sum a Type R C V H D M P Multisubset Norms S Syntax QDP_r_eq_norm2_T_multi QLA_Real r Type a QDP_Subset subset int n QDP_r_veq_norm2_T_multi QLA_Real r Type a QDP_Subset subset int n Meaning r i Sum_subset i norm2 a Type I R C V H D M P E Multisubset inner products S Syntax QDP_r_eq_T_dot_T_multi QLA_Real r Type a Type b QDP_Subset subset int n QDP_r_veq_T_dot_T_multi QLA_Real r Type a Type b QDP Subset subset int n Meaning r i Sum subset i a b Type I R E Syntax QDP c eq T dot T multi QLA Complex r Type a Type b QDP Subset subset int n QDP c veq T dot T multi QLA Complex r Type a Type b QDP Subset subset int n Meaning r i Sum subset i adjoint a b Type Q V H D M P A Multisubset real part of global inner product C Syntax QDP r eq re T dot T multi QLA Real r Type a Type b QDP Subset subset int n QDP r veq re T dot T multi QLA Real r Type a l Type b QDP Subset subset int n Meaning r Sum Re Tr adjoint a b Type C V H D M P Chapter 5 Function Details Multisubset global sums 47 7 Syntax QDP r eq sum I multi QL
22. architectures which QLA has been optimized for Therefore the user normally would not need to set this and it is recommended that they don t unless they specifically find it useful for a platform not already optimized in QLA The user can also use the macro QDP ALIGN DEFAULT to specify the default alignment provided by QMP for that machine Memory attributes e int QDP get mem flags void Meaning Returns the default memory flags z Syntax void QDP set mem flags int flags Meaning Sets the default memory flags Example QDP set mem flags QDP MEM FAST QDP MEM COMMS This allows the user to set the characteristics of the memory used for newly created fields if the architecture supports them The QDP memory flags have the same meaning as the corresponding QMP flags The integer value is the combination bitwise or of the flags given below The actual effect of each combination is specific to the implementation and the architecture Chapter 4 QDP Functions Memory Flag 27 Meaning QDP_MEM_NONCACHE QDP_MEM_COMMS QDP_MEM_FAST QDP_MEM_DEFAULT Use noncached memory Use memory that is optimized for communucations Use fastest memory available such as EDRAM on QCDOC Use default value for architecture from QMP Chapter 5 Function Details 28 5 Function Details This section describes in some detail the names and functionality for all functions in the in terface involving li
23. construction z Syntax QDP_D_eqop_spproj_D QDP_DiracFermion r QDP_DiracFermion a int dir int sign subset QDP D veqop spproj D QDP DiracFermion r QDP_DiracFermion a int dir int sign subset int n Meaning r spin reconstruct spin project a dir sign dir sign eqop eq peq meq eqm Chapter 5 Function Details 38 Matrix multiply and Dirac spin projection C N Syntax QDP_H_eqop_M a _times_D QDP_HalfFermion r QDP_ColorMatrix xa QDP_DiracFermion b int dir int sign subset QDP H veqop M a times D QDP HalfFermion r QDP_ColorMatrix a QDP_DiracFermion b int dir int sign subset int n Meaning r spin project a b dir sign eqop eq spproj peq_spproj meq_spproj eqm spproj E Matrix multiply and Dirac spin reconstruction C gt Syntax QDP_D_eqop_M a _times_H QDP_DiracFermion r QDP ColorMatrix a QDP HalfFermion b int dir int sign subset QDP D veqop M a times H QDP DiracFermion r QDP_ ColorMatrix a QDP HalfFermion b int dir int sign subset int n Meaning r spin reconstruct a b dir sign eqop eq sprecon peq sprecon meq sprecon eqm sprecon a Matrix multiply and Dirac spin projection with reconstruction C N Syntax QDP_D_eqop_M a _times_D QDP_DiracFermion r QDP_ColorMatrix xa QDP_DiracFermion b int dir int sign subset QDP_D_veqop_M a _times_D QDP_DiracFermion
24. eq_Ma_times_V c u b s carries out the product c x adjoint u x b x for all sites x in subset s Shift A shift in an operand is specified by a prefix lowercase s before the type abbreviation See the discussion of shifts below Thus QDP_V_eq_sV c b dir sign s Chapter 4 QDP Functions 13 shifts staggered fermion data along the direction specified by dir and sign for all sites x in destination subset s Operations on arrays of fields Some of the routines can operate on multiple fields at a time These functions are designated by placing a v in front of the eqop operator The allowed egop s are then veq vpeq vmeq and veqm All arguments to the function are then made into arrays of the type the original argument was except for the subset Even scalar values QLA types and other parameters are turned into arrays The length of the arrays is then given as the last argument For example the function QDP F3 V peq M times V QDP F3 ColorVector r QDP F3 ColorMatrix a QDP F3 ColorVector b QDP Subset s becomes QDP F3 V vpeq M times V QDP F3 ColorVector r QDP F3 ColorMatrix a QDP F3 ColorVector b QDP_Subset s int n This has the same effect as the following code for i 0 i n i QDP F3 V peq M times V r i alil bli s however it may be implemented in a more efficient manner see Section 4 9 Optimization Calls page 25 It is permissible to have multiple array elements po
25. first rhs operand type M followed by a string times specifying the operation and a character V specifying the second rhs operand type Supported variants of the assignment operator are tabulated below Abbreviation Meaning eq peq meq eqm Some functions allow all of these and some take only a simple replacement eq Constant Arguments In some cases it is desirable to keep an argument constant over the entire subset For example the function QDP_V_eq_c_times_V c z b s multiplies a lattice field of color vectors by a complex constant as in c x z b x for x in subset s In this case we specify that the argument is constant coordinate independent by writing the type abbreviation in lower case c Color argument for SU N For the general color case SU N the specific function requires an extra argument giving the number of colors It always comes first Thus in the above example we would write QDP_FN_V_eq_c_times_V nc c z b s where nc specifies the number of colors In normal practice the variable nc should be replaced by the required user defined macro QDP_Ncspecifying the prevailing number of colors The generic function is actually a macro and is automatically converted to this usage with QDP_Ncfor the first argument However if the specific name is used the user must supply the argument Adjoint The adjoint of an operand is specified by a suffix a after the type abbreviation Thus QDP_V_
26. he file metadata Example QDP Writer outfile QDP String file xml QDP string create O QDP string set file xml xml string outfile QDP open write file xml filename QDP SINGLEFILE P Chapter 4 QDP Functions 18 The QDP_Writer return value is the file handle used in subsequent references to the file A null return value signals an error The I O system takes responsibility for allocating and freeing space for the handle It is assumed the user has already created the file metadata in file xml so it can be written at the head of the file The volfmt argument is either QDP_SINGLEFILE or QDP_MULTIFILE QDP_SINGLEFILE creates a single file for the output from all nodes while QDP MULTIFILE creates one file per node Close an input file Syntax int QDP close read QDP Reader reader Meaning Closes an input file Example QDP close read reader Close an output file Syntax int QDP close write QDP Writer writer Meaning Closes an output file Example QDP close write writer In both cases the integer return value is 0 for success and 1 for failure 4 7 2 Reading and writing QDP fields Reading a field z Syntax int QDP read T QDP Reader in QDP String record xml field Meaning Reads the field and its metadata from the next record in the specified file Type S I R C V H D M P Example QDP Real field QDP create R QDP read R reader record xml field
27. he subset object s The QDP_subset value s should be the object returned by QDP_create_subset All subsets in the array s are destroyed Getting the size of a subset Syntax int QDP_subset_len QDP_subset s Meaning Returns the number of sites in a subset Reductions on subsets Reduction operations norms inner products global sums come in two variants according to whether the result is computed on a single subset of the lattice or on multiple subsets Thus the operation QLA_Complex z QDP_ColorVector a b QDP_c_eq_V_dot_V amp z a b QDP even sums the dot product of the lattice staggered fermion fields a and b on the even sites and stores the result in z The operation QLA Complex z nt QDP ColorVector a b QDP c eq V dot V multi z a b ts nt with the timeslice subsets illustrated above computes the dot product summed separately on each timeslice and stores the sums in the array z so that the value in z i results from the sum on the subset ts i 4 6 Shifts Shifts are general communication operations specified by any permutation of sites Near est neighbor shifts are a special case and are preinitialized by QDP_initialize Arbitrary displacement shifts are an intermediate generalization and are created with QDP create shift Arbitrary permutations are created with QDP create map However they are cre ated all shifts are specified by a direction label dir of type QDP Shift and a sign sign of type QDP
28. hrough qdp h Only when mixing colors does one need to specify individual headers The following table lists all the QDP headers Name Purpose qdp h Master header and QDP utilities qdp_int h integers boolean qdp f h real complex single precision qdp_d h real complex double precision qdp_df h real complex precision conversion qdp_f2 h SU 2 single precision qdp_d2 h SU 2 double precision qdp_df2 h SU 2 precision conversion qdp_f3 h SU 3 single precision qdp_d3 h SU 3 qdp_df3 h SU 3 qdp fn h SU N single precision qdp dn h SU N double precision qdp_dfn h SU N precision conversion Chapter 3 Datatypes 5 3 Datatypes The Na dimensional lattice consists of all the space time sites in the problem space Lattice data are fields on these sites A data primitive describes data on a single site The lattice fields consist of the primitives over all sites We do not define data types restricted to a subset of the lattice rather lattice fields occupy the entire lattice 3 1 Generic Names The linear algebra portion of the QDP API is designed to resemble the Level 1 QLA API Thus the datatypes and function naming conventions are similar As with QLA there are two levels of generic naming fully generic in which both color and precision may be controlled globally through two macros and color generic in which precision is expl
29. icit but not color Generic naming applies to datatypes module names and accessor macros and follows similar rules Names for fully generic datatypes are listed in the table below Name Abbreviation Description QDP_RandomState S implementation dependent QDP Int I integer QDP_Real R real QDP_Complex C complex QDP ColorVector V one spin N color spinor QDP_HalfFermion H two spin Ne color spinor QDP_DiracFermion D four spin N color spinor QDP_ColorMatrix M Ne x N complex matrix QDP_DiracPropagator P 4N x 4N complex matrix The name for the corresponding primitive type also known as the QLA type is obtained by replacing the QDP prefix with a QLA prefix Thus QLA_ColorMatrix is the primitive QLA type associated with the field QDP ColorMatrix Names for color generic datatypes are obtained by inserting F for single precision or _D for double precision after QDP where appropriate Thus QDP D ColorMatrix specifies a double precision color matrix with color to be set through a global macro A long double precision type with abbreviation Q is defined for QLA but currently not for QDP 3 2 Specific Types for Color and Precision According to the chosen color and precision names for specific floating point types are constructed from names for generic types Thus QDP ColorMatrixbecomes QDP PC ColorMatrix where the precision P is F or D according to the table below Chapter 3 Datatypes 6 Abbreviation Descript
30. ing r ic is jc js alic is for all ic is Trace of color matrix Syntax QDP C eq trace M QDP Complex r QDP ColorMatrix a subset Meaning r trace a Real Imaginary part of trace of color matrix Syntax QDP R eq func M QDP Real r QDP_ColorMatrix a subset Meaning r func a func re trace im trace Traceless antihermitian part of color matrix Syntax QDP_M_eq_antiherm_M QDP_ColorMatrix r QDP_ColorMatrix a subset Meaning r a a dagger 2 i Im Tr a n c M ON MM M B5 bL I Ke RR AS Chapter 5 Function Details 37 Spin trace of Dirac propagator Syntax QDP_M_eq_spintrace_P QDP_ColorMatrix r QDP_DiracPropagator a subset Meaning r ic jc Sum is alic is jc is Dirac spin projection Syntax QDP_H_eqop_spproj_D QDP_HalfFermion r QDP_DiracFermion a int dir int sign subset QDP_H_veqop_spproj_D QDP_HalfFermion r QDP_DiracFermion a int dir int sign subset int n Meaning r spin project a dir sign eqop eq peq meq eqm Dirac spin reconstruction Syntax QDP D eqop sprecon H QDP DiracFermion r QDP HalfFermion a int dir int sign subset QDP D veqop sprecon H QDP DiracFermion r QDP HalfFermion a int dir int sign subset int n Meaning r spin reconstruct a dir sign eqop eq peq meq eqm Dirac spin projection with re
31. int to the same field The result will always agree with that of the above for loop 4 4 Creating and destroying lattice fields All QDP fields are creted and destroyed with the following functions The alignment and type of memory on architectures that support it is detrmined by the default alignment and flags see Section 4 9 Optimization Calls page 25 Creating a lattice field Syntax Type QDP create T void Meaning Creates lattice field of type Type Type S I R C V H D M P Example u QDP_create_M In prototype specifications throughout this document the notation Type specifies the generic or specific datatype name matching the abbreviation T according to the table in Chapter 3 Datatypes page 5 Chapter 4 QDP Functions 14 Destroying a lattice field Syntax void QDP_destroy_T Type a Meaning Frees memory associated with field a Type S I R C V H D M P Example QDP_destroy_M u 4 5 Subsets All QDP linear algebra and shift operations require specifying the subset of the lattice on which the operation is performed The subset may be the entire lattice When defining subsets it is often convenient to partition the lattice into multiple disjoint subsets e g time slices or checkerboards Such subsets are defined through a user supplied function that returns a range of integers 0 1 2 n 1 so that if f x i then site z is in partition i A single subset may
32. ion F single precision D double precision and C is 2 3 or N if color is a consideration as listed below Abbreviation Description 2 SU 2 3 SU 3 N SU N If the datatype carries no color the color label is omitted Integers also have no precision label Likewise for functions if none of the arguments carry color the color label is omitted and if all numeric arguments are integers the precision label is omitted For example the type QDP F3 DiracFermion describes a single precision four spin three color spinor field The general color choice N can also be used for specialized SU 2 or SU 3 at the cost of degrading performance 3 3 Color and Precision Uniformity In standard coding practice it is assumed that a user keeps one of the precision and color options in force throughout the compilation So as a rule all functions in the interface take operands of the same precision and color As with data type names function names come in generic and color and precision specific forms as described in the next section Exceptions to this rule are functions that explicitly convert from double to single precision and vice versa These and functions that do not depend on color or precision are divided among thirteen separate libraries If the user chooses to adopt color and precision uniformity then all variables can be defined with generic types and all functions accessed through generic names The prevailing color and precisio
33. le length QDP string length xml Accessing the character string Syntax char QDP string ptr QDP String qs Meaning Returns a pointer to the null terminated character array in the string Example printf AsNn QDP string ptr xm1 Syntax size t QDP string length QDP String qs 4 8 Temporary entry and exit from QDP For a variety of reasons it may be necessary to remove data from QDP structures Con versely it may be necessary to reinsert data into QDP structures For example a highly optimized linear solver may operate outside QDP T he operands would need to be extracted Chapter 4 QDP Functions 23 from QDP fields and the eventual solution reinserted It may also be useful to suspend QDP communications temporarily to gain separate access to the communications layer For this purpose function calls are provided to put the QDP implementation and or QDP objects into a known state extract values and reinsert them Exposing QDP data Syntax QLA Type QDP expose T Type src Meaning Deliver data values from field src Type I R C V H D M P Example r QDP_expose_M a This function grants direct access to the data values contained in the QDP field src The return value is a pointer to an array of QLA data dest of type T The order of the data is given by QDP index No QDP operations are permitted on exposed data until QDP reset is called See next Returning control of
34. lic is jc js Inserting a Dirac propagator matrix element Syntax QDP_P_eq_elem_C QDP_DiracPropagator r QDP_Complex a int ic int is int jc int js subset Meaning r ic is jc js a Extracting a color vector from a color matrix column j subset Meaning r i afi j for all i Inserting a color vector into a color matrix column Syntax QDP_M_eq_colorvec_V QDP_ColorMatrix r QDP_ColorVector a int j subset Meaning r i j ali for all i Extracting a color vector from a half fermion or Dirac fermion Syntax QDP V eq colorvec T QDP ColorVector r Type a int spin subset Meaning r color a color spin for all color Type H D Syntax QDP_V_eq_colorvec_M QDP_ColorVector r QDP_ColorMatrix a Chapter 5 Function Details 36 Inserting a color vector into a half fermion or Dirac fermion Syntax QDP_T_eq_colorvec_V Type r QDP_ColorVector a int spin subset Meaning r color spin a color for all color Type H D Extracting a Dirac vector from a Dirac propagator matrix column Syntax QDP D eq diracvec P QDP DiracFermion r QDP_DiracPropagator a int jc int js subset Meaning r ic is alic is jc js for all ic is Inserting a Dirac vector into a Dirac propagator matrix column Syntax QDP P eq diracvec D QDP DiracPropagator r QDP DiracFermion a int jc int js subset Mean
35. me and does not interfere with QDP operations Extracting QDP data to a packed array Syntax void QDP_extract_packed_T QLA_Type dest Type src Meaning Copy data values from field src to array dest Type I R C V H D M P Example QDP extract M r a QDP even The user must allocate space of size QDP subset len subset sizeof QLA Type for the destination array before calling this function This function copies the data values contained in the QDP field src to the destination field Only values belonging to the specified subset are copied and they are stored contiguously in the destination array The order of the data is given by QDP index Since a copy is made QDP operations involving the source field may proceed without disruption Inserting QDP data from a packed array Syntax void QDP insert packed T Type dest QLA Type src Meaning Inserts data values from QLA array src Type I R C V H D M P Example QDP insert M a r Only data associated with the specified subset are inserted Other values are unmodified The data order must conform to QDP index This call analogous to a fill operation is permitted at any time and does not interfere with QDP operations Suspending QDP communications If a user wishes to suspend QDP communications temporarily and carry on communications by other means it is first necessary to call QDP suspend comm Chapter 4 QDP Functions 25 Sy
36. n fills Syntax QDP_T_eq_funci Type r void func QLA_Type dest int index subset Meaning calls func amp r x index x for all coordinates x in subset Type I R C V H D M P 5 3 Unary Operations Bitwise not Syntax QDP_I_eq_not_I QDP_Int r QDP_Int a subset Meaning r not a Elementary unary functions on reals Syntax QDP_R_eq_func_R QDP_Real r QDP_Real a subset Meaning r func a func sin cos tan asin acos atan sqrt fabs exp log sign ceil floor sinh cosh tanh logi 0 Chapter 5 Function Details Elementary unary functions real to complex 31 Syntax QDP_C_eq_cexpi_R QDP_Complex r QDP Real a subset Meaning r exp ia Elementary unary functions complex to real Syntax QDP_R_eq_func_C QDP_Real r QDP_Complex a subset Meaning r func a func norm arg Elementary unary functions on complex values Ne M KR aa Syntax QDP C eq func C QDP Complex r QDP Complex a subset Meaning r func a func cexp csqrt clog Copying Syntax QDP T eq T Type r Type a subset QDP T veq T Type r Type a subset int n Meaning rai Type S I R C V H D M P Incrementing Syntax QDP T eqop T Type r Type a subset QDP T veqop T Type r Type al subset int n Meaning r eqop a Type I R C V H D M P eqop eqm peq meq
37. n is then defined through macros The interface automatically translates data type names and function names to the appropriate specific type names through typedefs and macros With such a scheme and careful coding changing only two macros and the QDP library converts code from one color and precision choice to another 3 4 Breaking Color and Precision Uniformity It is permissible for a user to mix precision and color choices This is done by declaring variables with specific type names using functions with specific names and making appro priate precision conversions when needed In this case it may be necessary to link against a larger set of libraries Chapter 4 QDP Functions 7 4 QDP Functions The QDP functions are grouped into the following categories e Entry and exit from QDP e Layout utilities e Data parallel functions e Data management utilities e Subset definition e Shift creation e I O utilities e Temporary exit and reentry e Optimization calls 4 1 Entry and exit from QDP QDP must first be initialized before any QDP functions are to be used except for QDP_is_ initialized which may be called anytime Initializing QDP also initializes QMP if it has not already been done Thus the user can safely start QMP before QDP and do any necessary broadcasts or other operations Before any QDP field operations are done one must also create the lattice layout Entry to QDP Syntax void QDP initialize int argc char
38. near algebra with and without shifts Because of the variety of datatypes and assignment operations there are a few hundred names altogether However there are only a couple dozen categories It is hoped that the construction of the names is sufficiently natural that with only a little practice the user can guess the name of any function and determine its functionality without consulting a list In prototype specifications throughout this document the notation Type specifies the generic or specific datatype name matching the abbreviation T according to the table in Chapter 3 Datatypes page 5 We also introduce the shorthand define subset QDP_Subset subset Unless otherwise indicated operations occur on all sites in the specified subset 5 1 Functions involving shifts Shifting Syntax QDP T eq sT Type r Type a QDP Shift s QDP ShiftDir d subset QDP T veq sT Type r Type a QDP Shift s QDP_ShiftDir d subset int n Meaning r shift a Type I R C V H D M P Left multiplication by shifted color matrix Syntax QDP T eq SM times T Type r QDP_ColorMatrix a Type b QDP Shift s QDP_ShiftDir d subset Meaning r shift a b Type V H D M P Left multiplication of shifted field by color matrix Syntax QDP T eq M times sT Type r QDP ColorMatrix a Type b QDP Shift s QDP_ShiftDir d subset Meaning r a shift b Type V H D M P
39. ntax QDP_R_eq_I QDP_Real r QDP Int a subset Meaning r a Real to integer truncate round Syntax QDP_I_eq_func_R QDP_Int r QDP_Real a subset Meaning r func a func trunc round Nee Ne Ree er Chapter 5 Function Details 34 Accessing a color matrix element Syntax QDP_C_eq_elem_M QDP_Complex r QDP_ColorMatrix a int i int j subset Meaning fe Inserting a color matrix element Syntax QDP M eq elem C QDP ColorMatrix r QDP Complex a int i int j subset Meaning ri 4 Accessing a half fermion or Dirac fermion spinor element Syntax QDP C eq elem T QDP Complex r Type a int color int spin subset Meaning r a color spin Type H D Inserting a half fermion or Dirac fermion spinor element Syntax QDP T eq elem C Type r QDP Complex a int color int spin subset Meaning r color spin a Type H D Accessing a color vector element Syntax QDP C eq elem V QDP Complex r QDP ColorVector a int i subset Meaning r ali Mee NR aoa a a cO e i No SUNL of Chapter 5 Function Details 35 Inserting a color vector element Syntax QDP_V_eq_elem_C QDP_ColorVector r QDP_Complex a int i subset Meaning rli a Accessing a Dirac propagator matrix element Syntax QDP_C_eq_elem_P QDP_Complex r QDP_DiracPropagator a int ic int is int jc int js subset Meaning r a
40. ntax void QDP suspend comm void Meaning Suspends QDP communications Example QDP suspend comm No QDP shifts can then be initiated until QDP resume is called However QDP linear algebra operations without shifts may proceed Resuming QDP communications To resume QDP communications one uses Syntax void QDP resume comm void Meaning Restores QDP communications Example QDP resume comm 4 9 Optimization Calls The following procedures are included to aid in optimization of the QDP implementation Marking discarded data Syntax void QDP discard T Type a Meaning Indicates data in a is no longer needed Type I R C V H D M P Example QDP discard M utemp The field is not destroyed and memory is not released For that purpose see QDP_ destroy This call allows the implementation to ignore the data dependency that may have been created from a shift which allows the shift to be efficiently reused later It is a runtime error to attempt to use discarded data as an rvalue source operand or incremented destination in any subsequent operation However once the field is used as an lvalue fully replaced destination data integrity is automatically reinstated This should be called on the result of a shift once the result is no longer needed It is safe to call it for any field as long as the data is no longer needed It is highy recommended for the sake of efficiency that one always call
41. ogically SIMD acting on all sites across the lattice or on subsets of these sites e Allows creation of arbitrary subsets of sites e All math operations are handled by the SciDAC QLA library which has optimized versions for SSE Intel AMD and 440 QCDOC BG L architectures e Allows asynchronous non blocking shifts of lattice level objects over any permutation map of sites onto sites e Automatically handles dependency of shifts and waits on the results only when needed e Uses the SciDAC QMP library for communications which is available for all MPI plat forms and QCDOC e Provides some combined shift and linear algebra instructions for convenience and op timization e Provides fill operations filling a lattice quantity from a scalar value s global reduc tion operations and lattice wide operations on various data type primitives such as matrices vectors and propagators e Has flexible I O capabilities allowing reading and writing of all lattice fields and also global data e Uses SciDAC QIO library for I O which is compatible with the USQCD and ILDG standards Chapter 2 Compilation with QDP 2 2 Compilation with QDP 2 1 Header and macros The main header file for QDP is qdp h and must be included in all QDP programs This will automatically include any other header files that are necessary for the specified number of colors and will also include the QLA headers Typically the user will want to select a prevailing colo
42. r QDP With such a preamble the generic function names and datatypes are automatically mapped to the appropriate specific types Of course the precision and color macros can also be defined through a compiler flag as in gcc DQDP Precision 2 DQDP_Nc 3 For SU 4 one might do define QDP Precision F define QDP Nc 4 include lt qdp h gt Chapter 2 Compilation with QDP 3 2 2 Libraries Normally it is necessary to link four QDP libraries for a given choice of color and precision Other libraries may be required if mixing precisions or numbers of color Routines involving only integers and the random state are common to all choices Routines involving only real or complex numbers are common to all colors Thus for single precision SU 3 the required libraries are linked through lqdp_f3 lqdp_f lqdp_int lqdp_common with the library search path set to QDP_HOME 1ib Each library will depend on the corre sponding QLA library Also since global sums are done in a higher precision using them requires linking to QLA libraries of the next higher precision in addition to the correspond ing conversion library For the above example one would also need lqla_f3 lqla_f lqla_d3 lqla_d lqla_df3 1gla df lqla_int lqla_random lqla_cmath 1m in addition to the QIO and QMP libraries which typically are lqio llime lqmp and any other system dependent libraries such as MPI A complete list of the QDP libraries is given below
43. r and precision for the entire calculation This allows one to use generic function names and datatypes making it possible to change colors and precision with a simple recompilation if desired The following macros can be defined by the user prior to including this header file Optional Macros Choices Default QDP_Precision F 1 D 2 EY QDP Nc number of colors 3 QDP Colors 2 3 N 3 Single quotes are required around nonnumeric values The QDP Precision macro sets the default precision to either single 1 or F or double 2 or D The QDP Nc macro sets the default number of colors and can be any positive integer Note however that QLA may have been compiled with a limit on the maximum allowed value QDP Colors determines which QDP and QLA library versions will be used for calculations It is automatically set to 2 when QDP Nc is 2 3 when 3 and N otherwise If for some reason a users wishes to work with the N namespace for two or three colors rather than the more efficient 2 or 3 namespace they may do so by setting this macro to N explicitly The number of spins is fixed in QDP to be the same value that the QLA library that QDP was compiled against has which defaults to 4 A sample preamble for double precision SU 3 reads define QDP Precision D define QDP Nc 3 include lt qdp h gt with the include search path set to QDP_HOME include and QDP_HOME set to the home directory fo
44. rd_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 ke M a eK ne Ne Fe The linear index returned by QDP_index ranges from 0 to QDP_sites_on_node 1 Chapter 4 QDP Functions 11 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
45. shift d A The displacement vector points from the recieving site towards the sender or the op posite if later used with the QDP_backward direction Calling with a displacement vector 1 0 0 0 would reproduce the shift QDP_neighbor 0 Creating arbitrary permutations Syntax QDP_Shift QDP_create_map void func int rx Nd int sx Nd QDP_ShiftDir fb void args void args int argsize ES Meaning Creates a shift specified by the permutation map func Example int mu 1 QDP Shift mirror 4 mirror mu QDP create map reflect amp mu sizeof mu where reflect rx sx QDP forward mu sets sx i rx i except for sx mu L mu 1 rx mu The return value is used in the various linear algebra calls involving shifts The argu ments args are passed through to the calling function The argsize parameter specifies the byte length of the argument array or structure The implementation may choose to postpone construction of a shift Thus it is required that the callback function func be static and invariant i e a function call with the same arguments must give the same result even if the call is postponed The parameters args are copied at the moment the shift is created however so they may be volatile The size argument argsize makes copying possible Chapter 4 QDP Functions I Destroying a shift The corresponding destruction function is QDP destroy shift Syntax void QDP destroy
46. th the macro QDP_PROFILE defined This must be defined before the qdp h header is included When QDP_finalize is called a list of QDP function and call times will be sent to stdout on node 0 This function toggles the accumulation of the profiling statistics within the profiled sections of code A value of zero turns the collection of timing info off and nonzero values turn it on It is on by default Control checking communications Syntax int QDP_check_comm int new Meaning Controls checking communications Example old QDP_check_comm new A nonzero value turns the internal communications checksums on and zero turns it off It is off by default 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 Chapter 4 QDP Functions 9 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 sub lattice dimensions on every node It would be relatively easy to add other layouts if the need arised Defining the layout Prior to creating the
47. ubset Meaning r eqop Tr adjoint a b eqop C V HD MP Type eq peq meq eqm Real part of local inner product Syntax QDP R eqop T dot T QDP Real r Type a Type b subset Meaning r eqop Re Tr adjoint a b eqop C V H D M P Type eq_re peq_re meq_re eqm_re Color matrix from outer product S Syntax QDP_M_eqop_V_times_Va QDP_ColorMatrix r QDP_ColorVector a QDP_ColorVector b subset QDP_M_veqop_V_times_Va QDP_ColorMatrix r QDP_ColorVector a QDP_ColorVector b subset int n Meaning rli j eqop ali bij eqop eq peq meq eqm P 5 7 Ternary operations with fields Addition or subtraction with integer scalar multiplication Syntax QDP_I_eq_i_times_I_func_I QDP_Int r QLA Int c QDP Int xa QDP Int b subset Meaning r c a b func plus minus Chapter 5 Function Details Addition or subtraction with real scalar multiplication 44 z Syntax QDP T eq r times T func T Type r QLA Real c Type a Type b subset QDP T veq r times T func T Type r QLA Real c Type al Type b subset int n Meaning r c a b Type R C V H D M P func plus minus Addition or subtraction with complex scalar multiplication s Syntax QDP T eq c times T func T Type r QLA Complex c Type a Type b subset QDP T veq c times T func T Type r QLA Complex c Type
48. xample QDP next record reader Chapter 4 QDP Functions 20 Writing a field C Y Syntax int QDP write T QDP Writer out QDP String record xml QDP Type field Meaning Writes the field and its metadata as the next record in the specified file Type S I R C V H D M P Example QDP Real field QDP create R QDP R eq zero field QDP all QDP write R writer record xml field A The integer return value is 0 for success and 1 for failure It is assumed the user has created the QDP String for the record metadata and the array for the data in advance Writing an array of fields C gt Syntax int QDP write vT QDP Writer out QDP_String record xml QDP Type field int n Meaning Writes the array of fields and its metadata as the next record in the specified file Type S I R C V H D M P Example QDP_ColorMatrix field 4 for i 0 i lt 4 i field i QDP_create_M for i 0 i 4 i QDP M eq zero field i QDP a11 QDP write vM writer record xml field 4 The integer return value is 0 for success and 1 for failure It is assumed the user has prepared the record metadata and the array data in advance 4 7 3 Reading and writing QLA arrays QLA data is global data that carries no lattice site index Typically these values result from a global reduction For example a correlation function might be computed on every time slice of the lattice and summed globall
49. y over the entire machine From the standpoint of data parallel I O operation the data is treated as a global quantity with the same name and value on every processor When it is written to a file it is assumed that the values are the same on each node so only one node needs to write its value When it is read from a file the I O system does a broadcast to every node so the result of reading is a global value An interface is provided for reading and writing arrays of QLA data Single QLA values can be passed as an array of length one The naming conventions for the routines follow conventions of the QDP API Notice that the encoded QLA data type is lower case and the argument is a pointer to a QLA type Chapter 4 QDP Functions 21 Reading a QLA array Z Syntax int QDP vread t QDP Reader in QDP String record xml QLA Type array int n Meaning Reads the QLA array and its metadata from the next record in the specified file Type S I R C V H D M P Example QLA Complex array nt QDP_vread_c reader record_xml array nt The integer return value is 0 for success and 1 for failure It is assumed the user has created the record metadata and the field data in advance Writing an array of QLA values Syntax int QDP write vt QDP Writer out QDP String record xml QLA Type array int n Meaning Writes the QLA array and its metadata as the next record in the specified file Type S

QDP/C User Manual

Contents

Download Pdf Manuals

Related Search

Related Contents