Document pseudoatoms

docs/src/crystal.md

@@ -61,21 +61,10 @@ For many simulations, one needs to replicate the unit cell multiple times to cre
 ```jldoctest crystal
 super_xtal = replicate(xtal, (2,2,2))       # Replicates the original unit cell once in each dimension
 # output
-Name: SBMOF-1.cif
-Bravais unit cell of a crystal.
-	Unit cell angles α = 90.000000 deg. β = 100.897000 deg. γ = 90.000000 deg.
-	Unit cell dimensions a = 23.238600 Å. b = 11.133400 Å, c = 45.862400 Å
-	Volume of unit cell: 11651.776815 ų
-
-	# atoms = 960
-	# charges = 960
-	chemical formula: Ca₃₂C₄₄₈H₂₅₆O₁₉₂S₃₂
-	space Group: P1
-	symmetry Operations:
-		'x, y, z'
-	bonding graph:
-		# vertices = 960
-		# edges = 0
+Crystal(Ca₃₂C₄₄₈H₂₅₆O₁₉₂S₃₂, periodic = TTT):
+    bounding_box      : [ 23.2386        0        0;
+                         6.81724e-16  11.1334        0;
+                         -8.67001 3.33915e-15  45.0354]u"Å"
 ```
 
 ## finding other properties

docs/src/index.md

@@ -1,35 +1,35 @@
-![PorousMaterials.jl](assets/PMlogo.png)
-A pure-[Julia](https://julialang.org/) package for classical molecular modeling of adsorption in porous crystals such as metal-organic frameworks (MOFs).
-
-🔨 Compute the potential energy of a molecule at particular position and orientation inside of a porous crystal
-
-🔨 Write a potential energy grid of a molecule inside a porous material to visualize binding sites
-
-🔨 Compute the Henry coefficient of a gas in a porous crystal
-
-🔨 Run grand-canonical Monte Carlo simulations of gas adsorption in a porous crystal
-
-Designed for high-throughput computations to minimize input files and querying results from output files. User-friendly. Instructive error messages thrown when they should be. Well-documented. Easy to install.
-
-*In development, please contribute, post issues 🐛, and improve!*
-
-## Installation
-
-1. Download and install the [Julia programming language](https://julialang.org/), v1.5 or higher.
-
-2. In Julia, open the package manager (using `]`) and enter the following:
-
-```julia
-pkg> add PorousMaterials
-```
-
-3. In Julia, load all functions in `PorousMaterials.jl` into the namespace:
-
-```julia
-julia> using PorousMaterials # that's it
-```
-
-## Tests
-Run the tests in the script `tests/runtests.jl` manually or by `] test PorousMaterials` in the Julia REPL.
-
-Direct tests for Henry coefficients and grand-canonical Monte Carlo simulations take much longer and must be run separately; they are found in `tests/henry.jl` and `tests/gcmc_long.jl`.
+![PorousMaterials.jl](assets/PMlogo.png)
+A pure-[Julia](https://julialang.org/) package for classical molecular modeling of adsorption in porous crystals such as metal-organic frameworks (MOFs).
+
+🔨 Compute the potential energy of a molecule at particular position and orientation inside of a porous crystal
+
+🔨 Write a potential energy grid of a molecule inside a porous material to visualize binding sites
+
+🔨 Compute the Henry coefficient of a gas in a porous crystal
+
+🔨 Run grand-canonical Monte Carlo simulations of gas adsorption in a porous crystal
+
+Designed for high-throughput computations to minimize input files and querying results from output files. User-friendly. Instructive error messages thrown when they should be. Well-documented. Easy to install.
+
+*In development, please contribute, post issues 🐛, and improve!*
+
+## Installation
+
+1. Download and install the [Julia programming language](https://julialang.org/), v1.5 or higher.
+
+2. In Julia, open the package manager (using `]`) and enter the following:
+
+```julia
+pkg> add PorousMaterials
+```
+
+3. In Julia, load all functions in `PorousMaterials.jl` into the namespace:
+
+```julia
+julia> using PorousMaterials # that's it
+```
+
+## Tests
+Run the tests in the script `tests/runtests.jl` manually or by `] test PorousMaterials` in the Julia REPL.
+
+Direct tests for Henry coefficients and grand-canonical Monte Carlo simulations take much longer and must be run separately; they are found in `tests/henry.jl` and `tests/gcmc_long.jl`.

docs/src/molecule.md

@@ -8,7 +8,13 @@ end
 
 ## Loading Molecule Files
 
-Molecule input files are stored in `PorousMaterials.PATH_TO_MOLECULES`. Each molecule possesses its own directory containing two files: `charges.csv` and `atoms.csv`, comma-separated-value files, which describe the point charges and Lennard Jones spheres, respectively, that compose the molecule. Only rigid molecules are currently supported. Units of length are in Angstroms ($\AA$); units of charges are electrons.
+Molecule input files are stored in the path indicated by the `Xtals`/`PorousMaterials` global dictionary `rc`. 
+
+```julia
+rc[:paths][:molecules] # absolute or relative path
+```
+
+Each molecule possesses its own directory containing two files: `charges.csv` and `atoms.csv`, comma-separated-value files, which describe the point charges and Lennard Jones spheres, respectively, that compose the molecule. Only rigid molecules are currently supported. Units of length are in Angstroms ($\AA$); units of charges are electrons.
 
 ```jldoctest molecule
 molecule = Molecule("CO2")
@@ -40,6 +46,56 @@ Charges{Cart}(3, [0.7, -0.35, -0.35], Cart([0.0 -1.16 1.16; 0.0 0.0 0.0; 0.0 0.0
 
 To see specific information about the atoms and charges attributes of the molecule see [`Atoms`](@ref) and [`Charges`](@ref).
 
+## Pseudo-Atoms
+
+Sometimes, [e.g. modeling quadrupolar molecules](https://github.com/SimonEnsemble/PorousMaterials.jl/issues/236), it is desirable to add a point charge in a location outside of any atomic nucleus.
+In order to do this, a pseudo-atom label must be chosen (consistent with input data) and added to the global list of atomic masses.
+
+Take the example of using [TraPPE](https://doi.org/10.1002/aic.690470719)-derived charges for the dinitrogen molecule.
+Partial negative charges are assigned to the nitrogen atoms and a corresponding positive charge is placed at a pseudo-atom "dummy site" at the center of mass.
+The atoms and charges input data for this "N2_TraPPE" molecule are like so:
+
+```jldoctest molecule
+dir = joinpath(rc[:paths][:molecules], "N2_TraPPE")
+for file in readdir(dir)
+  @info file data=String(read(joinpath(dir, file)))
+end
+# output
+┌ Info: atoms.csv
+└   data = "atom,x,y,z\nN_in_N2,0,0,0.55\nPSEUDOATOM_LABEL,0,0,0\nN_in_N2,0,0,-0.55"
+┌ Info: charges.csv
+└   data = "q,x,y,z\n-0.482,0,0,0.55\n0.964,0,0,0\n-0.482,0,0,-0.55"
+```
+
+**atoms.csv**
+
+```
+atom,x,y,z
+N_in_N2,0,0,0.55
+PSEUDOATOM_LABEL,0,0,0
+N_in_N2,0,0,-0.55
+```
+
+**charges.csv**
+
+```
+q,x,y,z
+-0.482,0,0,0.55
+0.964,0,0,0
+-0.482,0,0,-0.55
+```
+
+In this example, `PSEUDOATOM_LABEL` is the label for the pseudo-atom; there are several common choices, so make sure you know which one is used in your particular data!
+
+Before loading these data by calling `Molecule`, we need to add our (massless) pseudo-atom to the mass dictionary:
+
+```juliadoctest
+rc[:atomic_masses][:PSEUDOATOM_LABEL] = 0.
+Molecule("N2_TraPPE")
+# ouput
+asdf
+```
+
 ## Moving Molecules
 We can translate and roatate a molecule:
 

test/data/molecules/N2_TraPPE/atoms.csv

@@ -0,0 +1,4 @@
+atom,x,y,z
+N_in_N2,0,0,0.55
+PSEUDOATOM_LABEL,0,0,0
+N_in_N2,0,0,-0.55

test/data/molecules/N2_TraPPE/charges.csv

@@ -0,0 +1,4 @@
+q,x,y,z
+-0.482,0,0,0.55
+0.964,0,0,0
+-0.482,0,0,-0.55