dssimmons-codes · BaoKhanhMa · Mar 3, 2026 · Jun 25, 2026 · Jun 25, 2026 · Jun 25, 2026
diff --git a/.github/workflows/check-version.yml b/.github/workflows/check-version.yml
@@ -23,11 +23,13 @@ jobs:
         shell: bash
         run: |
           set -euo pipefail
+
           if ! git tag --list | grep -q .; then
             echo "No tags found; skipping check."
             echo "skip=true" >> "$GITHUB_OUTPUT"
             exit 0
           fi
+
           tag="$(git describe --tags --abbrev=0)"
           echo "Latest tag: $tag"
           echo "tag=$tag" >> "$GITHUB_OUTPUT"

diff --git a/Makefile b/Makefile
@@ -122,9 +122,6 @@ XDR_OBJS  := $(patsubst $(XDR_SRC_DIR)/%.c,$(BUILD_DIR)/xdr/%.o,$(XDR_CSRCS))
 # Some distros require -lm for math symbols used by xdrfile
 LDLIBS += -lm
 
-# Ensure dir exists
-$(shell mkdir -p $(BUILD_DIR)/xdr)
-
 # --- Source discovery (flat, only src/*.cpp) ---------------------------------
 SRCS := $(wildcard $(SRC_DIR)/*.cpp)
 
@@ -138,9 +135,6 @@ SRCS := $(filter-out $(EXCLUDE_SRCS),$(SRCS))
 OBJS := $(patsubst $(SRC_DIR)/%.cpp,$(BUILD_DIR)/%.o,$(SRCS))
 DEPS := $(OBJS:.o=.d)
 
-# Ensure build dirs exist
-$(shell mkdir -p $(BUILD_DIR))
-
 # --- Targets -----------------------------------------------------------------
 .PHONY: all clean distclean rebuild format lint help
 all: $(APP)
@@ -204,11 +198,13 @@ $(APP): $(OBJS) $(XDR_OBJS) $(VORO_OBJS) | qvectors voro
 # Compile C++: strictly src/<file>.cpp → build/<file>.o
 $(BUILD_DIR)/%.o: $(SRC_DIR)/%.cpp | $(VERSION_H)
 	@echo "  CXX     $<"
+	@mkdir -p $(dir $@)
 	$(CXX) $(CPPFLAGS) $(CXXFLAGS) -c $< -o $@
 
 # Compile C from xdrfile: third_party/xdrfile-1.1b/src/*.c → build/xdr/*.o
 $(BUILD_DIR)/xdr/%.o: $(XDR_SRC_DIR)/%.c
 	@echo "  CC      $<"
+	@mkdir -p $(dir $@)
 	$(CC) $(XDR_CFLAGS) -c $< -o $@
 
 ## Compile voro++: third_party/voro++-0.4.6/src/*.cc → build/voro/*.o (isolated includes)

diff --git a/Manual/isf.md b/Manual/isf.md
@@ -0,0 +1,31 @@
+<h1>isf</h1>
+<h2>function</h2>
+
+Calculates the full intermediate scattering function of the system via the Fourier transform of the density.
+
+<h2>Syntax</h2>
+
+```
+structure_factor <output file> <method> <symmetry> <plane> <timescheme> <minimum wavenumber index> <maximum wavenumber index>
+<target>
+<target 2> (if symmetry = asymmetric only)
+```
+
+`<method>` is either `auto` or `manual`. The `manual` functionality is not currently documented; employ auto.
+
+`<symmetry>` is either `symmetric` or `asymmetric`.
+If `symmetric`, the analysis calculates the structure factor between the set of particles specified in target and itself.
+If `asymmetric`, then a second target must be specified, and the partial structure factor describing correlations of `<target>` with only `<target 2>` is calculated.
+`<first frame>` and `<last frame>` are the indices of the limits on time spacings to be calculated.
+Options for ``<plane>`` are ``xyz``, ``xy``, ``xz``, ``yz``, ``x``, ``y``, and ``z``.
+This chooses which dimensions in k-space to include in the calculation of the intermediate scattering function.
+``xyz`` computes the full radial three dimensional isf, ``xy``, ``yz``, and ``xz`` calculate two-dimensional in-plane radial isf's, and ``x``, ``y``, and ``z`` compute one-dimensional isf's.
+``<max_length_scale>`` determines the longest distance which will be decomposed into inverse space.
+If a distance of 0 is given, the full box size is used.
+Any deviation from '0' will in general produce incorrect results for the structure factor, especially at low k.
+
+`<timescheme>` determines what times to loop over.
+If `timescheme` is -1, loop over all times.
+If `timescheme` is zero or positive, only use one time per block, with the value setting the time index offset from the beginning of the block.
+In most cases this should be set to either 0 or -1, with -1 giving improved statistical strength at the cost of much longer compute times.
+The level of improvement in statistical strength will depend on the timescale for structural decorrelation in comparison to the length of a trajectory block.
diff --git a/Manual/mean_displacement.md b/Manual/mean_displacement.md
@@ -1,5 +1,7 @@
 <h1>mean_displacement</h1>
 
+[![multi](https://img.shields.io/badge/Multithreaded-blue)](multithreading.md)
+
 Calculates the mean (not mean square) displacement vector of all particles as a function of time. When used with trajectory_bin_lists, particularly useful for extracting gradients in displacement of the system. Syntax is as follows.
 
 _mean\_displacement \<output file\>_

diff --git a/Manual/msd.md b/Manual/msd.md
@@ -1,4 +1,7 @@
 <h1>msd</h1>
+
+[![multi](https://img.shields.io/badge/Multithreaded-blue)](multithreading.md)
+
 <h2>Function</h2>
 
 Calculates mean square displacement, as follows.
@@ -14,3 +17,5 @@ _msd \<output file\>_
 _\<target\>_
 
 
+
+
diff --git a/Manual/msd_2d.md b/Manual/msd_2d.md
@@ -1,5 +1,7 @@
 <h1>msd_2d</h1>
 
+[![multi](https://img.shields.io/badge/Multithreaded-blue)](multithreading.md)
+
 <h2>Function</h2>
 
 Calculates mean square displacement in two dimensions

diff --git a/Manual/multithreading.md b/Manual/multithreading.md
@@ -0,0 +1,61 @@
+<h1>AMDAT Multithreading</h1>
+
+## Overview
+High-performance computing workflows can be computationally expensive, and molecular dynamics analysis is no exception. To accelerate selected analyses, AMDAT supports multithreading with OpenMP. The analyses that currently support multithreading are listed below.
+
+---
+| Analysis | Description | Maximum Speedup Tested (Compared to Serial) |
+|----------|-------------|------------------------|
+| [`md`](mean_displacement.md) | Calculate Mean Displacement | 7x |
+| [`msd`](msd.md) | Calculate Mean Square Displacement | 10x |
+| [`msd_2d`](msd_2d.md) | Calculate Mean Square Displacement for two-dimensional analysis | 9x |
+| [`isfs`](isfs.md) | Calculate Incoherent Scattering Function | 20x |
+| [`vhs`](vhs.md) | Calculate self part of Van Hove Function | 12x |
+| [`vhd`](vhd.md) | Calculate distinct part of Van Hove Function | 20x |
+| `baf` | Calculate Bond Autocorrelation Function | 15x |
+| [`ngp`](ngp.md) | Calculate Non Gaussian Parameter | 30x |
+| [`composition`](composition.md) | Calculate Composition | 7x |
+| [`rdf`](rdf.md) | Calculate Radial Distribution Function | 21x |
+| [`rnf`](rnf.md) | Calculate Radial Count | 23x |
+
+
+## Inconsistency in performance between analysis
+
+AMDAT is currently implemented with a highly object-oriented design and an array-of-structures (AoS) memory layout. Hence, data are organized in adjacent memory blocks, making them more prone to Cache Coherency issue. In parallel system, this conflict results in false-sharing, meaning different threads try to have writing access to one common cache line, despite aiming at independent memory location. To fix performance bottleneck, AMDAT uses padding to separate each memory location further from each other, reducing Cache Coherency conflicts. This approach, however, trades spatial locality from serial implementation for mitigated memory conflict in parallel tasks, making perfect speed-up realistically unachievable. Therefore, speed-ups are inconsistent between analyses due to the differences in how we store the data.
+
+## System Requirements
+
+To use multithreading effectively in AMDAT, make sure the following requirements are met:
+
+- Your system has a multi-core CPU
+- The OpenMP runtime is available in your environment (This is already handled by Conda)
+
+## Analysis Requirements
+
+Parallelism is introduced to reduce the runtime of time-based loops. 
+However, to avoid oversubscription and ensure efficient resource utilization, 
+the optimal number of threads is allocated can be given by:
+
+$$N_{\text{threads}} = \min\left(N_{\text{iterations}},\;N_{\text{CPUs}} \right).$$
+
+where:
+- $$\ N_{\text{CPUs}} \$$ is the maximum number of hardware threads (logical CPUs) available on the node.
+- $$\ N_{\text{iterations}} \$$ is the number of independent time-based iterations. In AMDAT's input files, it is highlighted as shown below:
+
+> system  
+> xyz_log  
+> ./testfiles/traj.xyz ./testfiles/log.lammps  
+> exponential **`70`** 77 1.05 0 0 .01  
+> polymer 50  
+>
+> ...
+
+## Usage
+
+Running AMDAT is very simple with conda build, because OpenMP is already preinstalled. The flag `-n` <Number_of_Threads> will allocate the desired number of parallel regions for your analysis.
+
+### Example with msd
+
+```bash
+./AMDAT -n 8 -i ./testfiles/msd.in
+
diff --git a/Manual/ngp.md b/Manual/ngp.md
@@ -1,5 +1,7 @@
 <h1>ngp</h1>
 
+[![multi](https://img.shields.io/badge/Multithreaded-blue)](multithreading.md)
+
 <h2>Function</h2>
 
 Calculates non-Gaussian parameter of the mean squared displacement.

diff --git a/Manual/overview.md b/Manual/overview.md
@@ -6,7 +6,7 @@ AMDAT can read multiple file formats produced by the LAMMPS molecular dynamics s
 
 A central feature of AMDAT is its ability to read in and analyze blocked, exponentially-spaced trajectories. This is essential for analysis for dynamics over many orders of magnitude in time. The handling of this is currently documented in the [input_files](input_file.md) documentation. Both the documentation and the underlying functionality for this are expected to be expanded in the near future.
 
-AMDAT includes no built-in tools for visualization of either trajectories or properties of trajectories. All results are output in a text-based form and must be viewed in another software (exe python, julia, excel, matlab,...). AMDAT does not include the ability to aggregate statistics acquired based on multiple simulations; this requires use of post-analysis software, such as python, julia, matlab, igor, excel, or similar. AMDAT presently does not include multithreading, although this capability is planned for introduction in a future update.
+AMDAT includes no built-in tools for visualization of either trajectories or properties of trajectories. All results are output in a text-based form and must be viewed in another software (exe python, julia, excel, matlab,...). AMDAT does not include the ability to aggregate statistics acquired based on multiple simulations; this requires use of post-analysis software, such as python, julia, matlab, igor, excel, or similar. AMDAT includes CPU multithreading for select analysis function; more information is provided below or at this link: [multithreading](multithreading.md).
 
 <h2>Making AMDAT</h2>
 
@@ -38,7 +38,7 @@ AMDAT is run from the command line, specifying the filename of a user [input fil
 
 `-n <# OF PROCESSORS>`
 
-Presently, no analysis methods allow for multithreading, so this option does nothing. Eventually, this will permit AMDAT to run some analyses on `<# OF PROCESSORS>` processing cores. Defaults to 1 if not given..
+This sets AMDAT to run certain analyses (those for which multithreading is enabled) on `<# OF PROCESSORS>` processing cores. Defaults to 1 if not given. Analysis tools with multithreading capabilities are identified by this flag in their documentation page: [![multi](https://img.shields.io/badge/Multithreaded-blue)](multithreading.md). Additional information and a full list of analysis tools with multithreading capabilities can be found at [multithreading](multithreading.md).
 
 `-c <CONSTANT NAME> <CONSTANT VALUE>`
 

diff --git a/Manual/radial_count.md b/Manual/radial_count.md
@@ -1,5 +1,8 @@
 <h1>radial_count</h1>
 
+[![multi](https://img.shields.io/badge/Multithreaded-blue)](multithreading.md)
+
+---
 Computes a non-normalized radial distribution function - essentially the mean number of particles in shells a distance $r$ to $r+\Delta r$ from a central particle. 
 
 Syntax is as follows.

diff --git a/Manual/rdf.md b/Manual/rdf.md
@@ -1,4 +1,7 @@
 <h1>rdf</h1> 
+
+[![multi](https://img.shields.io/badge/Multithreaded-blue)](multithreading.md)
+
 <h2>Function</h2>
 
 

diff --git a/Manual/trajectory_lists.md b/Manual/trajectory_lists.md
@@ -50,7 +50,7 @@ A large number of analysis tools target `trajectory_list` objects.
 | [`displacement_dist`](displacement_dist.md) | Computes the displacement of each particle at some time separation and reports a distribution | Tab demarcated data file. |
 | [`displacement_map`](displacement_map.md) | Generates maps of particle displacement magnitude and writes to pdb files with value beta specifying displacement.| PDB file |
 | [`incremental_mean_displacement`](incremental_mean_displacement.md) | Calculates mean displacement of particles as a function of time. | Tab demarcated data file. |
-| [`isf_list`](isf_list.md) | Calculate full intermediate scattering function | Tab demarkated data file |
+| [`isf`](isf.md) | Calculate full intermediate scattering function | Tab demarkated data file |
 | [`isfs`](isfs.md) | Calculates the self-part of the intermediate scattering function. | Tab demarkated data file |
 | [`mean_closest_distance`](mean_closest_distance.md) | Calculates the average distance between particles in two distinct `trajectory_list`s. | Tab demarkated data file |
 | [`mean_displacement`](mean_displacement.md) | Calculates the mean (not mean square) displacement vector of all particles as a function of time. | Tab demarcated data file |
@@ -81,7 +81,6 @@ A large number of analysis tools target `trajectory_list` objects.
 | `find_fast_fixedthreshold` | Finds fast particles based on displacements higher than some value. Likely to become deprecated in favor of valuelist approach. | new `trajectory_list` |
 | [`find_between`](find_between.md) | Finds particles with displacements in some value range. Likely to become deprecated in favor of valuelist approach. | new `trajectory_list` |
 | `gyration_radius` | Deprecated; to be removed. | - |
-| `isf` | Deprecated; to be removed. | - |
 | `radial_debye_waller` | Computes dwf as a function of distance from (0,0,0). Planned for deprecation.|
 | `vector_autocorrelation_function` | Computes autocorrelation function for a specified set of vectors. Essentially replaced by [`raf`](raf.md) [`multibody`](multibodies.md) functionality and planned for deprecation. | Tab-demarcated data file. |
 

diff --git a/Manual/vhd.md b/Manual/vhd.md
@@ -1,5 +1,7 @@
 <h1>vhd</h1>
 
+[![multi](https://img.shields.io/badge/Multithreaded-blue)](multithreading.md)
+
 <h2>Function</h2>
 
 Calculates distinct part of the Van Hove function. The distinct van Hove is by construction asymmetric, computed between two distinct sets of atoms $a$ and $b$ ($a$ and $b$ may be the same). When asymmetric, $a$ is the central particle in the $G(r,\Delta t)$ calculation and $b$ is the set of particles for which densities around the central particles are computed.

diff --git a/Manual/vhs.md b/Manual/vhs.md
@@ -1,5 +1,7 @@
 <h1>vhs</h1>
 
+[![multi](https://img.shields.io/badge/Multithreaded-blue)](multithreading.md)
+
 Calculates self-part of the Van Hove function.
 
 ```

diff --git a/README.md b/README.md
@@ -15,12 +15,12 @@ It provides a wide variety of high-performance analyses integral to molecular mo
 ## Why AMDAT (at a glance)
 
 * Fast, in-memory engine – load once, analyze many time delays without re-reading files.
-* Blocked exponential time spacing – efficient long-timescale dynamics across orders of magnitude.
-* Modular data abstractions – trajectory / neighbor / multibody / value lists compose into rich workflows.
-* Validated analyses –
-  * static and time-resolved structure factors,
-  * radial distribution functions,
-  * mean-square displacements,
+* Blocked [exponential time spacing](/Manual/time_scheme.md) – efficient long-timescale dynamics across orders of magnitude.
+* Modular data abstractions – [trajectory](Manual/trajectory_lists.md) / [neighbor](Manual/neighborlist.md) / [multibody](Manual/multibodies.md) / [value](Manual/value_list.md) lists compose into rich workflows.
+* Validated analyses such as -
+  * [static](Manual/structure_factor.md) and [time-resolved](Manual/isf_list.md) structure factors,
+  * [radial distribution functions](Manual/rdf.md),
+  * [mean-square displacements](Manual/msd.md),
   * neighbor correlations,
   * clustering, and more.
 * Plain-text outputs – easy post-processing in Python/Matlab/Excel/VMD/OVITO.
@@ -162,6 +162,9 @@ If you use AMDAT, please cite:
 
 > Kawak, Drayer, and Simmons, "AMDAT: An Open-Source Molecular Dynamics Analysis Toolkit for Supercooled Liquids, Glass-Forming Materials, and Complex Fluids". arXiv, 2026. DOI: [10.48550/arXiv.2602.05865](https://doi.org/10.48550/arXiv.2602.05865)
 
+and
+> https://arxiv.org/abs/2602.05865
+
 *Also see [CITATION.cff](CITATION.cff).*
 
 ## Authors & Maintainers

diff --git a/VERSION b/VERSION
@@ -1 +1 @@
-1.0.1
+1.1.0
diff --git a/src/analysis.h b/src/analysis.h
@@ -88,6 +88,7 @@ class Analysis
     virtual void listkernel(Trajectory*, int, int, int){cout<<"Error: Trajectory list targets not fully implemented for this analysis method.\n";};	//added by Michael?
     virtual void listkernel2(Trajectory*, Trajectory*, int, int, int){cout<<"Error: Trajectory list targets not fully implemented for this analysis method.\n";};	//listkernel for use only when two (nested) trajectory loops are needed.
     virtual void listkernel(Trajectory*){cout<<"Error: Trajectory list targets not fully implemented for this analysis method.\n";};
+    virtual void listkernel(Trajectory*,int){cout<<"Error: Trajectory list targets not fully implemented for this analysis method.\n";};
 
 
     /*System loop methods*/

diff --git a/src/analysis_onetime.cpp b/src/analysis_onetime.cpp
@@ -29,6 +29,7 @@ void Analysis_Onetime::analyze(Trajectory_List * t_list)
 
   if(time_scheme==-1)
   {
+    #pragma omp parallel for schedule(static) if(this->isThreadSafe())
     for (timeii=0; timeii<system->show_n_timesteps();timeii++)
     {
       timekernel(timeii);
@@ -40,6 +41,7 @@ void Analysis_Onetime::analyze(Trajectory_List * t_list)
   }
   else
   {
+    #pragma omp parallel for schedule(static) if(this->isThreadSafe())
     for (timeii=time_scheme; timeii<system->show_n_exponentials();timeii+=system->show_n_exponential_steps())
     {
       timekernel(timeii);
@@ -62,6 +64,7 @@ void Analysis_Onetime::analyze(Trajectory_List * t_list,Trajectory_List* t_list2
 
   if(time_scheme==-1)
   {
+    #pragma omp parallel for schedule(static) if(this->isThreadSafe())
     for (timeii=0; timeii<system->show_n_timesteps();timeii++)
     {
       timekernel2(timeii);
@@ -73,6 +76,7 @@ void Analysis_Onetime::analyze(Trajectory_List * t_list,Trajectory_List* t_list2
   }
   else
   {
+    #pragma omp parallel for schedule(static) if(this->isThreadSafe())
     for (timeii=time_scheme; timeii<system->show_n_exponentials();timeii+=system->show_n_exponential_steps())
     {
       timekernel2(timeii);