Understanding Output Files
==========================

This chapter explains the files generated by Material-MC and how to read them.

Output summary
--------------

After a successful run, you will typically see:

- ``log.txt``: run status and parsed model summary (see also the dedicated log chapter)
- ``output.txt`` (or your ``-o`` filename): thermodynamic table vs temperature
- ``structure_initialized.xsf``: spin structure right after initialization
- ``structure_ground_state*.xsf``: ground-state spin structure (if enabled)

Where each file is written
--------------------------

- ``log.txt`` is opened in ``src/MMC.cpp`` on rank 0.
- The thermodynamic table is written by ``WriteOutput`` in ``src/result_out.cpp``.
- XSF spin files are written by ``WriteSpin`` in ``src/spin_out.cpp``.

Thermodynamic table (output.txt)
--------------------------------

Header and columns
~~~~~~~~~~~~~~~~~~

The table is tab-separated. The header is:

- without magnetic field: ``#T  Energy  Cv  Moment  chi``
- with magnetic field: ``#T  Energy  Cv  Moment  chi  Moment_B  chi_B``

Column meaning:

- ``T``: temperature point
- ``Energy``: average energy per spin (as computed in MC routines)
- ``Cv``: heat capacity
- ``Moment``: average magnetic moment per spin
- ``chi``: magnetic susceptibility
- ``Moment_B``: moment projected onto field direction (only when field is enabled)
- ``chi_B``: projected susceptibility (only when field is enabled)

Temperature order
~~~~~~~~~~~~~~~~~

- Classical MC: temperatures are distributed over MPI ranks and gathered back in index order.
- Parallel tempering: gathered values are reordered by temperature before writing.

So the output file is written in ascending temperature order in both methods.

Spin structure files (XSF)
--------------------------

``structure_initialized.xsf``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

This file is always written after supercell initialization. It contains:

- lattice vectors in ``PRIMVEC``
- all atom coordinates in ``PRIMCOORD``
- spin vector components for each site

Ground-state output files
~~~~~~~~~~~~~~~~~~~~~~~~~

If ``ground_state = true`` in ``[Output]``:

- Classical MC writes ``structure_ground_state<T>.xsf`` (temperature appended to filename).
- Parallel tempering writes ``structure_ground_state.xsf``.

Each row stores one site as:

``element  x  y  z  sx  sy  sz``

Quick checks after a run
------------------------

1. Confirm ``log.txt`` contains all success milestones.
2. Open ``output.txt`` and verify row count matches your temperature-point setting.
3. If field is enabled, confirm ``Moment_B`` and ``chi_B`` columns are present.
4. Open XSF files in a viewer (e.g., XCrySDen/VESTA-compatible workflows) to inspect spin textures.

Useful commands
---------------

From project root:

.. code-block:: bash

   # Preview thermodynamic table
   head -n 5 output.txt

   # Count data rows (excluding header)
   tail -n +2 output.txt | wc -l

   # Check generated XSF files
   ls -1 structure_*.xsf