From ee2bc7ca421b8ac368d9177998b1062ef2149c8f Mon Sep 17 00:00:00 2001 From: Mikael Lund Date: Tue, 1 Jan 2019 12:06:45 +0000 Subject: [PATCH] manual update; anaconda: openmpi->mpich on osx target --- CMakeLists.txt | 8 +++--- LICENSE | 2 +- README.md | 11 ++------ docs/_docs/docs.md | 6 ++++- docs/_docs/energy.md | 2 +- docs/_docs/install.md | 44 ++++++++++++++++++++------------ docs/_docs/moves.md | 19 ++++++++++---- docs/_docs/running.md | 15 ++++++++--- docs/_docs/topology.md | 22 +++++++++++----- scripts/meta.yaml | 4 +-- src/atomdata.cpp | 5 ---- src/faunus.cpp | 6 ----- src/{tests.cpp => unittests.cpp} | 0 13 files changed, 84 insertions(+), 60 deletions(-) rename src/{tests.cpp => unittests.cpp} (100%) diff --git a/CMakeLists.txt b/CMakeLists.txt index 15d683bd6..58b003780 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -258,10 +258,10 @@ endif() add_library(libfaunus STATIC ${objs} ${hdrs}) add_dependencies(libfaunus modernjson doctest eigen range-v3 docopt xdrfile progressbar pybind11) -add_executable(tests EXCLUDE_FROM_ALL src/tests.cpp ${hdrs}) -add_dependencies(tests modernjson doctest eigen range-v3) -target_link_libraries(tests libfaunus xdrfile ${LINKLIBS}) -add_test(NAME tests COMMAND tests) +add_executable(unittests src/unittests.cpp ${hdrs}) +add_dependencies(unittests modernjson doctest eigen range-v3) +target_link_libraries(unittests libfaunus xdrfile ${LINKLIBS}) +add_test(NAME unittests COMMAND unittests) add_executable(faunus src/faunus.cpp) add_dependencies(faunus modernjson doctest eigen range-v3 docopt xdrfile progressbar) diff --git a/LICENSE b/LICENSE index e2acaa92c..edc217c34 100644 --- a/LICENSE +++ b/LICENSE @@ -1,6 +1,6 @@ MIT License -Copyright (c) 2018 Mikael Lund +Copyright (c) 2019 Mikael Lund Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal diff --git a/README.md b/README.md index 272acb3e8..829cc2986 100644 --- a/README.md +++ b/README.md @@ -24,14 +24,7 @@ On macOS or Linux, install using [conda](https://conda.io/miniconda.html): conda install -c teokem faunus -Or build from source: - -~~~ bash - git clone https://github.com/mlund/faunus.git - cd faunus - cmake . - make -~~~ +Or build from source, see [here](http://mlund.github.io/faunus/docs/install/). Documentation ============= @@ -41,7 +34,7 @@ http://mlund.github.io/faunus Licence ======= -Copyright 2002-2018 Mikael Lund +Copyright 2002-2019 Mikael Lund Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, diff --git a/docs/_docs/docs.md b/docs/_docs/docs.md index 38e8825de..80e6041c0 100644 --- a/docs/_docs/docs.md +++ b/docs/_docs/docs.md @@ -50,7 +50,9 @@ yason.py minimal.yml | faunus produces an output file, `out.json`, with move statistics, system properties etc. The script `yason.py` merely converts from YAML to JSON as the former, easier to read, is used in all examples. -For more examples, see the `examples` folder. +For more examples, see the [`examples` folder](https://github.com/mlund/faunus/tree/master/examples). + +## Getting Help To open the user-guide in a browser, type: @@ -58,3 +60,5 @@ To open the user-guide in a browser, type: faunus-manual ~~~ +If you have questions, comments, or need help, create a ticket on [our Github issue page](https://github.com/mlund/faunus/issues). + diff --git a/docs/_docs/energy.md b/docs/_docs/energy.md index 4dd4bb2e2..059f6c050 100644 --- a/docs/_docs/energy.md +++ b/docs/_docs/energy.md @@ -384,7 +384,7 @@ energy: - harmonic: { index: [56,921], k: 10, req: 15 } moleculelist: - water: # TIP3P - structure: water.xyz + structure: "water.xyz" bondlist: # index relative to molecule - harmonic: { index: [0,1], k: 5024, req: 0.9572 } - harmonic: { index: [0,2], k: 5024, req: 0.9572 } diff --git a/docs/_docs/install.md b/docs/_docs/install.md index ed40b733e..5b134af70 100644 --- a/docs/_docs/install.md +++ b/docs/_docs/install.md @@ -40,10 +40,10 @@ but should compile on most unix operating systems and possibly under Cygwin (Win The following are optional: -- Message Passing Interface (MPI) - `pandoc` - `pypandoc` - `BeautifulSoup4` +- Message Passing Interface (MPI) **macOS tip:** Apple's developer tools, Xcode, is a quick way obtain @@ -58,17 +58,20 @@ clang on macOS. CMake can be installed with an Download the [latest release](https://github.com/mlund/faunus/releases/latest) or [the developer branch](https://github.com/mlund/faunus/archive/master.zip) -and perform the following steps in a terminal. -Dependencies will automatically be downloaded. +and perform the following steps in a terminal: ~~~ bash cd faunus cmake . [OPTIONS] -make faunus -make usagetips # optional, requires `pandoc`, `pypandoc`, `BeautifulSoup4` +make +make test +make manual_html # requires `pandoc` +make usagetips # requires `pandoc`, `pypandoc`, `BeautifulSoup4` make install ~~~ +For merely building the Faunus executable, use `make faunus` after the `cmake` command. + The following options are available: CMake Option | Description @@ -85,10 +88,27 @@ CMake Option | Description `-DPYTHON_INCLUDE_DIR="..."` | Full path to python headers `-DPYTHON_LIBRARY="..."` | Full path to python library, i.e. libpythonX.dylib/so +### Compiling the Manual + +Pandoc is required to build the HTML manual: + +~~~ bash +make manual_html +~~~ + +In addition to pandoc, a TeX Live installation is required to build +the PDF manual. Garamond fonts must be available: + +~~~ bash +wget https://tug.org/fonts/getnonfreefonts/install-getnonfreefonts +sudo texlua install-getnonfreefonts +sudo getnonfreefonts garamond --sys +make manual +~~~ ### Python libraries in odd locations -Should there are multiple compilers or python distributions, be specific: +Should there be multiple compilers or python distributions, be specific: ~~~ bash CC=/opt/bin/clang CXX=/opt/bin/clang++ cmake . \ @@ -115,7 +135,7 @@ make clean rm -fR CMakeCache.txt CMakeFiles ~~~ -## Creating a conda package (advanced usage) +## Creating a conda package (development usage) The basic steps for creating a conda package is outlined below, albeit details depend on the build environment. See also the `.travis.yml` @@ -136,13 +156,3 @@ Instead of uploading to anaconda.org, install a local copy directly after the bu conda install -c USER faunus --use-local ~~~ -### Requirements - -Building a conda package may require a TeX Live installation to create -the PDF manual. Ensure that Garamond fonts are available: - -~~~ bash -wget https://tug.org/fonts/getnonfreefonts/install-getnonfreefonts -sudo texlua install-getnonfreefonts -sudo getnonfreefonts garamond --sys -~~~ diff --git a/docs/_docs/moves.md b/docs/_docs/moves.md index e22b6130d..589be6cde 100644 --- a/docs/_docs/moves.md +++ b/docs/_docs/moves.md @@ -210,21 +210,30 @@ The table below explains the scaling behavior in different geometries: `xy` | `cuboid` | Scales xy, z untouched. `isochoric` | `cuboid` | Scales xy/z, const. volume -**Note:** +**Warning:** Untested for cylinders, slits. -{: .notice--info} +{: .notice--warning} -## Speciation / Grand Canonical +## Speciation / Grand Canonical (beta) -The speciation move handles density fluctuations and particle transformations and is the main move for particle insertion, deletion, and swapping used in (semi)-grand canonical ensembles. +The speciation move handles density fluctuations and particle transformations and is the main move +for particle insertion, deletion, and swapping used in (semi)-grand canonical ensembles. A reaction from `reactionlist` is randomly picked from the topology and is either propagated forward or backwards. In Faunus, the total number of atoms and molecules are constant, but these can be either _active_ or _inactive_. Deleting a molecule simply deactivates it, while insertion _vice versa_ activates an inactive molecule. -Thus, it is important that the _capacity_ or reservoir of particles (active plus inactive) is sufficiently large to allow for fluctuations. This is ensured using `insertmolecules` (see Topology). A runtime warning will be given, should you run low on particles. +Thus, it is important that the _capacity_ or reservoir of particles (active plus inactive) is +sufficiently large to allow for fluctuations. +This is ensured using `insertmolecules` (see Topology). +A runtime warning will be given, should you run low on particles. For more information about reactions, see the Topology section. `speciation` | Description --------------- | ---------------------------------- `repeat=1` | Average number of moves per sweep + +**Warning:** +The speciation move is under construction and subject to change. +{: .notice--warning} + diff --git a/docs/_docs/running.md b/docs/_docs/running.md index b1258e025..cc903174d 100644 --- a/docs/_docs/running.md +++ b/docs/_docs/running.md @@ -63,6 +63,12 @@ import json with open('out.json') as f: d = json.load(f) # --> dict print( d['atomlist'][0]["Na+"]["mw"] ) # --> 22.99 + # ^ ^ ^ ^ + # | | | | + # | | | get mol. weight value + # | | key is the atom name + # | fist object in array + # atomlist is an array of objects ~~~ ## Restarting @@ -74,11 +80,14 @@ To start from the previously saved state, use: faunus --input in.json --state state.json ~~~ -## Message Passing Interface +## Message Passing Interface (MPI) + +Only few routines in Faunus are currently parallelisable using MPI, for example +parallel tempering, and penalty function energies. Running with MPI spawns `nproc` processes that may or may not communicate with each other. If `nproc>1`, input and output files are prefixed with -`mpi{rank}.` where `{rank}` is the rank or process number. +`mpi{rank}.` where `{rank}` is the rank or process number, starting from zero. The following starts two processes, reading input from `mpi0.in.json` and `mpi1.in.json`. All output files, including those from any analysis are @@ -106,5 +115,5 @@ help(pyfaunus) For more examples, see [`pythontest.py`](https://github.com/mlund/faunus/blob/master/examples/pythontest.py). -Please note that the interface is under development and subject to change. +Note that the interface is under development and subject to change. diff --git a/docs/_docs/topology.md b/docs/_docs/topology.md index 5bf6f743e..5b9c3f2ac 100644 --- a/docs/_docs/topology.md +++ b/docs/_docs/topology.md @@ -37,11 +37,11 @@ Origo ($0,0,0$) is always placed in the geometric _center_ of the simulation con `geometry` | PBC | Required keywords ---------- | -------- | -------------------------------------- -type: | | +`type`: | | `cuboid` | $x,y,z$ | `length` (array or single float) `slit` | $x,y$ | `length` (array or single float) `cylinder` | $z$ | `radius`, `length` (along $z$) -`sphere` | off | `radius` +`sphere` | none | `radius` ## Atom Properties @@ -54,7 +54,8 @@ Atoms are the smallest possible particle entities with properties defined below. `dp=0` | Translational displacement parameter [Å] `dprot=0` | Rotational displacement parameter [degrees] (will be converted to radians) `eps=0` | Epsilon energy scaling commonly used for Lennard-Jones interactions etc. [kJ/mol] -`mu=[0,0,0]` | Dipole moment vector [Debye] +`mu=[1,0,0]` | Dipole moment unit vector +`mulen=0` | Dipole moment scalar [eÅ] `mw=1` | Molecular weight [g/mol] `q=0` | Valency / partial charge number [$e$] `r=0` | Radius = `sigma/2` [Å] @@ -76,17 +77,22 @@ atomlist: - ... ~~~ +### Anisotropic Atoms + +By default, Faunus is currently compiled with centro-symmetric atoms, only. To add _i.e._ dipolar properties, modify the particle definition at the top of `src/faunus.cpp`. + + ## Molecule Properties A molecule is a collection of atoms, but need not be associated as real molecules. Two particular modes can be specified: 1. If `atomic=true` the atoms in the molecule are unassociated and is - typically used to defined salt particles or any other non-aggregated + typically used to define salt particles or other non-aggregated species. No structure is required, and the molecular center of mass (COM) is unspecified. -2. If `atomic=false` the molecule resembles a real molecule and a structure +2. If `atomic=false` the molecule resembles a real molecule and a structure or trajectory is _required_. Properties of molecules and their default values: @@ -176,7 +182,7 @@ container boundaries. Overlap between particles is ignored and for i.e. hard-sphere potentials the initial energy may be infinite. -## Equilibrium Reactions +## Equilibrium Reactions (beta) Faunus supports density fluctuations, coupled to chemical equilibria with explicit and/or implicit particles via their chemical potentials as @@ -205,3 +211,7 @@ Available keywords: --------------- | --------------------------------------------------------------- `lnK`/`pK` | Molar equilibrium constant either as $\ln K$ or $-\log_{10}(K)$ +**Warning:** +This functionality is under construction and subject to change. +{: .notice--warning} + diff --git a/scripts/meta.yaml b/scripts/meta.yaml index 325d0cad4..d161154ef 100644 --- a/scripts/meta.yaml +++ b/scripts/meta.yaml @@ -36,12 +36,12 @@ requirements: - pandoc 2.* - pypandoc 1.* - beautifulsoup4 - - openmpi 1.6.3 # [osx] + - mpich 3.2.* # [osx] - openmpi 3.1.* # [linux64] - llvm-openmp # [osx] run: - llvm-openmp # [osx] - - openmpi 1.6.3 # [osx] + - mpich 3.2.* # [osx] - openmpi 3.1.* # [linux64] - ruamel_yaml - pygments diff --git a/src/atomdata.cpp b/src/atomdata.cpp index ab816b09f..6dc8562dc 100644 --- a/src/atomdata.cpp +++ b/src/atomdata.cpp @@ -30,11 +30,6 @@ namespace Faunus { for (auto it : j.items()) { a.name = it.key(); xjson val = it.value(); - //assertKeys(val, { - // "activity", "alphax", "q", "dp", "dprot", "eps", "id", - // "mu", "mulen", "scdir", "sclen", "mw", "sigma", - // "r", "tension", "tfe", "hydrophobic" - // }); // throw exception if keys other than these are given a.activity = val.value("activity", a.activity) * 1.0_molar; a.alphax = val.value("alphax", a.alphax); a.charge = val.value("q", a.charge); diff --git a/src/faunus.cpp b/src/faunus.cpp index cad28b52f..9db60d33c 100644 --- a/src/faunus.cpp +++ b/src/faunus.cpp @@ -14,13 +14,7 @@ using namespace std; #define FAUNUS_TIPSFILE "" #endif -#ifdef FAUNUS_CUBOID_NOPBC -typedef Geometry::CuboidNoPBC Tgeometry; -#elif FAUNUS_SPHERE -typedef Geometry::Sphere Tgeometry; -#else typedef Geometry::Chameleon Tgeometry; -#endif typedef Particle Tparticle; static const char USAGE[] = diff --git a/src/tests.cpp b/src/unittests.cpp similarity index 100% rename from src/tests.cpp rename to src/unittests.cpp