.devcontainer/cuda/Dockerfile

@@ -2,8 +2,7 @@ FROM nvidia/cuda:12.5.1-devel-ubuntu24.04
 LABEL NAME="sassena-docker-cuda" \
         VERSION="1.0" \
         DESCRIPTION="Docker image that contains all required dependencies to build Sassena with CPU+CUDA support."
-RUN apt-get update -y
-RUN DEBIAN_FRONTEND=noninteractive apt-get install -y tzdata
+RUN DEBIAN_FRONTEND=noninteractive apt-get update -y && apt-get install -y tzdata
 RUN apt-get install -y build-essential cmake zlib1g-dev libblas-dev libfftw3-dev libxml2-dev libhdf5-dev \
     wget mpi-default-dev liblapack-dev ninja-build doxygen sphinx-doc
 RUN apt-get install -y libspdlog-dev python3 python3-pip graphviz git python3-h5py python3-sphinx-rtd-theme pipx fuse

.gitlab-ci.yml

@@ -90,6 +90,9 @@ appimage-cpu-job: # Create an AppImage for Sassena (CPU only), upload it to the
   rules:
     - if: $CI_COMMIT_TAG
       when: manual
+  release:                               # See https://docs.gitlab.com/ee/ci/yaml/#release for available properties
+    tag_name: '$CI_COMMIT_TAG'
+    description: '$CI_COMMIT_TAG'
   image: $CI_REGISTRY/daphne4nfdi/sassena:latest
   script:
     - git submodule update --init --recursive

CITATION.cff

+cff-version: 1.2.0
+title: Sassena
+message: >-
+  If you use this software, please cite both the software
+  and the journal publication.
+type: software
+authors:
+  - given-names: Jose
+    family-names: Borreguero
+    orcid: 'https://orcid.org/0000-0002-0866-8158'
+  - given-names: Eduard
+    family-names: Bosch i Mustaros
+  - given-names: Sebastian
+    family-names: Busch
+    email: sebastian.busch@hereon.de
+    orcid: 'https://orcid.org/0000-0002-9815-909X'
+  - given-names: Stuart
+    family-names: Campbell
+    orcid: 'https://orcid.org/0000-0001-7079-0878'
+  - given-names: Victor
+    family-names: Escuerdo
+  - given-names: Benjamin
+    family-names: Lindner
+  - given-names: Arnab
+    family-names: Majumdar
+    orcid: 'https://orcid.org/0000-0003-4049-4060'
+  - given-names: Berta
+    family-names: Pedret Sagnier
+    orcid: 'https://orcid.org/0009-0009-4718-2212'
+  - given-names: Xavier
+    family-names: Povill
+  - given-names: Jeremy C.
+    family-names: Smith
+    orcid: 'https://orcid.org/0000-0002-2978-3227'
+  - given-names: Daniel
+    family-names: Vonk
+    orcid: 'https://orcid.org/0000-0003-0837-9185'
+identifiers:
+  - type: url
+    value: 'https://codebase.helmholtz.cloud/DAPHNE4NFDI/sassena'
+    description: Code repository
+repository-code: 'https://codebase.helmholtz.cloud/DAPHNE4NFDI/sassena'
+abstract: >-
+  Sassena is a program to calculate X-ray and neutron
+  scattering patterns from Molecular Dynamic simulations in
+  the Born approximation.
+license: GPL-3.0
+references:
+- type: article
+  authors:
+  - given-names: Benjamin
+    family-names: Lindner
+  - given-names: Jeremy C.
+    family-names: Smith
+  title: "Sassena -- X-ray and neutron scattering calculated from molecular dynamics trajectories using massively parallel computers"
+  year: 2012
+  journal: Computer Physics Communications
+  doi: 10.1016/j.cpc.2012.02.010

CONTRIBUTING.rst

+Contributing
+############
+
+Thank you for contributing to Sassena!
+
+Please follow the steps below to contribute to Sassena:
+
+* Create a new `issue <https://codebase.helmholtz.cloud/DAPHNE4NFDI/sassena/-/issues>`_ where you describe your intentions clearly and can gather feedback
+* Get the source code: ``git clone https://codebase.helmholtz.cloud/DAPHNE4NFDI/sassena.git``
+* Start from the development branch: ``git checkout develop``
+* Make sure your ``develop`` branch is up to date with the repo's: ``git pull origin develop --rebase``
+* Create a new feature branch from here with a descriptive name: ``git switch -c name`` where ``name`` could for example be ``fix/readme``
+* code away!
+   * ``git add`` the changed files you want to upload
+   * ``git commit`` with a meaningful message
+   * In your last commit of this series, include a `keyword <https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/using-keywords-in-issues-and-pull-requests>`_ to close your feature branch.
+* Upload your feature branch: ``git push origin HEAD``
+* Create a merge request of your feature branch into the ``develop`` branch
+
+From time to time, we will merge the ``develop`` branch into the ``main`` branch.

Dockerfile

@@ -2,8 +2,7 @@ FROM ubuntu:latest
 LABEL NAME="sassena-docker-no-cuda" \
         VERSION="1.0" \
         DESCRIPTION="Docker image that contains all required dependencies to build Sassena with CPU support."
-RUN apt-get update -y
-RUN DEBIAN_FRONTEND=noninteractive apt-get install -y tzdata
+RUN DEBIAN_FRONTEND=noninteractive apt-get update -y && apt-get install -y tzdata
 RUN apt-get install -y build-essential cmake zlib1g-dev libblas-dev libfftw3-dev libxml2-dev libhdf5-dev \
     wget mpi-default-dev liblapack-dev ninja-build doxygen sphinx-doc
 RUN apt-get install -y libspdlog-dev python3 python3-pip graphviz git python3-h5py python3-sphinx-rtd-theme pipx fuse

README

-NOTE: This is a fork of the upstream repo which hasn't been updated in a while.
-
-Software for Calculating Scattering Diagrams on Massively Parallel Computers
-
-please visit www.sassena.org for details.
-associated paper: http://dx.doi.org/10.1016/j.cpc.2012.02.010
-
-Content (from website)
-=======
-Sassena is a highly scalable parallelized software for calculating neutron and xray scattering intensities from all-atomic molecular dynamics simulations. It enables scientific scattering calculations only attainable through massively large parallel computers. The development of sassena is a consequence of the need to calculate scattering diagrams for systems with thousands of atoms and millions of time steps. These calculations require enormous computing power in the range of thousands of cores and up to terabytes of memory. As a side effect, the overall time for calculating scattering of small systems and short trajectories can be significantly reduced through the use of parallel computers.
-
-The direct computation of scattering diagrams based on (all-atomic) molecular dynamics trajectories allows reconciliation of simulations with experiment. Scattering diagrams also provide a powerful tool to investigate structural and dynamical properties of simulated molecular systems by reducing the amount of information into meaningful structural and dynamical fingerprints.
-
-Sassena was inspired by pre-existing software and integrates their capabilities:
-
-SASSIM (SASSIM: a method for calculating small-angle X-ray and neutron scattering and the associated molecular envelope from explicit-atom models of solvated proteins, F. Merzel and J. C. Smith, 2002, Acta Cryst.. D58, p. 242-249)
-SERENA (SERENA: a program for calculating X-ray diffuse scattering intensities from molecular dynamics trajectories, Micu A.M., Smith J.C., 1995, Computer Physics Communications, 91 (1-3), pp. 331-338.).
-nMoldyn 2, G R. Kneller, V Keiner, M Kneller and M Schiller, "nMoldyn, a program package for the calculation and analysis of neutron scattering spectra from MD simulations" Comp. Phys. Comm., vol. 91, (1995), 191-214., T Róg, K Murzyn, K Hinsen and G R. Kneller, "nMoldyn : A Program Package for a Neutron Scattering Oriented Analysis of Molecular Dynamics Simulations" J. Comp. Chem. no. 5, vol. 24, (2003), 657-667.
- 
-
-The design goal of the sassena software suite is to enable scientific scattering calculations which are only attainable through the use of massively parallel computers. However, the software also represents a great educational tool for investigating structural and dynamical properties of molecular systems. For this reason this websites contains a collection of tutorials, in-depth information and hosts the sassena user community.
-
-Though the focus of the software is scalability, work is underway to increase single-node performance and optimize IO access.
-
-The inaugural paper is online (http://dx.doi.org/10.1016/j.cpc.2012.02.010) and the source code is available free of charge and open source.
-
-If you use Sassena for your calculations please cite the following reference:
-
-B. Lindner and J.C. Smith, 2012, "Sassena — X-ray and neutron scattering calculated from molecular dynamics trajectories using massively parallel computers", Comp. Phys. Comm., Volume 183, Issue 7, Pages 1491–1501, http://dx.doi.org/10.1016/j.cpc.2012.02.010

README.rst

+=======
+Sassena
+=======
+
+Sassena is a program to calculate X-ray and neutron scattering patterns from
+Molecular Dynamics simulations in the Born approximation.
+
+Description
+===========
+
+The full documentation is currently hosted on
+https://daphne4nfdi.pages.hzdr.de/sassena (access restrictions apply).
+
+Sassena can calculate:
+
+* structure factor S(Q)
+* coherent intermediate scattering function I\ :sup:`coh`\ (Q,t)
+* incoherent intermediate scattering function I\ :sup:`inc`\ (Q,t)
+* elastic incoherent structure factor EISF(Q)
+
+Filetypes:
+
+* Sassena can read ``pdb`` files for atom type definition and ``dcd`` files
+  containg the trajectory. For trajectory conversion, use e.g. `VMD
+  <https://www.ks.uiuc.edu/Research/vmd/>`_.
+* The computation has to be defined by the user in an ``xml`` file
+* Sassena writes the output into an ``hdf`` file
+
+Orientational averages are calculated explicitly using a Monte Carlo scheme. It
+is possible to define subsets of atoms or frames that the computation should run
+on.
+
+Sassena has a command-line interface and can be run across many CPUs using MPI.
+
+Installation
+============
+
+You can choose to either use a pre-built binary of Sassena, which contains all
+the required libraries or build the project yourself from source. For more
+information, visit `the documentation <https://daphne4nfdi.pages.hzdr.de/sassena/for_users/index.html>`_.
+
+AppImage
+--------
+
+An `AppImage is provided
+<https://codebase.helmholtz.cloud/DAPHNE4NFDI/sassena/-/releases>`_ that can run
+on Linux (x64, without CUDA support) out of the box when executed (no installation needed). To use
+it, download the AppImage from the releases page, mark it as an executable and run it from the
+command-line:
+
+.. code-block:: bash
+
+   chmod +x Sassena.AppImage
+   ./Sassena.AppImage # --config scatter.xml etc.
+   # or to use mpi:
+   mpirun -n 16 ./Sassena.AppImage --config scatter.xml
+
+Compiling from Source
+---------------------
+For optimal performance (e.g. using target-specific registers, CUDA), Sassena
+can be compiled on the target machine, e.g. on Ubuntu 24.04:
+
+.. code-block:: bash
+
+   sudo apt install build-essential cmake ninja-build\
+    openmpi-bin libblas-dev liblapack-dev gfortran\
+    libxml2-dev libhdf5-dev zlib1g-dev libfftw3-dev\
+    libboost-all-dev libboost-regex-dev libboost-mpi-dev\
+    libboost-thread-dev libboost-serialization-dev libboost-system-dev\
+    libboost-filesystem-dev libboost-program-options-dev
+   git clone https://codebase.helmholtz.cloud/DAPHNE4NFDI/sassena.git
+   cd sassena
+   git submodule update --init --recursive
+   cmake --preset=rel-cpu --build # or rel-cuda if you want to build with CUDA
+
+
+Contributing
+============
+
+To contribute, please create a feature branch from the develop branch and add
+your changes and then create a merge request onto the `develop` branch. The repo
+uses `rebasing workflow
+<https://git-scm.com/book/en/v2/Git-Branching-Rebasing>`_, so you may need to
+rebase your changes onto the `develop` branch before the merge can be completed.
+
+For further information, please see ``CONTRIBUTING.rst``.
+
+
+Notable upstream repositories
+=============================
+
+https://github.com/camm/sassena
+
+https://github.com/benlabs/sassena
+
+Citation
+========
+
+If you use Sassena for your calculations please cite
+
+   Benjamin Lindner and Jeremy C. Smith: "Sassena — X-ray and neutron scattering calculated from molecular dynamics trajectories using massively parallel computers", Comp. Phys. Comm. 183/7 (2012) 1491, `DOI: 10.1016/j.cpc.2012.02.010 <http://dx.doi.org/10.1016/j.cpc.2012.02.010>`_

docs/for_devs/index.rst

@@ -5,7 +5,6 @@ For Developers
    :maxdepth: 2
    :caption: Contents
 
-   using
    configuring
    file_map
    ci

docs/for_devs/using.rst

-Using Sassena
-==================================
-
-Here we explain how to use sassena

docs/for_users/index.rst

-For Users
-============
+User Guide
+##########
 
-.. toctree::
-   :maxdepth: 2
-   :caption: Contents
 
-   using
+This page is designed to serve as a quick guide for users (who aren't
+developers) to compile and run Sassena.
+
+
+Installation
+************
+
+AppImage
+========
+
+An `AppImage is provided
+<https://codebase.helmholtz.cloud/DAPHNE4NFDI/sassena/-/releases>`_ that can run
+on Linux (x64, without CUDA support) out of the box when executed (no
+installation needed). To use it, download the AppImage from the releases page,
+mark it as an executable and run it from the command-line:
+
+.. code-block:: bash
+
+   chmod +x Sassena.AppImage
+   ./Sassena.AppImage # --config scatter.xml etc.
+   # or to use mpi:
+   mpirun -n 16 ./Sassena.AppImage --config scatter.xml
+
+Compiling from Source
+=====================
+
+If you want to target a specific instruction set (e.g. ARM) or want to use the
+CUDA implementation, compiling from source is needed.
+
+VSCode
+~~~~~~
+
+The easiest way to compile Sassena is by using VSCode's `Dev Containers
+<https://code.visualstudio.com/docs/devcontainers/containers>`_. This will
+automatically create a Docker container, configure the build and compile Sassena
+inside that container. This means that no additional dependencies (e.g. Boost)
+need to be installed on the system.
+
+To use VSCode's Dev Containers, you need to have *Docker* installed. For Linux,
+this means Docker Engine and Docker Compose. Please follow the installation
+guide for Docker `here <https://docs.docker.com/engine/install/>`_ and note that
+you must add your user to the `docker` group so that VSCode can create and run
+containers without sudo.
+
+If you want to also build with CUDA support, you must first make sure that your system has the
+NVIDIA drivers installed. Additionally, running CUDA applications inside of a
+Dev Container requires the installation of the `NVIDIA Container Toolkit
+<https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/install-guide.html>`_.
+Docker must be configured to use the NVIDIA Container toolkit, so make sure to
+follow the `configuration guide
+<https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/install-guide.html#configuring-docker>`_
+as well.
+
+You can then clone the project. Make sure to update the submodules as Sassena
+relies upon the header-only library `taskflow`, which is distributed as a
+submodule in the repo.
+
+.. code-block:: bash
+
+   git clone https://codebase.helmholtz.cloud/DAPHNE4NFDI/sassena.git
+   cd sassena
+   git submodule update --init --recursive
+
+Once you have the required dependencies, you can open the folder in VSCode and
+the editor will then ask whether you want to open the project in a container.
+You can select either the CPU or the CPU+CUDA container depending on your needs.
+If you don't get any prompt, you can follow the additional instructions in the
+`Dev Container Documentation
+<https://code.visualstudio.com/docs/devcontainers/attach-container>`_.
+
+Once VSCode has built the container, it should ask you to configure the project,
+which corresponds to the CMake configure step. If you only intend to run Sassena
+and not develop further, pick either "Release (CPU)" or "Release (CPU+CUDA)".
+You can then build the project using build button as normal or F7. Once it has
+been built, you can open a terminal in VSCode (Terminal > New Terminal) and a
+shell will appear pointing to the current build directory, where the sassena
+binaries should be visible.
+
+Other Editors
+~~~~~~~~~~~~~
+
+For optimal performance (e.g. using target-specific registers, CUDA), Sassena
+can be compiled on the target machine, e.g. on Ubuntu 24.04 without using any
+containers.
+
+The process is in essence the same as building with VSCode, though it requires
+manually configuring with CMake and compiling:
+
+.. code-block:: bash
+
+   sudo apt install build-essential cmake ninja-build\
+    openmpi-bin libblas-dev liblapack-dev gfortran\
+    libxml2-dev libhdf5-dev zlib1g-dev libfftw3-dev\
+    libboost-all-dev libboost-regex-dev libboost-mpi-dev\
+    libboost-thread-dev libboost-serialization-dev libboost-system-dev\
+    libboost-filesystem-dev libboost-program-options-dev
+   git clone https://codebase.helmholtz.cloud/DAPHNE4NFDI/sassena.git
+   cd sassena
+   git submodule update --init --recursive
+   cmake --preset=rel-cpu --build # or rel-cuda if you want to build with CUDA
+
+
+Running
+*******
+
+Waterdyn4 Test Project
+======================
+
+Once you have built Sassena, you may wish to try it on a sample project:
+
+.. code-block:: bash
+
+   cd tests/waterdyn4
+   ../../build-rel-cpu/bin/sassena --config scatter.xml
+
+The command-line output should look terminate with something like:
+
+.. code-block:: bash
+
+   [11:38:49 Rank 0] [info] Total runtime (s): 77.552289999999999
+   [11:38:49 Rank 0] [info] Successfully finished... Have a nice day!
+
+and will output to ``signal.h5`` by default.
+
+
+Running with CUDA
+=================
+
+Sassena has a new CUDA backend for self scattering, though it is only possible
+to use it if you have built the project from source and used the "Release
+(CPU+CUDA)" or "Dev (CPU+CUDA)" CMake preset. To try it, you can direct
+Sassena to use it in the ``scatter.xml`` file by adding the following lines inside
+the ``<scattering>`` tag:
+
+.. code-block:: xml
+
+   <device>
+       <type>cuda</type>
+       <atoms>100</atoms>
+   </device>
+
+The value in the ``<type>`` tag can be either ``cpu`` or ``cuda`` depending on
+the desired backend. If using CUDA, you can dictate how many atoms to calculate
+in parallel using the ``<atoms>`` tag. Note that this is subject to memory
+capacity on the GPU and will fail if the value is too high.
+
+Sassena can still be run with ``mpirun`` in the usual way when using the CUDA
+backend as only one process will claim the GPU.

docs/for_users/using.rst

-Using Sassena
-==================================
-
-Here we explain how to use sassena

docs/index.rst

 Sassena
 ===================
 
-Software for Calculating Scattering Diagrams on Massively Parallel Computers
+Sassena is a highly scalable parallelized software for calculating neutron and
+X-ray scattering intensities from all-atomic molecular dynamics simulations. It
+enables scientific scattering calculations only attainable through massively
+large parallel computers. The development of Sassena is a consequence of the
+need to calculate scattering diagrams for systems with thousands of atoms and
+millions of time steps. These calculations require enormous computing power in
+the range of thousands of cores and up to terabytes of memory. As a side effect,
+the overall time for calculating scattering of small systems and short
+trajectories can be significantly reduced through the use of parallel computers.
 
-please visit www.sassena.org for details.
-associated paper: http://dx.doi.org/10.1016/j.cpc.2012.02.010
 
-Sassena is a highly scalable parallelized software for calculating neutron and xray scattering intensities from all-atomic molecular dynamics simulations. It enables scientific scattering calculations only attainable through massively large parallel computers. The development of sassena is a consequence of the need to calculate scattering diagrams for systems with thousands of atoms and millions of time steps. These calculations require enormous computing power in the range of thousands of cores and up to terabytes of memory. As a side effect, the overall time for calculating scattering of small systems and short trajectories can be significantly reduced through the use of parallel computers.
-
-The direct computation of scattering diagrams based on (all-atomic) molecular dynamics trajectories allows reconciliation of simulations with experiment. Scattering diagrams also provide a powerful tool to investigate structural and dynamical properties of simulated molecular systems by reducing the amount of information into meaningful structural and dynamical fingerprints.
-
-Sassena was inspired by pre-existing software and integrates their capabilities:
-
-SASSIM (SASSIM: a method for calculating small-angle X-ray and neutron scattering and the associated molecular envelope from explicit-atom models of solvated proteins, F. Merzel and J. C. Smith, 2002, Acta Cryst.. D58, p. 242-249)
-SERENA (SERENA: a program for calculating X-ray diffuse scattering intensities from molecular dynamics trajectories, Micu A.M., Smith J.C., 1995, Computer Physics Communications, 91 (1-3), pp. 331-338.).
-nMoldyn 2, G R. Kneller, V Keiner, M Kneller and M Schiller, "nMoldyn, a program package for the calculation and analysis of neutron scattering spectra from MD simulations" Comp. Phys. Comm., vol. 91, (1995), 191-214., T Róg, K Murzyn, K Hinsen and G R. Kneller, "nMoldyn : A Program Package for a Neutron Scattering Oriented Analysis of Molecular Dynamics Simulations" J. Comp. Chem. no. 5, vol. 24, (2003), 657-667.
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents
 
+   for_users/index
+   for_devs/index
+   doxygen/html/index
 
-The design goal of the sassena software suite is to enable scientific scattering calculations which are only attainable through the use of massively parallel computers. However, the software also represents a great educational tool for investigating structural and dynamical properties of molecular systems. For this reason this websites contains a collection of tutorials, in-depth information and hosts the sassena user community.
+The direct computation of scattering diagrams based on (all-atomic) molecular
+dynamics trajectories allows reconciliation of simulations with experiment.
+Scattering diagrams also provide a powerful tool to investigate structural and
+dynamical properties of simulated molecular systems by reducing the amount of
+information into meaningful structural and dynamical fingerprints.
 
-Though the focus of the software is scalability, work is underway to increase single-node performance and optimize IO access.
+Sassena was inspired by pre-existing software and integrates their capabilities:
 
-The inaugural paper is online (http://dx.doi.org/10.1016/j.cpc.2012.02.010) and the source code is available free of charge and open source.
+* SASSIM (SASSIM: a method for calculating small-angle X-ray and neutron
+  scattering and the associated molecular envelope from explicit-atom models of
+  solvated proteins, F. Merzel and J. C. Smith, 2002, Acta Cryst.. D58, p.
+  242-249)
+* SERENA (SERENA: a program for calculating X-ray diffuse scattering
+  intensities from molecular dynamics trajectories, Micu A.M., Smith J.C., 1995,
+  Computer Physics Communications, 91 (1-3), pp. 331-338.).
+* nMoldyn 2, G R. Kneller, V Keiner, M Kneller and M Schiller, "nMoldyn, a program package for the
+  calculation and analysis of neutron scattering spectra from MD simulations"
+  Comp. Phys. Comm., vol. 91, (1995), 191-214., T Róg, K Murzyn, K Hinsen and G R.
+  Kneller, "nMoldyn : A Program Package for a Neutron Scattering Oriented Analysis
+  of Molecular Dynamics Simulations" J. Comp. Chem. no. 5, vol. 24, (2003),
+  657-667.
+
+The design goal of the Sassena software suite is to enable scientific scattering
+calculations which are only attainable through the use of massively parallel
+computers. However, the software also represents a great educational tool for
+investigating structural and dynamical properties of molecular systems. For this
+reason this websites contains a collection of tutorials, in-depth information
+and hosts the sassena user community.
+
+Though the focus of the software is scalability, work is underway to increase
+single-node performance and optimize IO access.
+
+The inaugural paper is online (http://dx.doi.org/10.1016/j.cpc.2012.02.010) and
+the source code is available free of charge and open source.
 
 If you use Sassena for your calculations please cite the following reference:
 
-B. Lindner and J.C. Smith, 2012, "Sassena — X-ray and neutron scattering calculated from molecular dynamics trajectories using massively parallel computers", Comp. Phys. Comm., Volume 183, Issue 7, Pages 1491–1501, http://dx.doi.org/10.1016/j.cpc.2012.02.010
+   B. Lindner and J.C. Smith, 2012, "Sassena — X-ray and neutron scattering calculated from molecular dynamics trajectories using massively parallel computers", Comp. Phys. Comm., Volume 183, Issue 7, Pages 1491–1501, http://dx.doi.org/10.1016/j.cpc.2012.02.010
 
-.. toctree::
-   :maxdepth: 2
-   :caption: Contents
-
-   doxygen/html/index
-   for_devs/index
-   for_users/index