2.5. Troubleshooting

This section explains error messages that may occur during \({\mathcal H}\Phi\) execution and how to resolve them.

2.5.1. Quick Reference

Command-line and File Errors

Error Message	Cause	Solution
argument count is incorrect	Invalid number of command-line arguments	Run as HPhi -e namelist.def or HPhi -s stan.in
Error: The file (filename) does not exist.	Specified file does not exist	Check file path and filename
ERROR: Open input file	Cannot open input file	Verify file existence and read permissions

Keyword and Parameter Errors

Error Message	Cause	Solution
ERROR ! Unsupported Keyword !	Non-existent keyword specified	Check manual for supported keywords
ERROR ! Keyword (name) is duplicated !	Same keyword specified twice	Remove duplicate keyword
ERROR ! (name) is NOT specified !	Required keyword not specified	Add the required keyword

Model and Solver Errors

Error Message	Cause	Solution
ERROR ! Unsupported Solver : (name)	Unsupported solver specified	Use Lanczos, TPQ, FullDiag, CG, or TimeEvolution
ERROR ! Unsupported Model : (name)	Unsupported model specified	Use Hubbard, Spin, Kondo, or SpinlessFermion
Sorry, this system is unsupported in the STANDARD MODE...	Unsupported model/lattice combination	Use Expert mode or choose a supported combination

Memory Errors

Error Message	Cause	Solution
Malloc ERROR for XXX	Memory allocation failed	Reduce system size or use a machine with more memory
There is not enough memory. Please reduce MPI process number.	Not enough memory per process	Reduce MPI process count to increase memory per process

MPI Errors

Error Message	Cause	Solution
You can not use OpenMP and MPI at the same time.	OpenMP and MPI combination is restricted	Use either OpenMP or MPI
ERROR: MPI process count is not a power of 2	MPI process count is not a power of 2	Set MPI process count to 1, 2, 4, 8, 16, etc.
ERROR: Not enough MPI processes.	Insufficient MPI processes	Increase the process count

Hamiltonian Validation Errors (Canonical Ensemble)

The following errors occur when the combination of site count, electron count, and spin is physically impossible in canonical ensemble calculations.

Error Message	Meaning
ERROR ! abs(2 * Sz) > nsite in Hubbard model !	Absolute value of Sz exceeds half the number of sites
ERROR ! Nelec > 2 * nsite in Hubbard model !	Electron count exceeds twice the number of sites
ERROR ! (nelec + 2 * Sz) % 2 != 0 in Hubbard model !	Parity of electron count and Sz does not match
ERROR ! nelec <= nsite && 2 * |Sz| > nelec in Hubbard model !	Sz is too large for the electron count
ERROR ! nelec > nsite && 2 * |Sz| > 2 * nsite - nelec in Hubbard model !	Sz is too large when electron count is high
ERROR ! abs(2 * Sz) > nsite in Spin model !	Sz exceeds half the number of sites in spin model
ERROR ! (nsite + 2 * Sz) % 2 != 0 in Spin model !	Parity of site count and Sz does not match in spin model
ERROR ! Nelec_cond / 2 + Nelec_loc > nsite in Kondo model !	Electron count exceeds site count in Kondo model
ERROR ! (nelec_cond + nelec_loc + 2 * Sz) % 2 != 0 in Kondo model !	Parity of electron count and Sz does not match in Kondo model

Solution: Check input parameters Nsite, Nelec, 2Sz and correct to physically valid combinations.

Warning Messages

Message	Description
Check ! (name) is SPECIFIED but will NOT be USED.	Specified parameter is not used in current calculation. Comment out if unnecessary
(name) = (value) ###### DEFAULT VALUE IS USED ######	Default value is being used (not an error)

---

2.5.2. Detailed Solutions for Common Errors

Out of Memory Error

Symptom: Malloc ERROR is displayed and calculation cannot start.

Cause: Hilbert space dimension is too large and required memory cannot be allocated.

Solutions:

1. Reduce system size

   Reducing the number of sites exponentially decreases the Hilbert space dimension.

2. Increase MPI process count

   Using more processes like mpirun -np 16 HPhi ... distributes the Hilbert space across processes.

3. Check available memory

   Review CHECK_Memory.dat to understand required memory.

MPI Process Count Error

Symptom: ERROR: MPI process count is not a power of 2

Cause: \({\mathcal H}\Phi\) requires MPI process count to be a power of 2 (1, 2, 4, 8, 16, 32, …).

Solution:

# Correct examples
mpirun -np 4 HPhi -e namelist.def
mpirun -np 8 HPhi -e namelist.def
mpirun -np 16 HPhi -e namelist.def

# Wrong example (3 is not a power of 2)
mpirun -np 3 HPhi -e namelist.def  # Error

File Not Found Error

Symptom: Error: The file (filename) does not exist.

Solutions:

1. Verify filenames in namelist.def

2. For relative paths, check position relative to execution directory

3. Check case sensitivity of filenames (Linux/macOS are case-sensitive)

Convergence Issues

Symptom: Lanczos or CG method does not converge.

Solutions:

1. Increase Lanczos steps

   Adjust LanczosEps or Lanczos_max in ModPara file

2. Change initial vector

   Try different random seeds with initial_iv parameter

3. Degenerate eigenvalues

   Convergence may be slow when degenerate eigenvalues exist