Update docs for running ml_peg

Author: ElliottKasoar

docs/source/developer_guide/running.rst

@@ -9,74 +9,118 @@ application.
 Calculations
 ------------
 
-Currently, all calculations should be launched using ``pytest``. This will help to
-automatically discover and run each test, handle intermediate errors, and control
-which tests are run based on our
-`custom markers <https://docs.pytest.org/en/7.1.x/example/markers.html>`_.
+All calculations can be launched using our ``ml_peg calc`` command-line command.
 
-ALl current tests can be launched using the
-`run_calcs.sh <https://github.com/ddmms/ml-peg/blob/main/run_calcs.sh>`_ script:
+Help for this command can be found by running ``ml_peg calc --help``:
 
 .. code-block:: bash
 
-    ./run_cals.sh
+    Usage: ml_peg calc [OPTIONS]
+
+    Run calculations
 
+    ╭─ Options ────────────────────────────────────────────────────────────────────────────────────────────────────────╮
+    │ --models                       TEXT  Comma-separated models to run calculations on. Default is all models.       │
+    │ --category                     TEXT  Category to run calculations for. Default is all categories. [default: *]   │
+    │ --test                         TEXT  Test to run calculations for. Default is all tests. [default: *]            │
+    │ --run-slow    --no-run-slow          Whether to run calculations labelled slow. [default: run-slow]              │
+    │ --verbose     --no-verbose           Whether to run pytest with verbose and stdout printed. [default: verbose]   │
+    │ --help                               Show this message and exit.                                                 │
+    ╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
 
-Individual tests or categories can be run using a similar command to the one in this
-script, such as:
+
+``ml_peg calc`` launches calculations using ``pytest``, and will automatically
+discover and run each test, handle intermediate errors, and control which tests are
+run based on our
+`custom markers <https://docs.pytest.org/en/7.1.x/example/markers.html>`_.
+
+For example, to run the ``S24`` test in the ``surfaces`` category, with the
+``mace_mp_0b3`` model, you could run:
 
 .. code-block:: bash
 
-    pytest -v ml_peg/calcs/surfaces/*/calc* -s --run-slow
+    ml_peg calc --category surfaces --test S24 --models mace_mp_0b3
+
 
+This is effectively equivalent to:
 
-This will run all calculations in the surfaces category, including any marked as ``slow``.
+.. code-block:: bash
+
+    .. code-block:: bash
+
+    pytest -vvv ml_peg/calcs/surfaces/S24/calc_S24.py --models mace_mp_0b3
 
 
 Analysis
 --------
 
-As with calculations, analysis of results should also be launched using ``pytest``,
-which can be done using the
-`run_analysis.sh <https://github.com/ddmms/ml-peg/blob/main/run_analysis.sh>`_ script:
+Similarly to calculations, analysis can be launched using our ``ml_peg analyse``
+command-line command.
+
+Help for this command can be found by running ``ml_peg analyse --help``:
 
 .. code-block:: bash
 
-    ./run_analysis.sh
+    Usage: ml_peg analyse [OPTIONS]
 
+    Run calculations
 
-Individual tests or categories can be also analysed similarly. For example:
+    ╭─ Options ──────────────────────────────────────────────────────────────────────────────────────────────────────╮
+    │ --models                      TEXT  Comma-separated models to run analysis for. Default is all models.         │
+    │ --category                    TEXT  Category to run analysis for. Default is all categories. [default: *]      │
+    │ --test                        TEXT  Test to run analysis for. Default is all tests. [default: *]               │
+    │ --verbose     --no-verbose          Whether to run pytest with verbose and stdout printed. [default: verbose]  │
+    │ --help                              Show this message and exit.                                                │
+    ╰────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
 
-.. code-block:: bash
 
-    pytest -v ml_peg/analysis/surfaces/*/analyse* -s
+``ml_peg analyse`` launches analysis using ``pytest``.
 
+For example, to run the ``OC157`` test in the
+``surfaces`` category, with the ``mace_mp_0b3`` and ``orb_v3_conservative_inf_omat__``
+models, you could run:
 
-Will analyse the results of calculations in the surfaces category.
+.. code-block:: bash
 
+    ml_peg analyse --category surfaces --test OC157 --models mace_mp_0b3,orb_v3_conservative_inf_omat__
 
-Application
------------
 
-Having run analysis, the app can now be launched by running the
-`run_app.py <https://github.com/ddmms/ml-peg/blob/main/run_app.py>`_ Python script:
+This is effectively equivalent to:
 
 .. code-block:: bash
 
-    python3 run_app.py
+    .. code-block:: bash
+
+    pytest -vvv ml_peg/analysis/surfaces/OC157/analyse_OC157.py --models mace_mp_0b3,orb_v3_conservative_inf_omat__
 
-.. tip::
 
-    ``uv run`` can be used in place of ``python3``, removing the need to activate a
-    virtual environment.
+Application
+-----------
 
+Having run analysis, the app can now be launched by running the ``ml_peg app``
+command-line command.
+
+Help for this command can be found by running ``ml_peg app --help``:
+
+.. code-block:: bash
 
-By default, this will make the app visiable at http://localhost:8050.
+    Usage: ml_peg app [OPTIONS]
 
-.. tip::
+    Run application
 
-    You can set the ``PORT`` environment variable to change the port used by Dash.
+    ╭─ Options ───────────────────────────────────────────────────────────────────────────────────────────────────╮
+    │ --models                    TEXT  Comma-separated models to build interactivity for. Default is all models. │
+    │ --category                  TEXT  Category to build app for. Default is all categories. [default: *]        │
+    │ --port                      TEXT  Port to run application on. [default: 8050]                               │
+    │ --debug       --no-debug          Whether to run with Dash debugging. [default: debug]                      │
+    │ --help                            Show this message and exit.                                               │
+    ╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
 
+.. note::
+
+    The ``models`` option for this command only influences building interactive
+    callbacks, and does not change whether the models are included in tables, scores,
+    or summaries,
 
 When launched, the app will attempt to automatically construct tables, figures, and
 interactive features, based on any importable test apps defined in ``ml_peg/apps/``.
@@ -86,3 +130,11 @@ be rendered for the test.
 
 If a test's table is also unable to be loaded, the test will not be added to the app,
 but the app builder should continue to attempt adding other tests.
+
+By default, the live app can then be accessed at http://localhost:8050.
+
+To run the app on a different port (e.g. 8060), and for only the NEBs category, run:
+
+.. code-block:: bash
+
+    ml_peg app --category nebs --port 8060