Add SASA analysis (#399)

* added SASA analysis

* moved sasa.h from analysis.h to .cpp

* minor renaming

* added missing documentation of functions

* most changes based on review

* Add documentation and streming output

* Add sasa analysis to JSON schema

* Update git ignore

* Update manual

* CI fix

* Add sasa test

* Fix github run command

* Update CI

---------

Co-authored-by: jakub <jakub@athena.teokem.lu.se>
Co-authored-by: Mikael Lund <Mikael.lund@teokem.lu.se>
Co-authored-by: Mikael Lund <Mlund@mac.com>

.github/workflows/cmake.yml

@@ -37,13 +37,17 @@ jobs:
       # and build directories, but this is only available with CMake 3.13 and higher.  
       # The CMake binaries on the Github Actions machines are (as of this writing) 3.12
       # Force libc++ due to https://github.com/actions/runner-images/issues/8659
-      run: cmake $GITHUB_WORKSPACE -DCMAKE_BUILD_TYPE=$BUILD_TYPE -DENABLE_OPENMP=on -DENABLE_PYTHON=off -DENABLE_TBB=off -DCMAKE_CXX_FLAGS="-stdlib=libc++"
+      run: |
+        export LDFLAGS="-fuse-ld=lld"
+        cmake $GITHUB_WORKSPACE -DCMAKE_BUILD_TYPE=$BUILD_TYPE -DENABLE_OPENMP=on -DENABLE_PYTHON=off -DENABLE_TBB=off -DCMAKE_CXX_FLAGS="-stdlib=libc++"
 
     - name: Build
       working-directory: ${{github.workspace}}/build
       shell: bash
       # Execute the build.  You can specify a specific target with "--target <NAME>"
-      run: cmake --build . --config $BUILD_TYPE --target faunus -j 2
+      run: |
+        export LDFLAGS="-fuse-ld=lld"
+        cmake --build . --config $BUILD_TYPE --target faunus -j 2
 
     - name: Test
       working-directory: ${{github.workspace}}/build

.gitignore

@@ -9,7 +9,7 @@ include/
 examples/
 _deps/
 sids/
-
+docs/html/
 unittests.log
 a.out
 

docs/_docs/analysis.md

@@ -341,6 +341,29 @@ with gzip.open('distances.mtx.gz', 'rt') as f:
         print(np.sort(counts)) # cluster size distribution
 ~~~
 
+### Surface Area
+
+Calculates surface areas using different sample policies
+that selects by:
+
+1. atoms types (`atomic`)
+2. molecule types (`molecular`)
+3. atom types in specific molecules (`atoms_in_molecule`)
+
+In addition to the optional `file` streaming, a histogram of observed areas
+is filed to disk, `sasa_histogram.dat`.
+
+`sasa`         | Description
+-------------- | ---------------------------
+`nstep`        | Interval between samples
+`nskip=0`      | Number of initial steps excluded from the analysis
+`policy`       | Sample policy: `atomic`, `molecular`, `atoms_in_molecule`
+`molecule`     | Molecule name to sample if `molecular` or `atoms_in_molecule` policies
+`atom`         | Atom name to sample if `atomic` policy
+`atomlist`     | List of atom names if `atoms_in_molecule` policy
+`file`         | Optionally stream area for each `nstep` to file (`.dat|.dat.gz`)
+`radius=1.4`   | Probe radius (Å)
+
 ## Charge Properties
 
 ### Molecular Multipoles

docs/schema.yml

@@ -1106,6 +1106,35 @@ properties:
                     additionalProperties: false
                     type: object
 
+                sasa:
+                    type: object
+                    properties:
+                        nstep: {type: integer, description: "Interval between samples"}
+                        nskip: {type: integer, default: 0, description: "Initial steps to skip"}
+                        molecule:
+                            type: string
+                            description: "Molecule name to sample if `molecular` or `atoms_in_molecule` policies"
+                        atom: {type: string, description: "Atom to sample if `atomic` policy"}
+                        atomlist:
+                            type: array
+                            items: string
+                            minItems: 1
+                            description: "List of atom names if `atoms_in_molecule` policy"
+                        radius:
+                            type: number
+                            default: 1.4
+                            description: "Probe radius for SASA calculation (Å)"
+                        file:
+                            type: string
+                            pattern: "(.*?)\\.(dat|dat.gz)$"
+                            description: "Streaming filename (.dat|.dat.gz)"
+                        policy:
+                            type: string
+                            enum: ["atomic", "molecular", "atoms_in_molecule"]
+                            description: "Area calculation policy"
+                    required: [nstep, policy]
+                    additionalProperties: false
+
                 savestate:
                     description: "Save particle positions to file"
                     properties:

examples/CMakeLists.txt

@@ -136,6 +136,13 @@ add_test(
     && ${Python_EXECUTABLE} ${JSON_COMPARE} polymers.out.json out.json --tol 0.05"
         WORKING_DIRECTORY ${EXAMPLES_DIR}/polymers)
 
+add_test(
+        NAME sasa
+        COMMAND sh -c "${Python_EXECUTABLE} ${YASON} sasa.yml\
+    | $<TARGET_FILE:faunus> --quiet\
+    && ${Python_EXECUTABLE} ${JSON_COMPARE} sasa.out.json out.json --tol 0.01"
+        WORKING_DIRECTORY ${EXAMPLES_DIR}/sasa)
+
 add_test(
         NAME smartmc
         COMMAND sh -c "${Python_EXECUTABLE} ${YASON} smartmc.yml\

examples/sasa/sasa.out.json

@@ -0,0 +1,19 @@
+{
+  "analysis": [
+    {
+      "sasa": {
+        "molecule": "mymolecule",
+        "nstep": 1,
+        "radius": 2.0,
+        "reference": "doi:10/dbjh",
+        "relative time": 0.592,
+        "samples": 1,
+        "slices_per_atom": 20,
+        "⟨SASA²⟩-⟨SASA⟩²": 0.0,
+        "⟨SASA⟩": 2177.145143881812
+      }
+    }
+  ],
+  "compiler": "Apple LLVM 15.0.0 (clang-1500.0.40.1)",
+  "git revision": "71a2e177 (2023-11-29)"
+}

examples/sasa/sasa.yml

@@ -0,0 +1,29 @@
+#!/usr/bin/env yason.py
+
+temperature: 298.15
+geometry: {type: sphere, radius: 100}
+mcloop: {macro: 1, micro: 1}
+
+atomlist:
+    - bead: {sigma: 20.0, mw: 1} # bead with r=10 Å
+
+moleculelist:
+    - mymolecule:
+        structure:
+          - bead: [0.0, 0.0, 0.0]
+          - bead: [5.0, 0.0, 0.0]
+
+insertmolecules:
+    - mymolecule: {N: 1}
+
+energy: []
+moves: []
+
+analysis:
+    - sasa:
+        file: sasa.dat
+        policy: molecular
+        molecule: mymolecule
+        radius: 2.0
+        nstep: 1
+