Usage Guide
===========

Command Line Interface
----------------------

The quickest way to exercise the validation checks is through the
``kim-test-pm-lite`` command line interface. Provide the path to a KIM model
and the species you want to validate:

.. code-block:: bash

   kim-test-pm-lite /path/to/kim-model Ar

Use ``-v`` to surface informational messages, ``-vv`` to enable debug logging
with scalar results, and ``-vvv`` to additionally print array data such as
positions and forces. In verbose modes the intermediate quantities reported by
the checks are logged using Rich formatting:

.. code-block:: bash

   kim-test-pm-lite ./models/Sim_LJ_G  Ar Ne -v

Specific checks can be requested with ``--checks``. Multiple checks may be
provided by repeating the option:

.. code-block:: bash

   kim-test-pm-lite ./models/Sim_LJ_G --checks InversionSymmetryCheck

Add ``--archive`` to retain the temporary workspace archive, or specify an
explicit location with ``--archive-path /path/to/archive.tar.gz``.

Use ``-l logs/run.log`` (or ``--log-file``) to mirror the log stream to a file
while still rendering via Rich in the terminal.

CLI Option Reference
--------------------

.. list-table:: CLI options
   :widths: 25 55 20
   :header-rows: 1

   * - Option
     - Description
     - Default
   * - ``model_path``
     - Path to the model directory or archive (positional argument).
     - Required
   * - ``species``
     - One or more chemical symbols to exercise (positional argument).
     - Optional
   * - ``-c`` / ``--checks``
     - Select a subset of checks; repeat the option to list multiple entries.
     - All checks
   * - ``-s`` / ``--structure``
     - Reserved placeholder for supplying an extxyz structure.
     - ``None``
   * - ``-m`` / ``--model-name``
     - Override the model name detected from the workspace.
     - Auto-detected
   * - ``-l`` / ``--log-file``
     - Mirror the log output to the specified file.
     - ``None``
   * - ``-a`` / ``--archive``
     - Archive the temporary workspace to a timestamped ``.tar.gz``.
     - Disabled
   * - ``--archive-path``
     - Archive to the given path (implies ``--archive``).
     - ``None``
   * - ``-v`` / ``--verbose``
     - Increase verbosity: ``-v`` (info), ``-vv`` (debug scalars), ``-vvv`` (arrays).
     - ``0``
   * - ``--seed``
     - Seed NumPy's global RNG so randomised checks are reproducible.
     - ``None``
   * - ``--tolerances``
     - Apply canned tolerance profiles (``light``, ``intermediate``, ``tight``).
     - ``intermediate``
   * - ``-t`` / ``--tests``
     - Run property tests such as ``LatticeConstantTest`` (never enabled by default).
     - ``None``

Property Tests
--------------

Property tests emit quantitative results rather than pass/fail verdicts. They
are only executed when listed via ``-t``/``--tests``; if you provide tests, only
the explicitly requested checks are executed alongside them.

Currently available:

* ``LatticeConstantTest`` – Builds (or uses a provided) bulk structure, relaxes
  the cell, and reports the equilibrium lattice constant and total energy.

Example invocations:

.. code-block:: bash

   # Use an auto-generated bulk structure
   kim-test-pm-lite ./models/Sim_LJ_G Ar --tests LatticeConstantTest -vv

.. code-block:: bash

   # Reuse an external unit cell
   kim-test-pm-lite ./models/Sim_LJ_G Ar --tests LatticeConstantTest \
       --structure path/to/unitcell.extxyz

The :class:`MemoryLeakCheck <kim_test_pm_lite.checks.memory_leak.MemoryLeakCheck>`
relies on `Valgrind <https://valgrind.org/>`_ being available on ``PATH``.
When invoked, it writes the complete Valgrind report to
``MemoryLeakTest/valgrind_output.txt`` for inspection. The check is not
part of the default suite; enable it explicitly with ``--checks
MemoryLeakCheck`` when you need the additional coverage.

Example CLI Session
-------------------

Running selected checks
^^^^^^^^^^^^^^^^^^^^^^^

.. literalinclude:: ./out.log
   :language: none


Running tests
^^^^^^^^^^^^^

Generate a structure to run test on (optional, can you default element list too).

.. code-block:: bash

    python -c "from ase.build import bulk; from ase.io import write; write('ca.xyz', bulk('Ca', cubic=True))"

.. literalinclude:: ./out_test.log
    :language: none

Programmatic Interface
----------------------

Developers may run the checks from Python using
``kim_test_pm_lite.core.test_runner.run_tests``. The function accepts a path to the
model and returns the same result structure used by the CLI:

.. code-block:: python

   from pathlib import Path

   from kim_test_pm_lite.core.test_runner import run_tests

   results = run_tests(
       Path("./models/Sim_LJ_G"),
       checks_to_run_str=["InversionSymmetryCheck"],
       species_list=["Ar"],
   )

   summary = results["summary"]
   print(f"Overall status: {summary['status']}")

Reporting Utilities
-------------------

The :class:`kim_test_pm_lite.core.result_reporter.ResultReporter` helper renders
results in Rich tables and exports data to JSON, Markdown, or EDN formats.
Construct the reporter with a Rich console to reuse your application's output
styling:

.. code-block:: python

   from rich.console import Console

   from kim_test_pm_lite.core.result_reporter import ResultReporter

   reporter = ResultReporter(console=Console())
   reporter.print_summary(results)