Add default output directory

docs/source/user_guide/command_line.rst

@@ -53,36 +53,38 @@ prints the following:
 
     Usage: janus singlepoint [OPTIONS]
 
-      Perform single point calculations and save to file.
-
-    Options:
-      --struct PATH        Path of structure to simulate.  [required]
-      --arch TEXT          MLIP architecture to use for calculations.  [default:
-                           mace_mp]
-      --device TEXT        Device to run calculations on.  [default: cpu]
-      --model-path TEXT    Path to MLIP model.  [default: None]
-      --properties TEXT    Properties to calculate. If not specified, 'energy',
-                       'forces' and 'stress' will be returned.
-      --out PATH           Path to save structure with calculated results. Default
-                           is inferred from name of structure file.
-      --read-kwargs DICT   Keyword arguments to pass to ase.io.read. Must be
-                           passed as a dictionary wrapped in quotes, e.g. "{'key'
-                           : value}".  [default: "{}"]
-      --calc-kwargs DICT   Keyword arguments to pass to selected calculator. Must
-                           be passed as a dictionary wrapped in quotes, e.g.
-                           "{'key' : value}". For the default architecture
-                           ('mace_mp'), "{'model':'small'}" is set unless
-                           overwritten.
-      --write-kwargs DICT  Keyword arguments to pass to ase.io.write when saving
-                           results. Must be passed as a dictionary wrapped in
-                           quotes, e.g. "{'key' : value}".  [default: "{}"]
-      --log PATH           Path to save logs to. Default is inferred from the name
-                           of the structure file.
-      --summary PATH       Path to save summary of inputs, start/end time, and
-                           carbon emissions. Default is inferred from the name of
-                           the structure file.
-      --config TEXT        Configuration file.
-      --help               Show this message and exit.
+    Perform single point calculations and save to file.
+
+       Options:
+      *  --struct                          PATH  Path of structure to simulate. [default: None] [required]
+         --arch                            TEXT  MLIP architecture to use for calculations. [default: mace_mp]
+         --device                          TEXT  Device to run calculations on. [default:]
+         --model-path                      TEXT  Path to MLIP model. [default: None]
+         --properties                      TEXT  Properties to calculate. If not specified, 'energy', 'forces' and
+                                                 'stress' will be returned. [default: None]
+         --file-prefix                     PATH  Prefix for output files, including directories. Default directory is
+                                                 ./janus_results, and default filename prefix is inferred from the
+                                                 input stucture filename.
+         --out                             PATH  Path to save structure with calculated results. Default is inferred
+                                                 from name of structure file. [default: None]
+         --read-kwargs                     DICT  Keyword arguments to pass to ase.io.read. Must be passed as a
+                                                 dictionary wrapped in quotes, e.g. "{'key': value}".
+                                                 By default, read_kwargs['index'] = ':', so all structures are read.
+                                                 [default: None]
+         --calc-kwargs                     DICT  Keyword arguments to pass to selected calculator. Must be passed as a
+                                                 dictionary wrapped in quotes, e.g. "{'key': value}".
+                                                 For the default architecture ('mace_mp'), "{'model': 'small'}" is set
+                                                 unless overwritten. [default: None]
+         --write-kwargs                    DICT  Keyword arguments to pass to ase.io.write when saving results. Must be
+                                                 passed as a dictionary wrapped in quotes, e.g. "{'key': value}".
+                                                 [default: None]
+         --log                             PATH  Path to save logs to. Default is inferred from the name of the
+                                                 structure file. [default: None]
+         --tracker         --no-tracker          Whether to save carbon emissions of calculation [default: tracker]
+         --summary                         PATH  Path to save summary of inputs, start/end time, and carbon emissions.
+                                                 Default is inferred from the name of the structure file. [default: None]
+         --config                          TEXT  Configuration file.
+         --help                                  Show this message and exit.
 
 
 Using configuration files
@@ -122,6 +124,30 @@ Example configurations for all commands can be found in `janus-tutorials <https:
 Output files
 ------------
 
+Filenames
++++++++++
+
+The names and locations of output files from calculations are controlled by ``--file-prefix``.
+By default, files will be saved to the ``./janus_results`` directory, creating it if is does not already exist.
+
+The prefix for files saved within this directory defaults to the name of the input structure file.
+For example, an input structure from ``NaCl.cif`` will lead to results being saved in ``./janus_results/NaCl-[suffix]``,
+where suffix depends on the output file.
+
+If both ``--file-prefix`` and a specific output file are specified, the latter will take precedence. For example:
+
+.. code-block:: bash
+
+    janus singlepoint --struct tests/data/NaCl.cif --arch mace_mp --out results/NaCl.extxyz --file-prefix other_results/NaCl
+
+
+will save the main output file to ``./results/NaCl.extxyz``, but the summary and log files to
+``./other_results/NaCl-singlepoint-log.yml`` and ``./other_results/NaCl-singlepoint-summary.yml``.
+
+
+Data saved
+++++++++++
+
 By default, calculations performed will modify the underlying `ase.Atoms <https://wiki.fysik.dtu.dk/ase/ase/atoms.html>`_ object
 to store information in the ``Atoms.info`` and ``Atoms.arrays`` dictionaries about the MLIP used.
 

janus_core/calculations/descriptors.py

@@ -36,6 +36,8 @@ class Descriptors(BaseCalculation):
         Device to run MLIP model on. Default is "cpu".
     model_path
         Path to MLIP model. Default is `None`.
+    file_prefix
+        Prefix for output filenames. Default is inferred from structure.
     read_kwargs
         Keyword arguments to pass to ase.io.read. By default,
         read_kwargs["index"] is -1.
@@ -72,6 +74,7 @@ def __init__(
         arch: Architectures = "mace_mp",
         device: Devices = "cpu",
         model_path: PathLike | None = None,
+        file_prefix: PathLike | None = None,
         read_kwargs: ASEReadArgs | None = None,
         calc_kwargs: dict[str, Any] | None = None,
         set_calc: bool | None = None,
@@ -98,6 +101,8 @@ def __init__(
             Device to run MLIP model on. Default is "cpu".
         model_path
             Path to MLIP model. Default is `None`.
+        file_prefix
+            Prefix for output filenames. Default is inferred from structure.
         read_kwargs
             Keyword arguments to pass to ase.io.read. By default,
             read_kwargs["index"] is -1.
@@ -153,6 +158,7 @@ def __init__(
             log_kwargs=log_kwargs,
             track_carbon=track_carbon,
             tracker_kwargs=tracker_kwargs,
+            file_prefix=file_prefix,
         )
 
         if isinstance(self.struct, Atoms) and not self.struct.calc:

janus_core/cli/descriptors.py

@@ -12,6 +12,7 @@
     Architecture,
     CalcKwargs,
     Device,
+    FilePrefix,
     LogPath,
     ModelPath,
     ReadKwargsAll,
@@ -45,6 +46,7 @@ def descriptors(
     arch: Architecture = "mace_mp",
     device: Device = "cpu",
     model_path: ModelPath = None,
+    file_prefix: FilePrefix = None,
     out: Annotated[
         Path | None,
         Option(
@@ -85,9 +87,13 @@ def descriptors(
         Device to run model on. Default is "cpu".
     model_path
         Path to MLIP model. Default is `None`.
+    file_prefix
+        Prefix for output files, including directories. Default directory is
+        ./janus_results, and default filename prefix is inferred from the input
+        stucture filename.
     out
-        Path to save structure with calculated results. Default is inferred from name
-        of the structure file.
+        Path to save structure with calculated results. Default is inferred
+        `file_prefix`.
     read_kwargs
         Keyword arguments to pass to ase.io.read. By default,
             read_kwargs["index"] is ":".
@@ -96,13 +102,13 @@ def descriptors(
     write_kwargs
         Keyword arguments to pass to ase.io.write when saving results. Default is {}.
     log
-        Path to write logs to. Default is inferred from the name of the structure file.
+        Path to write logs to. Default is inferred from `file_prefix`.
     tracker
         Whether to save carbon emissions of calculation in log file and summary.
         Default is True.
     summary
         Path to save summary of inputs, start/end time, and carbon emissions. Default
-        is inferred from the name of the structure file.
+        is inferred from `file_prefix`.
     config
         Path to yaml configuration file to define the above options. Default is None.
     """
@@ -151,6 +157,7 @@ def descriptors(
         "calc_per_atom": calc_per_atom,
         "write_results": True,
         "write_kwargs": write_kwargs,
+        "file_prefix": file_prefix,
     }
 
     # Initialise descriptors

janus_core/cli/eos.py

@@ -2,7 +2,6 @@
 
 from __future__ import annotations
 
-from pathlib import Path
 from typing import Annotated, get_args
 
 from typer import Context, Option, Typer
@@ -12,6 +11,7 @@
     Architecture,
     CalcKwargs,
     Device,
+    FilePrefix,
     LogPath,
     MinimizeKwargs,
     ModelPath,
@@ -62,17 +62,7 @@ def eos(
     model_path: ModelPath = None,
     read_kwargs: ReadKwargsLast = None,
     calc_kwargs: CalcKwargs = None,
-    file_prefix: Annotated[
-        Path | None,
-        Option(
-            help=(
-                """
-                Prefix for output filenames. Default is inferred from structure name,
-                or chemical formula.
-                """
-            ),
-        ),
-    ] = None,
+    file_prefix: FilePrefix = None,
     log: LogPath = None,
     tracker: Annotated[
         bool, Option(help="Whether to save carbon emissions of calculation")
@@ -125,16 +115,17 @@ def eos(
     calc_kwargs
         Keyword arguments to pass to the selected calculator. Default is {}.
     file_prefix
-        Prefix for output filenames. Default is inferred from structure name, or
-        chemical formula.
+        Prefix for output files, including directories. Default directory is
+        ./janus_results, and default filename prefix is inferred from the input
+        stucture filename.
     log
-        Path to write logs to. Default is inferred from the name of the structure file.
+        Path to write logs to. Default is inferred from `file_prefix`.
     tracker
         Whether to save carbon emissions of calculation in log file and summary.
         Default is True.
     summary
         Path to save summary of inputs, start/end time, and carbon emissions. Default
-        is inferred from the name of the structure file.
+        is inferred from `file_prefix`.
     config
         Path to yaml configuration file to define the above options. Default is None.
     """

janus_core/cli/geomopt.py

@@ -12,6 +12,7 @@
     Architecture,
     CalcKwargs,
     Device,
+    FilePrefix,
     LogPath,
     MinimizeKwargs,
     ModelPath,
@@ -115,16 +116,12 @@ def geomopt(
             help="Atom displacement tolerance for spglib symmetry determination, in Å."
         ),
     ] = 0.001,
-    file_prefix: Annotated[
-        Path | None,
-        Option(help="Prefix for output filenames. Default is inferred from structure."),
-    ] = None,
+    file_prefix: FilePrefix = None,
     out: Annotated[
         Path | None,
         Option(
             help=(
-                "Path to save optimized structure. Default is inferred from name "
-                "of structure file."
+                "Path to save optimized structure. Default is inferred `file_prefix`."
             ),
         ),
     ] = None,
@@ -190,10 +187,12 @@ def geomopt(
         Atom displacement tolerance for spglib symmetry determination, in Å.
         Default is 0.001.
     file_prefix
-        Prefix for output filenames. Default is inferred from structure.
+        Prefix for output files, including directories. Default directory is
+        ./janus_results, and default filename prefix is inferred from the input
+        stucture filename.
     out
         Path to save optimized structure, or last structure if optimization did not
-        converge. Default is inferred from name of structure file.
+        converge. Default is inferred from `file_prefix`.
     write_traj
         Whether to save a trajectory file of optimization frames.
         If traj_kwargs["filename"] is not specified, it is inferred from `file_prefix`.
@@ -208,13 +207,13 @@ def geomopt(
         Keyword arguments to pass to ase.io.write when saving optimized structure.
         Default is {}.
     log
-        Path to write logs to. Default is inferred from the name of the structure file.
+        Path to write logs to. Default is inferred from `file_prefix`.
     tracker
         Whether to save carbon emissions of calculation in log file and summary.
         Default is True.
     summary
         Path to save summary of inputs, start/end time, and carbon emissions. Default
-        is inferred from the name of the structure file.
+        is inferred from `file_prefix`.
     config
         Path to yaml configuration file to define the above options. Default is None.
     """

janus_core/cli/md.py

@@ -13,6 +13,7 @@
     CalcKwargs,
     Device,
     EnsembleKwargs,
+    FilePrefix,
     LogPath,
     MinimizeKwargs,
     ModelPath,
@@ -131,17 +132,7 @@ def md(
     rescale_every: Annotated[
         int, Option(help="Frequency to rescale velocities during equilibration.")
     ] = 10,
-    file_prefix: Annotated[
-        Path | None,
-        Option(
-            help=(
-                """
-                Prefix for output filenames. Default is inferred from structure,
-                ensemble, and temperature.
-                """
-            ),
-        ),
-    ] = None,
+    file_prefix: FilePrefix = None,
     restart: Annotated[bool, Option(help="Whether restarting dynamics.")] = False,
     restart_auto: Annotated[
         bool, Option(help="Whether to infer restart file if restarting dynamics.")
@@ -289,8 +280,9 @@ def md(
     rescale_every
         Frequency to rescale velocities. Default is 10.
     file_prefix
-        Prefix for output filenames. Default is inferred from structure, ensemble,
-        and temperature.
+        Prefix for output files, including directories. Default directory is
+        ./janus_results, and default filename prefix is inferred from the input
+        stucture filename.
     restart
         Whether restarting dynamics. Default is False.
     restart_auto
@@ -339,13 +331,13 @@ def md(
         Random seed used by numpy.random and random functions, such as in Langevin.
         Default is None.
     log
-        Path to write logs to. Default is inferred from the name of the structure file.
+        Path to write logs to. Default is inferred from `file_prefix`.
     tracker
         Whether to save carbon emissions of calculation in log file and summary.
         Default is True.
     summary
         Path to save summary of inputs, start/end time, and carbon emissions. Default
-        is inferred from the name of the structure file.
+        is inferred from `file_prefix`.
     config
         Path to yaml configuration file to define the above options. Default is None.
     """