Merge pull request #13 from seatonullberg/dev

v0.4.0

CHANGELOG.md

@@ -5,6 +5,17 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.4.0] - 2021-02-10
+
+### Added
+
+* Support for multithreading with `rayon`.
+
+### Changed
+
+* Examples are now post-processed with separate Python scripts.
+* Renamed `velvet-convert` crate to `velvet-external-data`.
+
 ## [0.3.2] - 2020-12-19
 
 ### Fixed

Cargo.toml

@@ -1,10 +1,10 @@
 [package]
 name = "velvet"
-version = "0.3.2"
+version = "0.4.0"
 authors = ["Seaton Ullberg <[email protected]>"]
 edition = "2018"
 repository = "https://github.com/seatonullberg/velvet"
-description = "An experimental molecular dynamics engine with a focus on user-friendliness and extensibility."
+description = "Classical atomistic simulation engine with a focus on user-friendliness and extensibility"
 license = "MIT"
 keywords = [
     "chemistry",
@@ -20,21 +20,43 @@ categories = [
 [workspace]
 members = [
     "crates/cli",
-    "crates/convert",
     "crates/core",
+    "crates/external-data",
     "crates/test-utils",
 ]
 
 [dependencies]
 hdf5 = "0.7"
 hdf5-sys = "0.7"
-velvet-convert = { path = "crates/convert", version = "0.1.2" }
-velvet-core = { path = "crates/core", version = "0.3.3" }
+velvet-core = { path = "crates/core", version = "0.4.0" }
+velvet-external-data = { path = "crates/external-data", version = "0.1.0" }
 
 [dev-dependencies]
-log = "0.4"
-plotters = "0.3.0"
-pretty_env_logger = "0.4"
+approx = "0.4"
+criterion = "0.3"
+nalgebra = "0.23"
+ron = "0.6"
+test-utils = { path = "crates/test-utils" }
+
+[[bench]]
+name = "integrator-benchmarks"
+path = "benches/integrators.rs"
+harness = false
+
+[[bench]]
+name = "property-benchmarks"
+path = "benches/properties.rs"
+harness = false
+
+[[bench]]
+name = "thermostat-benchmarks"
+path = "benches/thermostats.rs"
+harness = false
+
+[[bench]]
+name = "pair-potential-benchmarks"
+path = "benches/potentials/pair.rs"
+harness = false
 
 [package.metadata.docs.rs]
 features = ["hdf5-sys/static", "hdf5-sys/zlib"]

README.md

@@ -1,30 +1,31 @@
-# :alembic: Velvet
+# Velvet
 [![Crates.io](https://img.shields.io/crates/v/velvet)](https://crates.io/crates/velvet)
 ![Crates.io](https://img.shields.io/crates/l/velvet)
 ![Crates.io](https://img.shields.io/crates/d/velvet)
 
-Velvet is a classical atomistic simulation engine with a focus on user-friendliness and portability - two features that I believe are not well represented in the current scientific software environment. This project is largely a learning exercise, but as development continues I hope to accomplish the following goals:
+Velvet is a classical atomistic simulation engine with a focus on user-friendliness and extensibility. This project is largely a learning exercise, but as development continues I hope to accomplish the following goals:
 
 * Extensibility via user-defined plugin modules
 * Optimized single CPU performace with multithreading and SIMD support
 * Implement a wide variety of interatomic potentials
 * Molecular Dynamics, Monte Carlo, and Minimization routines
 * Visualization tools to analyze simulation results
+* Support importing and exporting data in popular external formats
 
 ## Getting Started
 
 ### Prerequisites
 
-To build Velvet you will need to have Rust's compiler and package manager installed on your machine. Instructions for most platforms can be found [here](https://www.rust-lang.org/tools/install).
-
-* [rustc](https://doc.rust-lang.org/rustc/what-is-rustc.html) - Compiler for the Rust programming language
-* [Cargo](https://doc.rust-lang.org/cargo/) - Package manager for the Rust programming language
-
 Velvet's standard output format is HDF5 so you will also need a local installation of `libhdf5`. The library can be installed with your package manager or downloaded directly from source [here](https://www.hdfgroup.org/solutions/hdf5/).
 
 * [The HDF Group](https://www.hdfgroup.org/) - Official HDF5 organization
 
-### Installation
+### Installation (from source)
+
+To build Velvet you will need to have Rust's compiler and package manager installed on your machine. Instructions for most platforms can be found [here](https://www.rust-lang.org/tools/install).
+
+* [rustc](https://doc.rust-lang.org/rustc/what-is-rustc.html) - Compiler for the Rust programming language
+* [Cargo](https://doc.rust-lang.org/cargo/) - Package manager for the Rust programming language
 
 1. Clone the repo
 ```bash
@@ -41,14 +42,8 @@ $ cargo build --release --workspace
 
 ## Usage
 
-The [`examples`](./examples) directory contains examples of how to use the `velvet-core` API to configure simulations directly in code.
-
-[__nve.rs__](./examples/nve.rs) - Simulation of Ar gas in the NVE ensemble. This example uses a Lennard-Jones style pair potential to simulate the pairwise interactions between Ar atoms. The velocity Verlet algorithm is employed to integrate the equations of motion in the system. The total energy of this system is plotted at each timestep in the figure below.
-<p align="center"><img src="./assets/nve.png" width="720"></p>
-
-[__nvt.rs__](./examples/nvt.rs) - Simulation of Ar gas in the NVT ensemble. This example expands upon the NVE example by adding a Nose-Hoover style thermostat to regulate the temperature of the system. The temperature of this system is plotted at each timestep in the figure below.
-<p align="center"><img src="./assets/nvt.png" width="720"></p>
-
+The [`examples`](./examples) directory contains examples of how to use the [`velvet`](https://crates.io/crates/velvet) crate to configure simulations directly in code.
+The [`scripts`](./scripts) directory contains Python scripts to visualize the results of each example.
 
 ## Roadmap
 
@@ -60,4 +55,4 @@ Distributed under the MIT License. See [LICENSE](LICENSE) for more information.
 
 ## Acknowledgements
 
-* [Lumol](https://github.com/lumol-org/lumol)
+* [Lumol](https://github.com/lumol-org/lumol) - Universal extensible molecular simulation engine

CHECKLIST.md → RELEASE_CHECKLIST.md

@@ -9,11 +9,9 @@ Refer to this document before publishing a new release of the `velvet` umbrella
 ```bash
 $ cargo test --workspace
 ```
-- [ ] Generate benchmark report
+- [ ] Run the benchmark suite
 ```bash
 $ cargo criterion --workspace
-$ mkdir docs/benches/<version>
-$ cp -r target/criterion/reports/* docs/benches/<version>
 ```
 - [ ] Commit the changes
 ```bash

crates/core/benches/integrators.rs → benches/integrators.rs

@@ -1,31 +1,33 @@
 use criterion::{criterion_group, criterion_main, Criterion};
 use std::fs::File;
 use std::io::BufReader;
-use velvet_convert::poscar::load_poscar;
-use velvet_core::distributions::{Boltzmann, VelocityDistribution};
-use velvet_core::integrators::{Integrator, VelocityVerlet};
-use velvet_core::potentials::Potentials;
 use test_utils::test_resources_path;
+use velvet_core::integrators::{Integrator, VelocityVerlet};
+use velvet_core::velocity_distributions::{Boltzmann, VelocityDistribution};
+use velvet_external_data::poscar::load_poscar;
+
+use test_utils;
 
 pub fn velocity_verlet_benchmark(c: &mut Criterion) {
     let file = File::open(test_resources_path("argon.poscar")).unwrap();
     let reader = BufReader::new(file);
-    let mut sys = load_poscar(reader);
+    let mut system = load_poscar(reader);
 
     let target = 100 as f32;
     let boltz = Boltzmann::new(target);
-    boltz.apply(&mut sys);
+    boltz.apply(&mut system);
 
     // load potentials
-    let path = test_resources_path("argon.pot.velvet");
-    let file = File::open(&path).unwrap();
-    let pots: Potentials = ron::de::from_reader(file).unwrap();
+    // let path = test_resources_path("argon.pot.velvet");
+    // let file = File::open(&path).unwrap();
+    // let pots: Potentials = ron::de::from_reader(file).unwrap();
+    let potentials = test_utils::get_argon_potentials(&system);
 
     let mut vv = VelocityVerlet::new(1.0);
-    vv.setup(&sys, &pots);
+    vv.setup(&system, &potentials);
 
     c.bench_function("velocity_verlet", |b| {
-        b.iter(|| vv.integrate(&mut sys, &pots))
+        b.iter(|| vv.integrate(&mut system, &potentials))
     });
 }
 

crates/core/benches/properties.rs → benches/properties.rs

@@ -1,66 +1,71 @@
 use criterion::{criterion_group, criterion_main, Criterion};
 use std::fs::File;
 use std::io::BufReader;
-use velvet_convert::poscar::load_poscar;
-use velvet_core::distributions::{Boltzmann, VelocityDistribution};
-use velvet_core::potentials::Potentials;
+use test_utils::test_resources_path;
 use velvet_core::properties::{
     Forces, IntrinsicProperty, KineticEnergy, PotentialEnergy, Property, Temperature,
 };
-use test_utils::test_resources_path;
+use velvet_core::velocity_distributions::{Boltzmann, VelocityDistribution};
+use velvet_external_data::poscar::load_poscar;
 
+use test_utils;
 
 pub fn forces_benchmark(c: &mut Criterion) {
     let file = File::open(test_resources_path("argon.poscar")).unwrap();
     let reader = BufReader::new(file);
-    let sys = load_poscar(reader);
+    let system = load_poscar(reader);
 
     // load potentials
-    let path = test_resources_path("argon.pot.velvet");
-    let file = File::open(&path).unwrap();
-    let pots: Potentials = ron::de::from_reader(file).unwrap();
+    // let path = test_resources_path("argon.pot.velvet");
+    // let file = File::open(&path).unwrap();
+    // let pots: Potentials = ron::de::from_reader(file).unwrap();
+    let potentials = test_utils::get_argon_potentials(&system);
 
-    c.bench_function("forces", |b| b.iter(|| Forces.calculate(&sys, &pots)));
+    c.bench_function("forces", |b| {
+        b.iter(|| Forces.calculate(&system, &potentials))
+    });
 }
 
 pub fn potential_energy_benchmark(c: &mut Criterion) {
     let file = File::open(test_resources_path("argon.poscar")).unwrap();
     let reader = BufReader::new(file);
-    let sys = load_poscar(reader);
+    let system = load_poscar(reader);
 
     // load potentials
-    let path = test_resources_path("argon.pot.velvet");
-    let file = File::open(&path).unwrap();
-    let pots: Potentials = ron::de::from_reader(file).unwrap();
+    // let path = test_resources_path("argon.pot.velvet");
+    // let file = File::open(&path).unwrap();
+    // let pots: Potentials = ron::de::from_reader(file).unwrap();
+    let potentials = test_utils::get_argon_potentials(&system);
 
     c.bench_function("potential_energy", |b| {
-        b.iter(|| PotentialEnergy.calculate(&sys, &pots))
+        b.iter(|| PotentialEnergy.calculate(&system, &potentials))
     });
 }
 
 pub fn kinetic_energy_benchmark(c: &mut Criterion) {
     let file = File::open(test_resources_path("argon.poscar")).unwrap();
     let reader = BufReader::new(file);
-    let sys = load_poscar(reader);
+    let system = load_poscar(reader);
 
     // load potentials
-    let path = test_resources_path("argon.pot.velvet");
-    let file = File::open(&path).unwrap();
-    let pots: Potentials = ron::de::from_reader(file).unwrap();
+    // let path = test_resources_path("argon.pot.velvet");
+    // let file = File::open(&path).unwrap();
+    // let pots: Potentials = ron::de::from_reader(file).unwrap();
+    let potentials = test_utils::get_argon_potentials(&system);
 
     c.bench_function("kinetic_energy", |b| {
-        b.iter(|| KineticEnergy.calculate(&sys, &pots))
+        b.iter(|| KineticEnergy.calculate(&system, &potentials))
     });
 }
 
 pub fn temperature_benchmark(c: &mut Criterion) {
     let file = File::open(test_resources_path("argon.poscar")).unwrap();
     let reader = BufReader::new(file);
-    let mut sys = load_poscar(reader);
+    let mut system = load_poscar(reader);
     let boltz = Boltzmann::new(1000 as f32);
-    boltz.apply(&mut sys);
+    boltz.apply(&mut system);
     c.bench_function("temperature", |b| {
-        b.iter(|| Temperature.calculate_intrinsic(&sys))
+        b.iter(|| Temperature.calculate_intrinsic(&system))
     });
 }
 

benches/thermostats.rs

@@ -0,0 +1,58 @@
+use criterion::{criterion_group, criterion_main, Criterion};
+use velvet_core::integrators::{Integrator, VelocityVerlet};
+use velvet_core::thermostats::{Berendsen, NoseHoover, Thermostat};
+use velvet_core::velocity_distributions::{Boltzmann, VelocityDistribution};
+use velvet_external_data::poscar::load_poscar;
+
+use test_utils;
+
+use std::fs::File;
+use std::io::BufReader;
+
+pub fn thermostats_group_benchmark(c: &mut Criterion) {
+    let mut group = c.benchmark_group("thermostats");
+
+    let file = File::open(test_utils::test_resources_path("argon.poscar")).unwrap();
+    let reader = BufReader::new(file);
+    let mut system = load_poscar(reader);
+
+    let target = 100 as f32;
+    let boltz = Boltzmann::new(target);
+    boltz.apply(&mut system);
+
+    // load potentials
+    // let path = test_resources_path("argon.pot.velvet");
+    // let file = File::open(&path).unwrap();
+    // let pots: Potentials = ron::de::from_reader(file).unwrap();
+    let potentials = test_utils::get_argon_potentials(&system);
+
+    let mut vv = VelocityVerlet::new(1.0);
+    vv.setup(&system, &potentials);
+
+    let mut berendsen = Berendsen::new(target, 2.0);
+    berendsen.setup(&system);
+
+    let mut nose = NoseHoover::new(target, 1.01, 1.0);
+    nose.setup(&system);
+
+    group.bench_function("berendsen", |b| {
+        b.iter(|| {
+            berendsen.pre_integrate(&mut system);
+            vv.integrate(&mut system, &potentials);
+            berendsen.post_integrate(&mut system);
+        })
+    });
+
+    group.bench_function("nose_hoover", |b| {
+        b.iter(|| {
+            nose.pre_integrate(&mut system);
+            vv.integrate(&mut system, &potentials);
+            nose.post_integrate(&mut system);
+        })
+    });
+
+    group.finish()
+}
+
+criterion_group!(thermostats, thermostats_group_benchmark);
+criterion_main!(thermostats);

crates/cli/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "velvet-cli"
-version = "0.1.1"
+version = "0.1.2"
 authors = ["Seaton Ullberg <[email protected]>"]
 description = "Command line tool built on top of the Velvet API"
 license = "MIT"
@@ -10,8 +10,8 @@ edition = "2018"
 [dependencies]
 clap = "2.33"
 ron = "0.6"
-velvet-convert = { path = "../convert", version = "0.1.2" }
-velvet-core = { path = "../core", version = "0.3.0" }
+velvet-core = { path = "../core", version = "0.4.0" }
+velvet-external-data = { path = "../external-data", version = "0.1.0" }
 
 [[bin]]
 name = "velvet"

crates/cli/src/main.rs

@@ -5,7 +5,7 @@ use std::io::BufReader;
 use clap::{arg_enum, value_t, App, Arg, ArgMatches, SubCommand};
 use ron::ser::{to_string_pretty, PrettyConfig};
 
-use velvet_convert::poscar::load_poscar;
+use velvet_external_data::poscar::load_poscar;
 
 arg_enum! {
     #[derive(PartialEq, Debug)]