Merge pull request #73 from michellab/feature-decouple-somd-3

Update README and docs with citation information.

Author: Roy-Haolin-Du

README.md

@@ -15,6 +15,22 @@ For details of the algorithms and testing, please see the assocated paper:
 
 **Clark, F.; Robb, G. R.; Cole, D. J.; Michel, J. Automated Adaptive Absolute Binding Free Energy Calculations. J. Chem. Theory Comput. 2024, 20 (18), 7806–7828. https://doi.org/10.1021/acs.jctc.4c00806.**
 
+### Citation
+
+If you use a3fe in your research, please cite:
+
+- **Software**: Clark, F., & Du, . (Haolin) R. (2025). a3fe: Automated Adaptive Absolute alchemical Free Energy calculator (0.4.0). Zenodo. https://doi.org/10.5281/zenodo.17298077.
+
+- **Paper**: Clark, F.; Robb, G. R.; Cole, D. J.; Michel, J. Automated Adaptive Absolute Binding Free Energy Calculations. J. Chem. Theory Comput. 2024, 20 (18), 7806–7828. https://doi.org/10.1021/acs.jctc.4c00806.
+
+Additionally, please cite the underlying software that makes a3fe possible:
+
+- **Sire**: Christopher J. Woods, Lester O. Hedges, Adrian J. Mulholland, Maturos Malaisree, Paolo Tosco, Hannes H. Loeffler, Miroslav Suruzhon, Matthew Burman, Sofia Bariami, Stefano Bosisio, Gaetano Calabro, Finlay Clark, Antonia S. J. S. Mey, Julien Michel; Sire: An interoperability engine for prototyping algorithms and exchanging information between molecular simulation programs. J. Chem. Phys. 28 May 2024; 160 (20): 202503. https://doi.org/10.1063/5.0200458
+
+- **BioSimSpace**:
+  - Hedges, L. O., Bariami, S., Burman, M., Clark, F., Cossins, B. P., Hardie, A., … Wu, Z. (2023). A Suite of Tutorials for the BioSimSpace Framework for Interoperable Biomolecular Simulation [Article v1.0]. Living Journal of Computational Molecular Science, 5(1), 2375. https://doi.org/10.33011/livecoms.5.1.2375
+  - Hedges et al., (2019). BioSimSpace: An interoperable Python framework for biomolecular simulation. Journal of Open Source Software, 4(43), 1831, https://doi.org/10.21105/joss.01831
+
 ### Installation
 
 a3fe depends on SLURM for scheduling jobs, and on GROMACS for running initial equilibration simulations. Please ensure that your have sourced your GMXRC or loaded your GROMACS module before proceeding with the installation. While we recommend installing with [mamba](https://mamba.readthedocs.io/en/latest/installation/mamba-installation.html), you can substitute `mamba` with `conda` in the following commands.

docs/getting_started.rst

@@ -1,6 +1,6 @@
 Getting Started
 ===============
-a3fe is a package for running alchemical absolute binding free energy calculations with SOMD (Sire / OpenMM Molecular Dynamics) through SLURM. 
+a3fe is a package for running alchemical absolute binding free energy calculations with SOMD (Sire / OpenMM Molecular Dynamics) through SLURM.
 It is based on Sire(https://sire.openbiosim.org/) and also uses BioSimSpace(https://biosimspace.openbiosim.org/) during the set-up stages. For a
 discussion of the algorithms used, please see (https://pubs.acs.org/doi/10.1021/acs.jctc.4c00806).
 
@@ -10,14 +10,14 @@ Please see the instructions in the github repo README (https://github.com/michel
 
 Quick Start
 ***********
-- Activate your a3fe conda environment 
+- Activate your a3fe conda environment
 - Create a base directory for the calculation and create an directory called ``input`` within this
 - Move your input files into the the input directory. For example, if you have parameterised AMBER-format input files, name these bound_param.rst7, bound_param.prm7, free_param.rst7, and free_param.prm7. **Ensure that the ligand is named LIG and is the first molecule in the system.** For more details see :ref:`Preparing Input for a3fe`. Alternatively, copy the pre-provided input from ``a3fe/a3fe/data/example_run_dir/input`` to your input directory.
 - In the calculation base directory, run the following python code, either through ipython or as a python script (you will likely want to run this with ``nohup``/ through tmux to ensure that the calculation is not killed when you lose connection). Running though ipython will let you interact with the calculation while it's running.
 
 .. code-block:: python
 
-    import a3fe as a3 
+    import a3fe as a3
     calc = a3.Calculation(ensemble_size=5) # Run with 5 independent replicates and default engine is SOMD
     calc.setup()
     calc.get_optimal_lam_vals()
@@ -51,16 +51,16 @@ Some handy commands and code snippets, assuming that you have set up the calcula
 
 .. code-block:: python
 
-    print(f"Total GPU hours: {calc.tot_gpu_time:0.f}")
+    print(f"Total GPU hours: {calc.tot_gpu_time:0.2f}")
     print("#"*10)
     for leg in calc.legs:
-        print(f"Total GPU hours for leg {leg.leg_type}: {leg.tot_gpu_time:.0f}")
+        print(f"Total GPU hours for leg {leg.leg_type}: {leg.tot_gpu_time:.2f}")
 
 **Get a detailed summary of free energy components as a pandas dataframe**:
 
 .. code-block:: python
 
-    df = calc.get_summary_df()
+    df = calc.get_results_df()
     print(df)
 
 **Save the current state of the calculation**: