From bd76fb6fc96b5b8ad611d93aeaa1563028a75191 Mon Sep 17 00:00:00 2001 From: "Documenter.jl" Date: Mon, 27 Jan 2025 04:14:32 +0000 Subject: [PATCH] build based on 59f8967 --- dev/.documenter-siteinfo.json | 2 +- dev/api/index.html | 4 ++-- dev/development/index.html | 2 +- dev/differentiable/index.html | 2 +- dev/documentation/index.html | 2 +- dev/examples/index.html | 2 +- dev/exercises/index.html | 2 +- dev/index.html | 2 +- dev/publications/index.html | 2 +- dev/related/index.html | 2 +- 10 files changed, 11 insertions(+), 11 deletions(-) diff --git a/dev/.documenter-siteinfo.json b/dev/.documenter-siteinfo.json index 376f6ad9..88b8c47f 100644 --- a/dev/.documenter-siteinfo.json +++ b/dev/.documenter-siteinfo.json @@ -1 +1 @@ -{"documenter":{"julia_version":"1.11.3","generation_timestamp":"2025-01-23T14:46:34","documenter_version":"1.8.0"}} \ No newline at end of file +{"documenter":{"julia_version":"1.11.3","generation_timestamp":"2025-01-27T04:14:14","documenter_version":"1.8.0"}} \ No newline at end of file diff --git a/dev/api/index.html b/dev/api/index.html index ff1e7ef9..3154639b 100644 --- a/dev/api/index.html +++ b/dev/api/index.html @@ -1,5 +1,5 @@ -API · Molly.jl
GitHub

Molly API

The API reference can be found here.

Molly re-exports StaticArrays.jl and Unitful.jl, making the likes of SVector and 1.0u"nm" available when you call using Molly.

Package extensions are used in order to reduce the number of dependencies:

Exported names

Docstrings

Molly.ASECalculator — Type
ASECalculator(; <keyword arguments>)

A Python ASE calculator.

This calculator is only available when PythonCall is imported. It is the user's responsibility to have the required Python packages installed. This includes ASE and any packages providing the calculator.

Contrary to the rest of Molly, unitless quantities are assumed to have ASE units: Å for length, eV for energy, u for mass, and Å sqrt(u/eV) for time. Unitful quantities will be converted as appropriate.

Not currently compatible with TriclinicBoundary.

Arguments

  • ase_calc: the ASE calculator created with PythonCall.
  • atoms: the atoms, or atom equivalents, in the system.
  • coords: the coordinates of the atoms in the system. Typically a vector of SVectors of 2 or 3 dimensions.
  • boundary: the bounding box in which the simulation takes place.
  • elements=nothing: vector of atom elements as a string, either elements or atoms_data (which contains element data) must be provided.
  • atoms_data=nothing: other data associated with the atoms.
  • velocities=nothing: the velocities of the atoms in the system, only required if the velocities contribute to the potential energy or forces.
source
Molly.AbstractGBSA — Type

Generalized Born (GB) implicit solvent models augmented with the hydrophobic solvent accessible surface area (SA) term.

Custom GBSA methods should sub-type this abstract type.

source
Molly.AndersenThermostat — Type
AndersenThermostat(temperature, coupling_const)

The Andersen thermostat for controlling temperature.

The velocity of each atom is randomly changed each time step with probability dt / coupling_const to a velocity drawn from the Maxwell-Boltzmann distribution. See Andersen 1980.

source
Molly.AshbaughHatch — Type
AshbaughHatch(; cutoff, use_neighbors, shortcut, ϵ_mixing, σ_mixing,
+API · Molly.jl
GitHub
Molly API
The API reference can be found here.
Molly re-exports StaticArrays.jl and Unitful.jl, making the likes of SVector and 1.0u"nm" available when you call using Molly.
Package extensions are used in order to reduce the number of dependencies:
Exported names
Docstrings
Molly.ASECalculator — Type
ASECalculator(; <keyword arguments>)
A Python ASE calculator.
This calculator is only available when PythonCall is imported. It is the user's responsibility to have the required Python packages installed. This includes ASE and any packages providing the calculator.
Contrary to the rest of Molly, unitless quantities are assumed to have ASE units: Å for length, eV for energy, u for mass, and Å sqrt(u/eV) for time. Unitful quantities will be converted as appropriate.
Not currently compatible with TriclinicBoundary.
Arguments
  • ase_calc: the ASE calculator created with PythonCall.
  • atoms: the atoms, or atom equivalents, in the system.
  • coords: the coordinates of the atoms in the system. Typically a   vector of SVectors of 2 or 3 dimensions.
  • boundary: the bounding box in which the simulation takes place.
  • elements=nothing: vector of atom elements as a string, either elements or   atoms_data (which contains element data) must be provided.
  • atoms_data=nothing: other data associated with the atoms.
  • velocities=nothing: the velocities of the atoms in the system, only required   if the velocities contribute to the potential energy or forces.
source
Molly.AbstractGBSA — Type
Generalized Born (GB) implicit solvent models augmented with the hydrophobic solvent accessible surface area (SA) term.
Custom GBSA methods should sub-type this abstract type.
source
Molly.AndersenThermostat — Type
AndersenThermostat(temperature, coupling_const)
The Andersen thermostat for controlling temperature.
The velocity of each atom is randomly changed each time step with probability dt / coupling_const to a velocity drawn from the Maxwell-Boltzmann distribution. See Andersen 1980.
source
Molly.AshbaughHatch — Type
AshbaughHatch(; cutoff, use_neighbors, shortcut, ϵ_mixing, σ_mixing,
               λ_mixing, weight_special)
The Ashbaugh-Hatch potential ($V_{\text{AH}}$) is a modified Lennard-Jones ($V_{\text{LJ}}$) 6-12 interaction between two atoms.
The potential energy is defined as
\[V_{\text{LJ}}(r_{ij}) = 4\varepsilon_{ij} \left[\left(\frac{\sigma_{ij}}{r_{ij}}\right)^{12} - \left(\frac{\sigma_{ij}}{r_{ij}}\right)^{6}\right] \\ \]
\[V_{\text{AH}}(r_{ij}) =
     \begin{cases}
       V_{\text{LJ}}(r_{ij}) +\varepsilon_{ij}(1-λ_{ij}) &,  r_{ij}\leq  2^{1/6}σ  \\
@@ -141,4 +141,4 @@
 torsion_angle(vec_ij, vec_jk, vec_kl)

Calculate the torsion angle in radians defined by four coordinates or three vectors.

The angle between the planes defined by atoms (i, j, k) and (j, k, l) is returned in the range -π to π.

source
Molly.use_neighbors — Method
use_neighbors(inter)

Whether a pairwise interaction uses the neighbor list, default false.

Custom pairwise interactions can define a method for this function. For built-in interactions such as LennardJones this function accesses the use_neighbors field of the struct.

source
Molly.ustrip_vec — Method
ustrip_vec(x)
 ustrip_vec(u, x)

Broadcasted form of ustrip from Unitful.jl, allowing e.g. ustrip_vec.(coords).

source
Molly.vector — Method
vector(c1, c2, boundary)

Displacement between two coordinate values from c1 to c2, accounting for periodic boundary conditions.

The minimum image convention is used, so the displacement is to the closest version of the coordinates accounting for the periodic boundaries. For the TriclinicBoundary an approximation is used to find the closest version by default.

source
Molly.vector_1D — Method
vector_1D(c1, c2, side_length)

Displacement between two 1D coordinate values from c1 to c2, accounting for periodic boundary conditions in a CubicBoundary or RectangularBoundary.

The minimum image convention is used, so the displacement is to the closest version of the coordinate accounting for the periodic boundaries.

source
Molly.virial — Method
virial(sys, neighbors=find_neighbors(sys), step_n=0; n_threads=Threads.nthreads())
 virial(inter, sys, neighbors, step_n; n_threads=Threads.nthreads())

Calculate the virial of a system or the virial resulting from a general interaction.

The virial is defined as

\[\Xi = -\frac{1}{2} \sum_{i,j>i} r_{ij} \cdot F_{ij}\]

Custom general interaction types can implement this function.

This should only be used on systems containing just pairwise interactions, or where the specific interactions, constraints and general interactions without virial defined do not contribute to the virial.

source
Molly.visualize — Function
visualize(coord_logger, boundary, out_filepath; <keyword arguments>)

Visualize a simulation as an animation.

This function is only available when GLMakie is imported. It can take a while to run, depending on the length of the simulation and the number of atoms.

Arguments

  • connections=Tuple{Int, Int}[]: pairs of atoms indices to link with bonds.
  • connection_frames: the frames in which bonds are shown. Should be a list of the same length as the number of frames, where each item is a list of Bools of the same length as connections. Defaults to always true.
  • trails::Integer=0: the number of preceding frames to show as transparent trails.
  • framerate::Integer=30: the frame rate of the animation.
  • color=:purple: the color of the atoms. Can be a single color or a list of colors of the same length as the number of atoms.
  • connection_color=:orange: the color of the bonds. Can be a single color or a list of colors of the same length as connections.
  • markersize=0.05: the size of the atom markers, in the units of the data.
  • linewidth=2.0: the width of the bond lines.
  • transparency=true: whether transparency is active on the plot.
  • show_boundary::Bool=true: whether to show the bounding box as lines.
  • boundary_linewidth=2.0: the width of the boundary lines.
  • boundary_color=:black: the color of the boundary lines.
  • kwargs...: other keyword arguments are passed to the point plotting function.
source
Molly.volume — Method
volume(sys)
-volume(boundary)

Calculate the volume (3D) or area (2D) of a System or bounding box.

Returns infinite volume for infinite boundaries.

source
Molly.wrap_coord_1D — Method
wrap_coord_1D(c, side_length)

Ensure a 1D coordinate is within the bounding box and return the coordinate.

source
Molly.wrap_coords — Method
wrap_coords(c, boundary)

Ensure a coordinate is within the bounding box and return the coordinate.

source
+volume(boundary)

Calculate the volume (3D) or area (2D) of a System or bounding box.

Returns infinite volume for infinite boundaries.

source
Molly.wrap_coord_1D — Method
wrap_coord_1D(c, side_length)

Ensure a 1D coordinate is within the bounding box and return the coordinate.

source
Molly.wrap_coords — Method
wrap_coords(c, boundary)

Ensure a coordinate is within the bounding box and return the coordinate.

source
diff --git a/dev/development/index.html b/dev/development/index.html index 151fe292..79692cfd 100644 --- a/dev/development/index.html +++ b/dev/development/index.html @@ -1,2 +1,2 @@ -Development · Molly.jl
GitHub

Development documentation

Running tests

The tests will automatically include multithreading and/or GPU tests if multiple threads and/or a CUDA-enabled GPU are available. test/runtests.jl does not include all the tests, see the test directory for more, though these extra tests do not need to be run for every change. Various environmental variables can be set to modify the tests:

  • VISTESTS determines whether to run the GLMakie.jl plotting tests which will error on remote systems where a display is not available, default VISTESTS=1.
  • GPUTESTS determines whether to run the GPU tests, default GPUTESTS=1.
  • DEVICE determines which GPU to run the GPU tests on, default DEVICE=0.
  • GROUP can be used to run a subset of the tests, options All/Protein/Gradients/NotGradients, default GROUP=All.

The CI run does not carry out all tests - for example the GPU tests are not run - and this is reflected in the code coverage.

Benchmarks

The benchmark directory contains some benchmarks for the package.

+Development · Molly.jl
GitHub

Development documentation

Running tests

The tests will automatically include multithreading and/or GPU tests if multiple threads and/or a CUDA-enabled GPU are available. test/runtests.jl does not include all the tests, see the test directory for more, though these extra tests do not need to be run for every change. Various environmental variables can be set to modify the tests:

  • VISTESTS determines whether to run the GLMakie.jl plotting tests which will error on remote systems where a display is not available, default VISTESTS=1.
  • GPUTESTS determines whether to run the GPU tests, default GPUTESTS=1.
  • DEVICE determines which GPU to run the GPU tests on, default DEVICE=0.
  • GROUP can be used to run a subset of the tests, options All/Protein/Gradients/NotGradients, default GROUP=All.

The CI run does not carry out all tests - for example the GPU tests are not run - and this is reflected in the code coverage.

Benchmarks

The benchmark directory contains some benchmarks for the package.

diff --git a/dev/differentiable/index.html b/dev/differentiable/index.html index a39ae2ee..3dddfe6e 100644 --- a/dev/differentiable/index.html +++ b/dev/differentiable/index.html @@ -318,4 +318,4 @@ Epoch 17 | Dist end 0.968 | Loss 0.032 Epoch 18 | Dist end 0.973 | Loss 0.027 Epoch 19 | Dist end 0.982 | Loss 0.018 -Epoch 20 | Dist end 0.995 | Loss 0.005

After training it looks much better: Logo after You could replace the simple network here with a much more complicated model and it would theoretically be able to train, even if it might prove practically difficult (see discussion below).

Biomolecular force fields

Molly was used to train the GB99dms force field for implicit solvent molecular dynamics of proteins. This involved doing differentiable simulations of one million steps with a loss function based on the residue-residue distance match to explicit solvent simulations. The code is available.

Reversible simulation

Molly.jl was also used to code reversible simulation, an extension of differentiable simulation with RAD where the gradients are calculated explicitly. This means the memory cost is constant in step number.

Molecular loss functions

Ultimately, you need some objective function in order to calculate the gradient for each parameter. Here are some ideas for loss functions suitable for differentiable molecular simulations:

Some of these are currently not possible in Molly as the loggers are ignored for gradient purposes, but this will hopefully change in future.

Tips and tricks

+Epoch 20 | Dist end 0.995 | Loss 0.005

After training it looks much better: Logo after You could replace the simple network here with a much more complicated model and it would theoretically be able to train, even if it might prove practically difficult (see discussion below).

Biomolecular force fields

Molly was used to train the GB99dms force field for implicit solvent molecular dynamics of proteins. This involved doing differentiable simulations of one million steps with a loss function based on the residue-residue distance match to explicit solvent simulations. The code is available.

Reversible simulation

Molly.jl was also used to code reversible simulation, an extension of differentiable simulation with RAD where the gradients are calculated explicitly. This means the memory cost is constant in step number.

Molecular loss functions

Ultimately, you need some objective function in order to calculate the gradient for each parameter. Here are some ideas for loss functions suitable for differentiable molecular simulations:

Some of these are currently not possible in Molly as the loggers are ignored for gradient purposes, but this will hopefully change in future.

Tips and tricks

diff --git a/dev/documentation/index.html b/dev/documentation/index.html index ebd38d37..376068e3 100644 --- a/dev/documentation/index.html +++ b/dev/documentation/index.html @@ -663,4 +663,4 @@ 0.1703351361585439 nm ps^-1 -0.027009534351612234 nm ps^-1 0.23543457751795477 nm ps^-1 -

This may not apply across Julia versions, though you can use StableRNGs.jl. It also does not apply across different backends such as CPU and GPU.

+

This may not apply across Julia versions, though you can use StableRNGs.jl. It also does not apply across different backends such as CPU and GPU.

diff --git a/dev/examples/index.html b/dev/examples/index.html index f25ba90a..8aa89434 100644 --- a/dev/examples/index.html +++ b/dev/examples/index.html @@ -894,4 +894,4 @@ # Check that the constraints are satisfied at the end of the simulation @test check_position_constraints(sys, shake) -@test check_velocity_constraints(sys, shake) +@test check_velocity_constraints(sys, shake) diff --git a/dev/exercises/index.html b/dev/exercises/index.html index eb5d509e..466a70ec 100644 --- a/dev/exercises/index.html +++ b/dev/exercises/index.html @@ -1,2 +1,2 @@ -Exercises · Molly.jl
GitHub

Molly exercises

A notebook with exercises covering various parts of Molly is available here, with answers available here.

Another notebook with exercises on computing transport coefficients with Molly is available here.

+Exercises · Molly.jl
GitHub

Molly exercises

A notebook with exercises covering various parts of Molly is available here, with answers available here.

Another notebook with exercises on computing transport coefficients with Molly is available here.

diff --git a/dev/index.html b/dev/index.html index 9349c109..9fca9777 100644 --- a/dev/index.html +++ b/dev/index.html @@ -42,4 +42,4 @@ coupling=AndersenThermostat(temp, 1.0u"ps"), ) -simulate!(sys, simulator, 5_000)

The above 1 ps simulation looks something like this when you view it in VMD: MD simulation

Contributing

Contributions are very welcome including reporting bugs, fixing bugs, adding new features, improving performance, adding tests and improving documentation. Feel free to open an issue or use the channels below to discuss your contribution. New features will generally require tests to be added as well. See the roadmap issue for some discussion of recent progress and future plans.

Join the #juliamolsim channel on the Julia Slack, the #molly channel on the JuliaMolSim Zulip or post on the Julia Discourse to discuss the usage and development of Molly.jl.

Molly.jl follows the Contributor Covenant code of conduct.

Citation

If you use Molly, please cite the following paper (bib entry here):

A paper involving more contributors with further details on the software will be written at some point.

Interested?

There is the possibility of a postdoc position involving the development and use of Molly. Contact Joe Greener with informal enquiries.

+simulate!(sys, simulator, 5_000)

The above 1 ps simulation looks something like this when you view it in VMD: MD simulation

Contributing

Contributions are very welcome including reporting bugs, fixing bugs, adding new features, improving performance, adding tests and improving documentation. Feel free to open an issue or use the channels below to discuss your contribution. New features will generally require tests to be added as well. See the roadmap issue for some discussion of recent progress and future plans.

Join the #juliamolsim channel on the Julia Slack, the #molly channel on the JuliaMolSim Zulip or post on the Julia Discourse to discuss the usage and development of Molly.jl.

Molly.jl follows the Contributor Covenant code of conduct.

Citation

If you use Molly, please cite the following paper (bib entry here):

A paper involving more contributors with further details on the software will be written at some point.

Interested?

There is the possibility of a postdoc position involving the development and use of Molly. Contact Joe Greener with informal enquiries.

diff --git a/dev/publications/index.html b/dev/publications/index.html index 21cad356..e270074e 100644 --- a/dev/publications/index.html +++ b/dev/publications/index.html @@ -1,2 +1,2 @@ -Publications · Molly.jl
GitHub

Publications

If you use Molly, please cite the following paper (bib entry here):

  • Greener JG. Differentiable simulation to develop molecular dynamics force fields for disordered proteins, Chemical Science 15, 4897-4909 (2024)

A paper involving more contributors with further details on the software will be written at some point.

Other papers that use, contribute to or are compatible with Molly are listed below:

  • Martínez L. CellListMap.jl: Efficient and customizable cell list implementation for calculation of pairwise particle properties within a cutoff, Comput Phys Commun 279, 108452 (2022)
  • Blassel N and Stoltz G. Fixing the flux: A dual approach to computing transport coefficients, arXiv (2023)
  • Witt WC et al. ACEpotentials.jl: A Julia implementation of the atomic cluster expansion, J Chem Phys 159, 164101 (2023)
  • Monmarché P, Spacek R and Stoltz G. Transient subtraction: A control variate method for computing transport coefficients, arXiv (2024)
  • Greener JG. Reversible molecular simulation for training classical and machine learning force field, arXiv (2024)
+Publications · Molly.jl
GitHub

Publications

If you use Molly, please cite the following paper (bib entry here):

  • Greener JG. Differentiable simulation to develop molecular dynamics force fields for disordered proteins, Chemical Science 15, 4897-4909 (2024)

A paper involving more contributors with further details on the software will be written at some point.

Other papers that use, contribute to or are compatible with Molly are listed below:

  • Martínez L. CellListMap.jl: Efficient and customizable cell list implementation for calculation of pairwise particle properties within a cutoff, Comput Phys Commun 279, 108452 (2022)
  • Blassel N and Stoltz G. Fixing the flux: A dual approach to computing transport coefficients, arXiv (2023)
  • Witt WC et al. ACEpotentials.jl: A Julia implementation of the atomic cluster expansion, J Chem Phys 159, 164101 (2023)
  • Monmarché P, Spacek R and Stoltz G. Transient subtraction: A control variate method for computing transport coefficients, arXiv (2024)
  • Greener JG. Reversible molecular simulation for training classical and machine learning force field, arXiv (2024)
diff --git a/dev/related/index.html b/dev/related/index.html index 089e277f..97a1089b 100644 --- a/dev/related/index.html +++ b/dev/related/index.html @@ -1,2 +1,2 @@ -Related software · Molly.jl
GitHub

Related software

There are many mature packages for molecular simulation. Of particular note here are OpenMM and GROMACS, both of which influenced the implementation of Molly. Molly can be thought of as similar to OpenMM in that it exposes simulation internals in a high-level language, though it is written in one language all the way down rather than using multiple device-specific kernels. It also aims to be differentiable and work just as well with non-molecular physical simulations, though how much this impacts the ability to reach high simulation speeds remains to be seen.

For differentiable simulations there are a number of related packages:

In Julia there are a number of packages related to atomic simulation, some of which are involved with the JuliaMolSim organisation:

+Related software · Molly.jl
GitHub

Related software

There are many mature packages for molecular simulation. Of particular note here are OpenMM and GROMACS, both of which influenced the implementation of Molly. Molly can be thought of as similar to OpenMM in that it exposes simulation internals in a high-level language, though it is written in one language all the way down rather than using multiple device-specific kernels. It also aims to be differentiable and work just as well with non-molecular physical simulations, though how much this impacts the ability to reach high simulation speeds remains to be seen.

For differentiable simulations there are a number of related packages:

In Julia there are a number of packages related to atomic simulation, some of which are involved with the JuliaMolSim organisation: