glotzerlab / hoomd-examples Goto Github PK

HOOMD-blue example scripts.

License: BSD 3-Clause "New" or "Revised" License

Jupyter Notebook 99.65% Python 0.35%

python jupyter molecular-dynamics hard-particle hoomd-blue simulation particle-system monte-carlo-simulation tutorial

hoomd-examples's Introduction

HOOMD-blue tutorials

These jupyter notebooks provide a tutorial for the HOOMD-blue simulation software and are included in HOOMD-blue's documentation.

Outline

Executing the tutorials

You can install HOOMD-blue and run these examples interactively.

Clone the hoomd-examples repository and start jupyter notebook

$ git clone https://github.com/glotzerlab/hoomd-examples
$ cd hoomd-examples
$ jupyter lab

Prerequisites

These examples use the following python packages:

Conda users can install these from conda-forge:

conda install -c conda-forge fresnel freud  gsd hoomd jupyterlab matplotlib

hoomd-examples's People

Contributors

Stargazers

Watchers

Forkers

yuanchaohu worjeff mikemhenry rajneesh1508 krishnan120492 jennyfothergill spencerraw dorian-adams juhaepark haotianzhangai4science giita-19 alinacao2000 clpetix

hoomd-examples's Issues

MD tutorial doesn't display random particle configurations

File name

01-Introducing-Molecular-Dynamics/02-Initializing-a-Random-System

Description

In the section

Here is the final random configuration of particles:

render(snapshot)

snapshot is not updated and still displays the initial lattice.

Can you fix it?

I will fix this.

Tutorial description

Add an introductory tutorial that teaches how to run MD simulations with rigid bodies.

Section

As a new tutorial after custom actions.

Author

I will write this tutorial.

Initialization of Particles in Simple Cubic, FCC, and BCC Lattice

Example description

Show how using freud to generate an arrangement of particles in different lattices and creating a gsd file from the configuration.

Section

Initialization

Update restartable-docs for HOOMD v3

Description

sphinx-docs/restartable-jobs.rst has not been updated to the new API.

Patchy Particles example does not work with hooomd 4.6.0

File name

02-Simulating-a-System-of-Patchy-Particles.ipynb

Description

Running this notebook, both within jupyter and as a python script, results in the following error

(base) Patron@Patrons-MacBook-Air ~ % python 02-Simulating-a-System-of-Patchy-Particles.py
/Users/Patron/02-Simulating-a-System-of-Patchy-Particles.py:237: FutureWarning: CPPPotential is deprecated since 4.6.0. Use a hpmc.pair.Pair potential.
  patch_potential = hoomd.hpmc.pair.user.CPPPotential(
/Users/Patron/02-Simulating-a-System-of-Patchy-Particles.py:247: FutureWarning: pair_potential is deprecated since 4.5.0. Use pair_potentials.
  mc.pair_potential = patch_potential
Traceback (most recent call last):
  File "/Users/Patron/02-Simulating-a-System-of-Patchy-Particles.py", line 256, in <module>
    simulation.run(0)
  File "/opt/anaconda3/lib/python3.11/site-packages/hoomd/simulation.py", line 555, in run
    self.operations._schedule()
  File "/opt/anaconda3/lib/python3.11/site-packages/hoomd/operations.py", line 211, in _schedule
    self.integrator._attach(sim)
  File "/opt/anaconda3/lib/python3.11/site-packages/hoomd/operation.py", line 315, in _attach
    self._attach_hook()
  File "/opt/anaconda3/lib/python3.11/site-packages/hoomd/hpmc/integrate.py", line 457, in _attach_hook
    self._pair_potential._attach(self._simulation)
  File "/opt/anaconda3/lib/python3.11/site-packages/hoomd/operation.py", line 315, in _attach
    self._attach_hook()
  File "/opt/anaconda3/lib/python3.11/site-packages/hoomd/hpmc/pair/user.py", line 290, in _attach_hook
    self._cpp_obj = _jit.PatchEnergyJIT(
                    ^^^^^^^^^^^^^^^^^^^^
RuntimeError: Error compiling JIT code:

                        #include <stdio.h>
                        #include "hoomd/HOOMDMath.h"
                        #include "hoomd/VectorMath.h"

                        // param_array (singlet class) or param_array_isotropic
                        // and param_array_constituent (union class) are
                        // allocated by the library
                        float *param_array;
                        

                        using namespace hoomd;

                        extern "C"
                        {
                        float eval(const vec3<float>& r_ij,
                            unsigned int type_i,
                            const quat<float>& q_i,
                            float d_i,
                            float charge_i,
                            unsigned int type_j,
                            const quat<float>& q_j,
                            float d_j,
                            float charge_j)
                            {
                        
const float delta = 45 * M_PI / 180;  // delta in radians
const float epsilon = 1.000000;
const float lambda = 1.200000;
const float sigma = 1.000000;  // hard core diameter

const float kT = param_array[0];
const float beta_epsilon = epsilon/kT;

const vec3<float> ehat_particle_reference_frame(1, 0, 0);
vec3<float> ehat_i = rotate(q_i, ehat_particle_reference_frame);
vec3<float> ehat_j = rotate(q_j, ehat_particle_reference_frame);

vec3<float> r_hat_ij = r_ij / sqrtf(dot(r_ij, r_ij));
bool patch_on_i_is_aligned_with_r_ij = dot(ehat_i, r_hat_ij) >= cos(delta);
bool patch_on_j_is_aligned_with_r_ji = dot(ehat_j, -r_hat_ij) >= cos(delta);

float rsq = dot(r_ij, r_ij);
float r_ij_length = sqrtf(rsq);
if (patch_on_i_is_aligned_with_r_ij
    && patch_on_j_is_aligned_with_r_ji
    && r_ij_length < lambda*sigma)
    {
    return -beta_epsilon;
    }
else
    {
    return 0.0;
    }

                            }
                        }
                        
Compilation arguments:
-cc1
-triple
x86_64-apple-macosx13.0.0
-Wundef-prefix=TARGET_OS_OSX
-Werror=undef-prefix
-Wdeprecated-objc-isa-usage
-Werror=deprecated-objc-isa-usage
-emit-llvm
-disable-free
-clear-ast-before-backend
-disable-llvm-verifier
-discard-value-names
-main-file-name
_hoomd_llvm_code.cc
-mrelocation-model
pic
-pic-level
2
-mframe-pointer=all
-ffp-contract=on
-fno-rounding-math
-funwind-tables=2
-fcompatibility-qualified-id-block-type-checking
-fvisibility-inlines-hidden-static-local-var
-target-cpu
penryn
-tune-cpu
generic
-mllvm
-treat-scalable-fixed-error-as-warning
-debugger-tuning=lldb
-target-linker-version
609
-fcoverage-compilation-dir=/Users/Patron
-resource-dir
/opt/anaconda3/lib/clang/14.0.6
-D
HOOMD_LLVMJIT_BUILD
-D
HOOMD_LONGREAL_SIZE=64
-D
HOOMD_SHORTREAL_SIZE=32
-I
/opt/anaconda3/lib/python3.11/site-packages/hoomd/include
-stdlib=libc++
-internal-isystem
/opt/anaconda3/bin/../include/c++/v1
-internal-isystem
/usr/local/include
-internal-isystem
/opt/anaconda3/lib/clang/14.0.6/include
-internal-externc-isystem
/usr/include
-O3
--std=c++14
-fdeprecated-macro
-fdebug-compilation-dir=/Users/Patron
-ferror-limit
19
-stack-protector
1
-fblocks
-fencode-extended-block-signature
-fregister-global-dtors-with-atexit
-fgnuc-version=4.2.1
-fcxx-exceptions
-fexceptions
-fmax-type-align=16
-vectorize-loops
-vectorize-slp
-D__GCC_HAVE_DWARF2_CFI_ASM=1
-o
_hoomd_llvm_code.ll
-x
c++
_hoomd_llvm_code.cc

In file included from code.cc:3:
In file included from /opt/anaconda3/lib/python3.11/site-packages/hoomd/include/hoomd/HOOMDMath.h:33:
In file included from /opt/anaconda3/bin/../include/c++/v1/cmath:317:
In file included from /opt/anaconda3/bin/../include/c++/v1/math.h:316:
/opt/anaconda3/bin/../include/c++/v1/stdlib.h:150:34: error: unknown type name 'ldiv_t'
inline _LIBCPP_INLINE_VISIBILITY ldiv_t div(long __x, long __y) _NOEXCEPT {
                                 ^
/opt/anaconda3/bin/../include/c++/v1/stdlib.h:151:12: error: no member named 'ldiv' in the global namespace
  return ::ldiv(__x, __y);
         ~~^
/opt/anaconda3/bin/../include/c++/v1/stdlib.h:154:34: error: unknown type name 'lldiv_t'
inline _LIBCPP_INLINE_VISIBILITY lldiv_t div(long long __x,
                                 ^
/opt/anaconda3/bin/../include/c++/v1/stdlib.h:156:12: error: no member named 'lldiv' in the global namespace
  return ::lldiv(__x, __y);
         ~~^
In file included from code.cc:3:
In file included from /opt/anaconda3/lib/python3.11/site-packages/hoomd/include/hoomd/HOOMDMath.h:33:
In file included from /opt/anaconda3/bin/../include/c++/v1/cmath:317:
/opt/anaconda3/bin/../include/c++/v1/math.h:388:31: error: use of undeclared identifier 'FP_NAN'
  return __builtin_fpclassify(FP_NAN, FP_INFINITE, FP_NORMAL, FP_SUBNORMAL, FP_ZERO, __x);
                              ^
/opt/anaconda3/bin/../include/c++/v1/math.h:388:39: error: use of undeclared identifier 'FP_INFINITE'
  return __builtin_fpclassify(FP_NAN, FP_INFINITE, FP_NORMAL, FP_SUBNORMAL, FP_ZERO, __x);
                                      ^
/opt/anaconda3/bin/../include/c++/v1/math.h:388:52: error: use of undeclared identifier 'FP_NORMAL'
  return __builtin_fpclassify(FP_NAN, FP_INFINITE, FP_NORMAL, FP_SUBNORMAL, FP_ZERO, __x);
                                                   ^
/opt/anaconda3/bin/../include/c++/v1/math.h:388:63: error: use of undeclared identifier 'FP_SUBNORMAL'
  return __builtin_fpclassify(FP_NAN, FP_INFINITE, FP_NORMAL, FP_SUBNORMAL, FP_ZERO, __x);
                                                              ^
/opt/anaconda3/bin/../include/c++/v1/math.h:388:77: error: use of undeclared identifier 'FP_ZERO'
  return __builtin_fpclassify(FP_NAN, FP_INFINITE, FP_NORMAL, FP_SUBNORMAL, FP_ZERO, __x);
                                                                            ^
/opt/anaconda3/bin/../include/c++/v1/math.h:393:21: error: use of undeclared identifier 'FP_ZERO'
  return __x == 0 ? FP_ZERO : FP_NORMAL;
                    ^
/opt/anaconda3/bin/../include/c++/v1/math.h:393:31: error: use of undeclared identifier 'FP_NORMAL'
  return __x == 0 ? FP_ZERO : FP_NORMAL;
                              ^
In file included from code.cc:3:
/opt/anaconda3/lib/python3.11/site-packages/hoomd/include/hoomd/HOOMDMath.h:249:21: error: no member named 'sqrtf' in the global namespace; did you mean 'sqrt'?
    return 1.0f / ::sqrtf(x);
                  ~~^~~~~
                    sqrt
/opt/anaconda3/bin/../include/c++/v1/math.h:929:42: note: 'sqrt' declared here
inline _LIBCPP_HIDE_FROM_ABI float       sqrt(float __x) _NOEXCEPT       {return __builtin_sqrtf(__x);}
                                         ^
In file included from code.cc:3:
/opt/anaconda3/lib/python3.11/site-packages/hoomd/include/hoomd/HOOMDMath.h:269:14: error: no member named 'sinf' in the global namespace
    return ::sinf(x);
           ~~^
/opt/anaconda3/lib/python3.11/site-packages/hoomd/include/hoomd/HOOMDMath.h:285:14: error: no member named 'cosf' in the global namespace
    return ::cosf(x);
           ~~^
/opt/anaconda3/lib/python3.11/site-packages/hoomd/include/hoomd/HOOMDMath.h:299:5: error: use of undeclared identifier '__sincosf'; did you mean 'sincos'?
    __sincosf(x, &s, &c);
    ^~~~~~~~~
    sincos
/opt/anaconda3/lib/python3.11/site-packages/hoomd/include/hoomd/HOOMDMath.h:296:24: note: 'sincos' declared here
inline HOSTDEVICE void sincos(float x, float& s, float& c)
                       ^
/opt/anaconda3/lib/python3.11/site-packages/hoomd/include/hoomd/HOOMDMath.h:299:18: error: non-const lvalue reference to type 'float' cannot bind to a temporary of type 'float *'
    __sincosf(x, &s, &c);
                 ^~
/opt/anaconda3/lib/python3.11/site-packages/hoomd/include/hoomd/HOOMDMath.h:296:47: note: passing argument to parameter 's' here
inline HOSTDEVICE void sincos(float x, float& s, float& c)
                                              ^
/opt/anaconda3/lib/python3.11/site-packages/hoomd/include/hoomd/HOOMDMath.h:311:7: error: no member named '__sincos' in the global namespace
    ::__sincos(x, &s, &c);
    ~~^
/opt/anaconda3/lib/python3.11/site-packages/hoomd/include/hoomd/HOOMDMath.h:323:5: error: use of undeclared identifier '__sincospif'; did you mean 'sincospi'?
    __sincospif(x, &s, &c);
    ^~~~~~~~~~~
    sincospi
/opt/anaconda3/lib/python3.11/site-packages/hoomd/include/hoomd/HOOMDMath.h:318:24: note: 'sincospi' declared here
inline HOSTDEVICE void sincospi(float x, float& s, float& c)
                       ^
/opt/anaconda3/lib/python3.11/site-packages/hoomd/include/hoomd/HOOMDMath.h:323:20: error: non-const lvalue reference to type 'float' cannot bind to a temporary of type 'float *'
    __sincospif(x, &s, &c);
                   ^~
/opt/anaconda3/lib/python3.11/site-packages/hoomd/include/hoomd/HOOMDMath.h:318:49: note: passing argument to parameter 's' here
inline HOSTDEVICE void sincospi(float x, float& s, float& c)
                                                ^
fatal error: too many errors emitted, stopping now
Error generating code.
20 errors generated.

Can you fix it?

We have been unable to fix it.

Tutorial description

A tutorial showing the behavior of systems under different integrators.

Section

We want each integrator showcasing each system at a high and low density and plot various physical quantities of each system.

Author

Tobias Dwyer
Josh Anderson

Update tutorials for new thermostats.

v4.0 will include a new API for thermostats: glotzerlab/hoomd-blue#1424 . Update the examples to demonstrate using this new API.

File name

00-Introducing-HOOMD-blue/07-Analyzing-Trajectories.ipynb, possibly others.

Description

PIL reports:

/var/folders/vp/8bj3q4yx63s9v1lxzm5r0kj40000gs/T/ipykernel_13283/3912975196.py:86: DeprecationWarning: ADAPTIVE is deprecated and will be removed in Pillow 10 (2023-07-01). Use Palette.ADAPTIVE instead.
  palette=PIL.Image.ADAPTIVE)

Can you fix it?

I don't have time at the moment. Feel free to submit a PR fixing this.

Initialization of randomly placed polymers

Example description

Show how using freud to generate a random arrangement of polymers with volume exclusion and creating a gsd file from the configuration.

Section

Initialization

Hard Spheres with hoomd v.3.0 API

Example description

A simple simulation of hard spheres with trajectory dumping.

Section

HPMC

Tasks

Initialize system
run system
dump output

Tutorial description

Teach users how to use walls in HPMC and MD.

Author

Contributions welcome. I will write at some point if I find the time.

Front view hides 3d nature of the system

File name

Introduction to HOOMD tutorials.

Description

The front view used in the fresnel renderings hides the 3D nature of the system. New users would understand better that the system is 3D with an isometric view.

Can you fix it?

I can fix this, but at a later time.

Tutorial description

Teach users how to run active matter simulations in HOOMD.

2D active particles
force.Active
methods.OverdampedViscous
Rotational diffusion.
Quiver plot of particle velocities.

Author

I welcome other authors to contribute.

Re-implement basic concepts as tutorial notebooks

The following concepts pages from HOOMD v2 need to be re-written as targeted tutorials, worked into the API documentation, or brought up as part of a larger introduction tutorial series:

Periodic boundary conditions
Rotational degrees of freedom
Neighbor lists
Domain decomposition
Autotuners
Restartable jobs

Use volume fraction instead of packing fraction

File name

"Introducing HOOMD-blue"

Description

The tutorial uses the term "packing fraction" where it should use "volume fraction". The tutorial does not densely pack the particles.

Can you fix it?

Yes, I will make the fix.

Update rigid bodies tutorial

Update the rigid bodies tutorial for changes on trunk-major.
glotzerlab/hoomd-blue#1433

Tutorial description

This tutorial will describe how to run patchy particle simulations in HPMC.

Section

Probably after the custom actions tutorial.

Author

I will write this tutorial.

Replace `sim` with `simulation`.

Also review tutorials for other variable names that do not match the name of the class.

This change is necessary so that user can copy and paste code from both tutorials and examples and 1) have a reasonable expectation that the pasted code will work and 2) that the name of the variable is a sufficient search term to find the class in the documentation.

Bonds, Angles, Dihedrals, Constraints

Tutorial description

Write a tutorial or series of tutorials on bonds, angles, dihedrals, and constraints.

Section

Maybe right after after "Introducing Molecular Dynamics"?

Author

I will write this tutorial.

Some examples use deprecated APIs

Description

Several examples use snapshot.exists. This needs to be replaced with snapshot.communicator.rank == 0

Can you fix it?

Contributions welcome.

hoomd-examples outline

hoomd-examples rewrite

hoomd-examples needs significant improvement to better inform users. Recognizing that users will copy and paste anything in the examples, all examples must be exemplars of research workflow best practices. The tutorials will be broken up into the following sections.

We need your help! Please review the outline below and let us know what examples you think would be useful in the documentation. I will update this description with the suggestions to complete the outline for the new HOOMD examples.

Basic tutorials

Basic tutorials introduce the user to the essential elements of a HOOMD simulation via short examples with extended descriptions. Later example scripts may assume that the user is familiar with these concepts and do not need to re-introduce them.

Introduction
Executing scripts (jupyter notebook and command line)
Introducing contexts (including cpu, gpu modes, and launching with mpirun)
Specifying the initial condition (via gsd file, also describe the commonly used per-particle properties)
MD simulations (read_gsd, nlist configuration, integrator, run)
HPMC simulations (read_gsd, integrator, run)
Log file output (analyze.log)
Trajectory output (dump.gsd)
Saving trajectory metadata (e.g. dumping MC shape information)
Visualizing trajectories (explains the fresnel visualization helper script, also links to OVITO, VMD, plato-draw)

Examples

Examples demonstrate research-relevant use cases of HOOMD with simple, easy-to-understand code along with Markdown cells that explain it and a link to the research paper. The examples should include code that initializes the system in a gsd file, including compression to the target density (if applicable), and the simulation configuration and execution. Examples should be self-contained to the extent that is possible (i.e. no reliance on signac workspaces or extensive json configurations) with parameters hard coded or specified as variables in the script. Where possible, examples should be run on a small number of particles so that a single cpu can run the example and get meaningful output in a few minutes. When possible, the example should utilize the visualization helper script to render the output trajectory and/or plot log output so that the user may adjust the notebook, rerun, and see the effect on the output.

Active rotation (https://dx.doi.org/10.1103/PhysRevLett.112.075701)
Suggest additional examples

Guides

A how-to guide notebook demonstrates a specific HOOMD feature with as succinct a script as possible along with explanatory markdown cells. There should be many short how-to guides organized into subsections on similar topics. How-to guides should show the creation of the initial gsd file where relevant. Where not relevant, they may use an initial gsd file checked into the notebook repo (or re-use an initial gsd file created by another notebook). Output (plots and/or trajectories) must be examined so that the user may change parameters in the notebook and re-run to see the effect.

Tabulated pair potential
What HOOMD features would you like to see guides for?

External tools

Notebooks in the external tools section demonstrate how to use HOOMD in conjunction tools such as (but not limited to) signac, mbuild, and freud.

What tools would you like to use HOOMD with?

Generate a Random Configuration

Example description

Show how using freud to generate a random arrangement of particles with volume exclusion and creating a gsd file from the configuration.

Section

Initialization

AttributeError: module 'hoomd' has no attribute 'device'

I have installed hoomd using conda as follows:
conda install -c conda-forge fresnel freud gsd hoomd jupyterlab matplotlib

However, while trying to access the device in the notebooks (cpu = hoomd.device.CPU()), I get the following error:
AttributeError: module 'hoomd' has no attribute 'device'

hoomd.version
'2.9.6'

How do I resolve this issue? Thanks.

Tutorial: Plotting interaction potentials

Tutorial description

Show users how to use the HOOMD API to plot potentials, forces, and torques from particle-particle interactions. Users will then have the skills needed to confirm the potentials are computed as they expect.

Examples could include MD pair and bond potentials (V(r)), potentials between two rigid bodies (V(x,y,theta)), and possibly HPMC patch potentials as well.

The MD potentials could use ConstantVelocity (glotzerlab/hoomd-blue#1520) to map out the potential with fewer calls to run(). It should also demonstrate that one can also use dt=0, and sim.run(1) and explain why sim.run(0) does not work.

Author

I plan to write this at some point.

Update fresnel / document supported versions

File name

I had issues running the latest build of fresnel (with API changes newer than 0.12). The specific issues were with cameras, orthographic vs. Orthographic.

To fix

Document supported fresnel version numbers.
When the next release of fresnel comes out, an update will be needed.

Can you fix it?

I'm currently filing a lot of issues and am not able to commit to fixing all of them at this time.

Write MPI tutorial

Description

Write a core HOOMD tutorial that explains how to work with MPI in simulations.

Motivation and context

Users need to understand how to execute simulations with MPI.

Tutorial: Bead spring polymers

Tutorial description

Teach users how to run simulations of bead spring polymers.

Initialization (bonds, angles).
Compression.
Exclusions.
Pair and bond forces.

Author

Contributions welcome. I plan to write this when time permits.

glotzerlab / hoomd-examples Goto Github PK

hoomd-examples's Introduction

HOOMD-blue tutorials

Outline

Executing the tutorials

Prerequisites

hoomd-examples's People

Contributors

Stargazers

Watchers

Forkers

hoomd-examples's Issues

File name

Description

Can you fix it?

Tutorial description

Section

Author

Example description

Section

Description

File name

Description

Can you fix it?

Tutorial description

Section

Author

File name

Description

Can you fix it?

Example description

Section

Example description

Section

Tasks

Tutorial description

Author

File name

Description

Can you fix it?

Tutorial description

Author

File name

Description

Can you fix it?

Tutorial description

Section

Author

Tutorial description

Section

Author

Description

Can you fix it?

hoomd-examples rewrite

Basic tutorials

Examples

Guides

External tools

Example description

Section

Tutorial description

Author

File name

To fix

Can you fix it?

Description

Motivation and context

Tutorial description

Author

Recommend Projects

Recommend Topics

Recommend Org