SCS_Lanczos Documentation

Capabilities · Ground state

Ground-state calculations

Worked examples for obtaining ground-state energies and eigenvectors with the Lanczos method in SCS_Lanczos.

Documentation Ground-state calculations

Choose a model

Ground-state examples

The examples follow a common workflow—select the model and symmetry sector, prepare the input, run Lanczos, and inspect the converged ground state.

Detailed example

Spin model

Ground-state calculation using the Model_Spins implementation.

Open example →
Planned

Hubbard model

One-orbital Hubbard ground state with a fixed particle-number sector.

Example to be added
Planned

t–J model

Projected-fermion ground state using the Model_1_orb_tJ implementation.

Example to be added

Worked example 01

Spin-model ground state

This example documents a complete spin-model calculation, from defining the Hamiltonian and lattice to checking the final ground-state energy. The exact input listing and commands will be filled using a tested SCS_Lanczos run.

1. Model route 2. Physical parameters 3. Input file 4. Run command 5. Expected output

Step 1

Define the spin model

Code implementationmodels/Model_Spins.*
HamiltonianTo be specified for this example
Lattice and sizeTo be specified
Boundary conditionTo be specified
Symmetry sectorTo be specified
The documentation will state all conventions explicitly, including site numbering, bond ordering, the sign and normalization of exchange couplings, and the selected spin sector.

Step 2

Prepare the input file

The tested input file will be reproduced here in full. Each active parameter will be explained directly below the listing.

# Spin-model input example
# A tested input file will be inserted here.

Parameters to document

Model selector
Number of sites
Spin or target Sz sector
Exchange connections and couplings
Lanczos convergence controls
Requested eigenvalues and eigenvectors

Step 3

Build and run

The exact compile target and executable invocation will be shown here after verifying the example against the current repository version.

# Build command
make

# Model-specific run command
# To be added from a tested run

Step 4

Read the output

The completed example will identify the lines reporting the Hilbert-space size, Lanczos iterations, convergence, ground-state energy, and saved eigenvector information.

Basis sizeConfirms the selected Hilbert space and symmetry sector.
IterationTracks convergence of the lowest Ritz value.
E0Ground-state energy for the chosen parameters.
Residual / toleranceConfirms numerical convergence.

Step 5

Validation checklist

  1. Confirm that the basis dimension matches the intended spin sector.
  2. Repeat with a tighter Lanczos tolerance and verify that the reported energy is stable.
  3. For a small lattice, compare with the full exact-diagonalization result.
  4. Check the energy against a known analytic limit or benchmark when available.
  5. Record the code revision, input file, and output together for reproducibility.

Next documentation step

Complete the tested Spin-model example

To replace the placeholders, we will add one working input file, the corresponding run command, and a short representative output from SCS_Lanczos.