Log a warning when the user sets a simfile option not present by default

Also update the docs on how to use set_simfile_option.

a3fe/read/_process_somd_files.py

@@ -1,5 +1,7 @@
 """Functionality to manipulate SOMD files."""
 
+from logging import Logger as _Logger
+from typing import Optional as _Optional
 from typing import Tuple as _Tuple
 from warnings import warn as _warn
 
@@ -31,7 +33,9 @@ def read_simfile_option(simfile: str, option: str) -> str:
     raise ValueError(f"Option {option} not found in simfile {simfile}")
 
 
-def write_simfile_option(simfile: str, option: str, value: str) -> None:
+def write_simfile_option(
+    simfile: str, option: str, value: str, logger: _Optional[_Logger] = None
+) -> None:
     """Write an option to a SOMD simfile.
 
     Parameters
@@ -42,6 +46,9 @@ def write_simfile_option(simfile: str, option: str, value: str) -> None:
         The option to write.
     value : str
         The value to write.
+    logger : Optional[Logger]
+        The logger to use for logging.
+
     Returns
     -------
     None
@@ -57,6 +64,10 @@ def write_simfile_option(simfile: str, option: str, value: str) -> None:
 
     # If the option is not present, append it to the end of the file
     if option_line_idx is None:
+        if logger is not None:
+            logger.warning(
+                f"Option {option} not found in simfile {simfile}. Appending new option to the end of the file."
+            )
         lines.append(f"{option} = {value}\n")
     # Otherwise, replace the line with the new value
     else:

a3fe/run/simulation.py

@@ -620,7 +620,7 @@ def update_paths(self, old_sub_path: str, new_sub_path: str) -> None:
 
     def set_simfile_option(self, option: str, value: str) -> None:
         """Set the value of an option in the simulation configuration file."""
-        _write_simfile_option(self.simfile_path, option, value)
+        _write_simfile_option(self.simfile_path, option, value, logger=self._logger)
 
     def analyse(self) -> None:
         raise NotImplementedError(

a3fe/run/stage.py

@@ -1143,7 +1143,7 @@ def _mv_output(self, save_name: str) -> None:
     def set_simfile_option(self, option: str, value: str) -> None:
         """Set the value of an option in the simulation configuration file."""
         simfile = _os.path.join(self.input_dir, "somd.cfg")
-        _write_simfile_option(simfile, option, value)
+        _write_simfile_option(simfile, option, value, logger=self._logger)
         super().set_simfile_option(option, value)
 
     def wait(self) -> None:

docs/guides.rst

@@ -122,8 +122,8 @@ Once you have the required files in `input` as described above, you can run a st
 We suggest running this through ipython (so that you can interact with the calculation while it is running) in a tmux session (so that the process
 is not killed when you log out).
 
-Customising Calculation Setup
-******************************
+Customising Calculations
+*************************
 
 Calculation setup options, including the force fields, lambda schedules, and length of the equilibration steps, can be customised using :class:`a3fe.run.system_prep.SystemPreparationConfig`.
 For example, to use GAFF2 instead of OFF2 for the small molecule, set this in the config object and pass this to ``calc.setup()``:
@@ -134,9 +134,11 @@ For example, to use GAFF2 instead of OFF2 for the small molecule, set this in th
     cfg.forcefields["ligand"] = "gaff2"
     calc_set.setup(bound_leg_sysprep_config = cfg, free_leg_sysprep_config = cfg)
 
-To customise specifics of how each lambda window is run (e.g. timestep), you can modify the ``template_config.cfg`` file in the input directory.
-To see a list of available options, run ``somd-freenrg --help-config``. If you have already set up your calculation, you will need to run ``calc.update_run_somd()``
-to update all simulation inputs with the new config file.
+To customise the specifics of how each lambda window is run (e.g. timestep), you can use the ``set_simfile_option`` method. For example, to set the timestep to 2 fs, run
+``calc.set_simfile_option("timestep", "2 * femtosecond")``. This will change parameters from the defaults given in ``template_config.cfg`` in the ``input`` directory, and warn
+you if you are trying to set a parameter that is not present in the template config file. To see a list of available options, run ``somd-freenrg --help-config``. Note that if you
+want to change any slurm options in ``run_somd.sh``, you should modify ``run_somd.sh`` in the the calculation ``input`` directory then run ``calc.update_run_somd()`` to update all
+``run_somd.sh`` files in the calculation.
 
 Running Fast Non-Adaptive Calculations
 ***************************************