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:

.. code-block:: bash

   # 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):

.. code-block:: bash

   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:

.. code-block:: bash

   shasum log.txt structure_initialized_kh_bond_color.vesta

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