StdFace_ModelUtil.h

Purpose

Core model utilities for lattice construction and physical interactions. This header provides functions to:

• Construct various lattice geometries (chain, honeycomb, kagome, etc.)

• Set up hopping and interaction terms

• Handle input parameter validation and printing

• Manage site labeling and memory allocation for interaction arrays

Source reference: src/StdFace_ModelUtil.h

Public Types

None defined in this header. Uses struct StdIntList from StdFace_vals.h.

Public Macros/Constants

None.

Public Functions

Error/Exit Functions

void StdFace_exit(int errorcode)

Terminates the program with the given error code.

Parameters:

• errorcode – Exit status code

Interaction Generator Functions

void StdFace_intr(struct StdIntList *StdI, double complex intr0, int site1, int spin1, int site2, int spin2, int site3, int spin3, int site4, int spin4)

Adds a general two-body interaction term to the interaction list.

Parameters:

• StdI – Pointer to the configuration structure

• intr0 – Complex coefficient of the interaction

• site1 – First site index

• spin1 – First spin index

• site2 – Second site index

• spin2 – Second spin index

• site3 – Third site index

• spin3 – Third spin index

• site4 – Fourth site index

• spin4 – Fourth spin index

void StdFace_Hopping(struct StdIntList *StdI, double complex trans0, int isite, int jsite, double *dR)

Adds a hopping term between two sites.

Parameters:

• StdI – Pointer to the configuration structure

• trans0 – Complex hopping amplitude

• isite – Source site index

• jsite – Destination site index

• dR – Displacement vector (3 elements)

void StdFace_trans(struct StdIntList *StdI, double complex trans0, int isite, int ispin, int jsite, int jspin)

Adds a transfer (one-body) term with explicit spin indices.

Parameters:

• StdI – Pointer to the configuration structure

• trans0 – Complex transfer amplitude

• isite – Source site index

• ispin – Source spin index

• jsite – Destination site index

• jspin – Destination spin index

void StdFace_HubbardLocal(struct StdIntList *StdI, double mu0, double h0, double Gamma0, double Gamma0_y, double U0, int isite)

Sets up local Hubbard model terms (chemical potential, magnetic field, on-site U).

Parameters:

• StdI – Pointer to the configuration structure

• mu0 – Chemical potential

• h0 – Longitudinal magnetic field

• Gamma0 – Transverse magnetic field (x)

• Gamma0_y – Transverse magnetic field (y)

• U0 – On-site Coulomb interaction

• isite – Site index

void StdFace_MagField(struct StdIntList *StdI, int S2, double h, double Gamma, double Gamma_y, int isite)

Adds magnetic field terms for spin models.

Parameters:

• StdI – Pointer to the configuration structure

• S2 – Total spin 2S

• h – Longitudinal field

• Gamma – Transverse field (x)

• Gamma_y – Transverse field (y)

• isite – Site index

void StdFace_Coulomb(struct StdIntList *StdI, double V, int isite, int jsite)

Adds inter-site Coulomb interaction.

Parameters:

• StdI – Pointer to the configuration structure

• V – Coulomb interaction strength

• isite – First site index

• jsite – Second site index

void StdFace_GeneralJ(struct StdIntList *StdI, double J[3][3], int Si2, int Sj2, int isite, int jsite)

Adds general exchange interaction with full 3x3 J matrix.

Parameters:

• StdI – Pointer to the configuration structure

• J – 3x3 exchange coupling matrix

• Si2 – Spin 2S at site i

• Sj2 – Spin 2S at site j

• isite – First site index

• jsite – Second site index

Print Utility Functions

void StdFace_PrintVal_d(char *valname, double *val, double val0)

Prints a double parameter value; sets default if unspecified.

Parameters:

• valname – Name of the parameter

• val – Pointer to the value (may be modified)

• val0 – Default value

void StdFace_PrintVal_dd(char *valname, double *val, double val0, double val1)

Prints a double parameter with two possible defaults.

Parameters:

• valname – Name of the parameter

• val – Pointer to the value

• val0 – Primary default value

• val1 – Secondary default value

void StdFace_PrintVal_c(char *valname, double complex *val, double complex val0)

Prints a complex parameter value.

Parameters:

• valname – Name of the parameter

• val – Pointer to the complex value

• val0 – Default complex value

void StdFace_PrintVal_i(char *valname, int *val, int val0)

Prints an integer parameter value.

Parameters:

• valname – Name of the parameter

• val – Pointer to the integer value

• val0 – Default value

Validation Functions

void StdFace_NotUsed_d(char *valname, double val)

Warns if a double parameter was specified but is not used in the current model.

Parameters:

• valname – Name of the parameter

• val – The specified value

void StdFace_NotUsed_i(char *valname, int val)

Warns if an integer parameter was specified but is not used.

Parameters:

• valname – Name of the parameter

• val – The specified value

void StdFace_NotUsed_c(char *valname, double complex val)

Warns if a complex parameter was specified but is not used.

Parameters:

• valname – Name of the parameter

• val – The specified value

void StdFace_NotUsed_J(char *valname, double JAll, double J[3][3])

Warns if exchange parameters were specified but not used.

Parameters:

• valname – Name of the J parameter

• JAll – Isotropic J value

• J – 3x3 J matrix

void StdFace_RequiredVal_i(char *valname, int val)

Checks that a required integer parameter was specified; exits if not.

Parameters:

• valname – Name of the parameter

• val – The value to check

Input Processing Functions

void StdFace_InputSpinNN(double J[3][3], double JAll, double J0[3][3], double J0All, char *J0name)

Processes nearest-neighbor spin coupling input.

Parameters:

• J – Output 3x3 matrix

• JAll – Isotropic coupling

• J0 – Anisotropic coupling matrix

• J0All – Anisotropic isotropic coupling

• J0name – Parameter name for messages

void StdFace_InputSpin(double Jp[3][3], double JpAll, char *Jpname)

Processes spin coupling input (general).

Parameters:

• Jp – Output 3x3 matrix

• JpAll – Isotropic coupling

• Jpname – Parameter name for messages

void StdFace_InputCoulombV(double V, double *V0, char *V0name)

Processes Coulomb interaction input.

Parameters:

• V – General V value

• V0 – Pointer to specific V value

• V0name – Parameter name

void StdFace_InputHopp(double complex t, double complex *t0, char *t0name)

Processes hopping parameter input.

Parameters:

• t – General hopping value

• t0 – Pointer to specific hopping value

• t0name – Parameter name

Site/Lattice Utility Functions

void StdFace_InitSite(struct StdIntList *StdI, FILE *fp, int dim)

Initializes site arrays and lattice geometry.

Parameters:

• StdI – Pointer to the configuration structure

• fp – Output file pointer for geometry information

• dim – Lattice dimensionality (1, 2, or 3)

void StdFace_SetLabel(struct StdIntList *StdI, FILE *fp, int iW, int iL, int diW, int diL, int isiteUC, int jsiteUC, int *isite, int *jsite, int connect, double complex *Cphase, double *dR)

Sets site labels and computes connection information (2D lattices).

Parameters:

• StdI – Configuration structure

• fp – Output file pointer

• iW – Cell index (W direction)

• iL – Cell index (L direction)

• diW – Displacement in W direction

• diL – Displacement in L direction

• isiteUC – Source unit cell site index

• jsiteUC – Target unit cell site index

• isite – Output source global site index

• jsite – Output target global site index

• connect – Connection type

• Cphase – Output boundary phase

• dR – Output displacement vector

void StdFace_PrintGeometry(struct StdIntList *StdI)

Outputs geometry information to file.

Parameters:

• StdI – Configuration structure

void StdFace_MallocInteractions(struct StdIntList *StdI, int ntransMax, int nintrMax)

Allocates memory for transfer and interaction arrays.

Parameters:

• StdI – Configuration structure

• ntransMax – Maximum number of transfer terms

• nintrMax – Maximum number of interaction terms

void StdFace_FindSite(struct StdIntList *StdI, int iW, int iL, int iH, int diW, int diL, int diH, int isiteUC, int jsiteUC, int *isite, int *jsite, double complex *Cphase, double *dR)

Finds site indices with full 3D support.

Parameters:

• StdI – Configuration structure

• iW – Cell index (W direction)

• iL – Cell index (L direction)

• iH – Cell index (H direction)

• diW – Displacement in W direction

• diL – Displacement in L direction

• diH – Displacement in H direction

• isiteUC – Source unit cell site index

• jsiteUC – Target unit cell site index

• isite – Output source global site index

• jsite – Output target global site index

• Cphase – Output boundary phase

• dR – Output displacement vector

void StdFace_PrintXSF(struct StdIntList *StdI)

Outputs XSF format file for visualization.

Parameters:

• StdI – Configuration structure

Lattice Constructor Functions

void StdFace_Chain(struct StdIntList *StdI)

Constructs a 1D chain lattice.

Parameters:

• StdI – Configuration structure (modified in place)

void StdFace_Ladder(struct StdIntList *StdI)

Constructs a 1D ladder lattice.

Parameters:

• StdI – Configuration structure

void StdFace_Tetragonal(struct StdIntList *StdI)

Constructs a 2D square/tetragonal lattice.

Parameters:

• StdI – Configuration structure

void StdFace_Triangular(struct StdIntList *StdI)

Constructs a 2D triangular lattice.

Parameters:

• StdI – Configuration structure

void StdFace_Honeycomb(struct StdIntList *StdI)

Constructs a 2D honeycomb lattice.

Parameters:

• StdI – Configuration structure

void StdFace_Kagome(struct StdIntList *StdI)

Constructs a 2D Kagome lattice.

Parameters:

• StdI – Configuration structure

void StdFace_Orthorhombic(struct StdIntList *StdI)

Constructs a 3D orthorhombic/cubic lattice.

Parameters:

• StdI – Configuration structure

void StdFace_FCOrtho(struct StdIntList *StdI)

Constructs a 3D face-centered orthorhombic/cubic lattice.

Parameters:

• StdI – Configuration structure

void StdFace_Pyrochlore(struct StdIntList *StdI)

Constructs a 3D pyrochlore lattice.

Parameters:

• StdI – Configuration structure

void StdFace_Wannier90(struct StdIntList *StdI)

Constructs a lattice from Wannier90 tight-binding data.

Parameters:

• StdI – Configuration structure

Conditional Functions (Mode-specific)

The following functions are only available in specific build modes:

HPhi mode (_HPhi defined):

• StdFace_Chain_Boost()

• StdFace_Ladder_Boost()

• StdFace_Honeycomb_Boost()

• StdFace_Kagome_Boost()

mVMC mode (_mVMC defined):

• StdFace_generate_orb()

• StdFace_Proj()

• PrintJastrow()

Ownership and Lifetime Rules

• The StdIntList *StdI parameter is never allocated or freed by these functions; the caller (StdFace_main()) is responsible for its lifetime.

• StdFace_MallocInteractions() allocates internal arrays within StdI; these are freed by the caller after output generation.

• Memory allocation uses functions from setmemory.h.

Error Handling

• StdFace_exit(errorcode) terminates the program with the given code.

• StdFace_RequiredVal_i() calls StdFace_exit() if a required parameter is missing.

• Invalid parameter combinations result in error messages printed to stdout followed by program termination.

Thread / MPI Safety

Unspecified in the current code. No explicit threading or MPI constructs are present.

Source Reference

• Header: src/StdFace_ModelUtil.h

• Implementation: src/StdFace_ModelUtil.c

• Lattice implementations: src/ChainLattice.c, src/SquareLattice.c, etc.