How to Read log.txt

This chapter explains how to inspect and interpret log.txt generated by Material-MC.

Where log.txt comes from

The main program creates and writes log.txt on rank 0:

  • src/MMC.cpp opens log.txt at startup.

  • After input/structure parsing and initialization, it writes status and model summaries.

  • After simulation completion, it writes final success messages.

What you should check first

A healthy run usually contains these milestones:

  • Successfully process input file.

  • Successfully initialize the supercell.

  • Successfully run Monte Carlo simulation.

  • Successfully output all results.

If one of these lines is missing, the run likely stopped before that phase.

Main sections in log.txt

Lattice constants

Printed under:

  • Lattice constants:

Three rows are the lattice vectors a, b, and c. Verify they match your POSCAR expectation.

Monte Carlo method

Printed under:

  • Monte Carlo Method: Classical Monte Carlo.

  • or Monte Carlo Method: Parallel Tempering Monte Carlo.

This confirms which algorithm was actually selected from input.toml.

Model type

Printed under:

  • Model Type: Heisenberg model.

  • or Model Type: Ising model.

  • or Model Type: Kitaev-Heisenberg model.

This confirms the local update model family.

If KH model is selected, you should also see:

  • KH global couplings (J, K, G, Gp): ...

  • KH bond type mapping (type1, type2, type3): ...

Use the coupling line to verify that optional J/K/G/Gp values were parsed as expected (omitted fields should appear as 0.00000), and use the mapping line to confirm the parsed [Hamiltonian.BondTypeDirection] assignment applied to geometric bond types.

Hamiltonian summary

The log prints both:

  • a Hamiltonian category line

  • a formula line (symbolic)

This helps verify whether field/anisotropy/custom settings were mapped to the expected runtime Hamiltonian.

Anisotropy and magnetic field

Printed as vectors:

  • Anisotropy: ...

  • Magnetic field (meV/spin): ...

Use this to confirm values parsed from input.toml.

Cell information (per element)

For each base-site element, log includes:

  • element name and spin magnitude

  • anisotropic ratio

  • super-exchange parameters by shell

  • coordination numbers by shell

This section is the most useful sanity check for neighbor-shell configuration.

Typical troubleshooting workflow

  1. Confirm all four success milestone lines exist.

  2. Check Monte Carlo Method and Model Type against input.toml.

  3. Check Anisotropy and Magnetic field values for unit/typing mistakes.

  4. In Cell information, verify:

    • shell count is expected,

    • exchange parameters are in correct order,

    • coordination numbers are physically reasonable.

  5. If results look wrong, compare log.txt with your edited input.toml before rerunning.

Quick command examples

From project root:

# Print full log
cat log.txt

# Jump to cell-information section
grep -n "Cell information" log.txt

# Check method/model lines quickly
grep -n "Monte Carlo Method\|Model Type" log.txt

KH validation checklist (lightweight and reproducible)

Use this checklist with example/kh_minimal/ to sanity-check KH setup end-to-end.

Recommended run (from project root):

mpirun -np 1 ./build/MMC -c example/kh_minimal/POSCAR -i example/kh_minimal/input.toml -o kh_validation_output.txt -s kh_validation_spin

Checkpoint A: bond-direction parsing sanity

Confirm KH-specific parser outputs are present in log.txt:

  • Model Type: Kitaev-Heisenberg model.

  • KH global couplings (J, K, G, Gp): ...

  • KH bond type mapping (type1, type2, type3): x y z

For the bundled minimal sample, expected coupling line is:

  • KH global couplings (J, K, G, Gp):     -1.00000      2.00000      0.50000     -0.25000

Checkpoint B: Hamiltonian path invocation sanity

Confirm KH Hamiltonian dispatch line is present:

  • Hamiltonian: Kitaev-Heisenberg model (bond-dependent J/K/G/Gp terms).

This line verifies runtime is on KH energy path, not a Heisenberg fallback.

Checkpoint C: x/y/z color output sanity

For KH model runs, rank 0 writes:

  • structure_initialized_kh_bond_color.vesta

In that file, verify VECTT color lines follow KH direction convention:

  • x bonds -> 255 0 0 (red)

  • y bonds -> 0 255 0 (green)

  • z bonds -> 0 0 255 (blue)

Reproducibility checkpoint (same input -> same artifacts)

Run the same command twice and compare checksums:

shasum log.txt structure_initialized_kh_bond_color.vesta

For identical environment and inputs, checksums should match across reruns.