Merge pull request #53 from ArnoStrouwen/master

ChrisRackauckas · web-flow · commit a2cbe23706ba · 2022-06-08T22:47:08.000-04:00
add docs
diff --git a/.github/workflows/Documentation.yml b/.github/workflows/Documentation.yml
@@ -0,0 +1,25 @@
+name: Documentation
+
+on:
+  push:
+    branches:
+      - master
+      - 'release-'
+    tags: '*'
+  pull_request:
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - uses: julia-actions/setup-julia@latest
+        with:
+          version: '1'
+      - name: Install dependencies
+        run: julia --project=docs/ -e 'using Pkg; Pkg.develop(PackageSpec(path=pwd())); Pkg.instantiate()'
+      - name: Build and deploy
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} # For authentication with GitHub Actions token
+          DOCUMENTER_KEY: ${{ secrets.DOCUMENTER_KEY }} # For authentication with SSH deploy key
+        run: julia --project=docs/ docs/make.jl
diff --git a/README.md b/README.md
diff --git a/docs/.gitignore b/docs/.gitignore
@@ -0,0 +1,2 @@
+build/
+site/
diff --git a/docs/Project.toml b/docs/Project.toml
@@ -0,0 +1,6 @@
+[deps]
+Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
+NBodySimulator = "0e6f8da7-a7fc-5c8b-a220-74e902c310f9"
+
+[compat]
+Documenter = "0.27"
diff --git a/docs/make.jl b/docs/make.jl
@@ -0,0 +1,19 @@
+using Documenter, NBodySimulator
+
+include("pages.jl")
+
+makedocs(
+    sitename="NbodySimulator.jl",
+    authors="Chris Rackauckas",
+    modules=[NBodySimulator],
+    clean=true,doctest=false,
+    format = Documenter.HTML(analytics = "UA-90474609-3",
+                             assets = ["assets/favicon.ico"],
+                             canonical="https://nbodysimulator.sciml.ai/stable/"),
+    pages=pages
+)
+
+deploydocs(
+   repo = "github.com/SciML/NBodySimulator.jl.git";
+   push_preview = true
+)
diff --git a/docs/pages.jl b/docs/pages.jl
@@ -0,0 +1,7 @@
+# Put in a separate page so it can be used by SciMLDocs.jl
+
+pages=[
+    "Home" => "index.md",
+    "examples.md",
+    "nbodysimulator.md"
+]
diff --git a/docs/src/assets/favicon.ico b/docs/src/assets/favicon.ico
diff --git a/docs/src/assets/logo.png b/docs/src/assets/logo.png
diff --git a/docs/src/examples.md b/docs/src/examples.md
@@ -0,0 +1,3 @@
+# Examples
+
+Further examples can be found [here](https://github.com/SciML/NBodySimulator.jl/tree/master/examples).
diff --git a/docs/src/index.md b/docs/src/index.md
diff --git a/docs/src/nbodysimulator.md b/docs/src/nbodysimulator.md
@@ -0,0 +1,68 @@
+# API
+
+## Simulation
+```@docs
+NBodySimulation
+run_simulation
+```
+
+## Bodies
+```@docs
+NBodySimulator.Body
+MassBody
+ChargedParticle
+MagneticParticle
+generate_bodies_in_cell_nodes
+```
+
+## Potentials
+```@docs
+PotentialParameters
+NBodySimulator.get_accelerating_function
+GravitationalParameters
+MagnetostaticParameters
+ElectrostaticParameters
+LennardJonesParameters
+SPCFwParameters
+```
+
+## Thermostats
+```@docs
+NBodySimulator.Thermostat
+NBodySimulator.NullThermostat
+AndersenThermostat
+BerendsenThermostat
+NoseHooverThermostat
+LangevinThermostat
+```
+### Boundary Conditions
+```@docs
+CubicPeriodicBoundaryConditions
+PeriodicBoundaryConditions
+InfiniteBox
+```
+
+## Systems
+```@docs
+PotentialNBodySystem
+GravitationalSystem
+WaterSPCFw
+```
+
+# Analyze
+```@docs
+NBodySimulator.SimulationResult
+temperature
+rdf
+msd
+initial_energy
+kinetic_energy
+potential_energy
+total_energy
+```
+
+# Protein Database File
+```@docs
+load_water_molecules_from_pdb
+save_to_pdb
+```
diff --git a/src/basic_potentials.jl b/src/basic_potentials.jl
@@ -1,3 +1,6 @@
+"""
+The potentials or force field determines the interaction of particles and, therefore, their acceleration.
+"""
 abstract type PotentialParameters
 end
 
diff --git a/src/bodies.jl b/src/bodies.jl
@@ -5,7 +5,9 @@ DiffEqBase.@def position_velocity_mass begin
     v::SVector{3,cType}
     m::mType
 end
-
+"""
+Bodies or Particles are the objects which will interact with each other and for which the equations of Newton's 2nd law are solved during the simulation process.
+"""
 abstract type Body
 end
 
@@ -28,7 +30,9 @@ struct WaterMolecule <: Body
     H1::MassBody
     H2::MassBody
 end
-
+"""
+Places similar particles in the nodes of a cubic cell with their velocities distributed in accordance with the Maxwell–Boltzmann law
+"""
 function generate_bodies_in_cell_nodes(n::Int, m::Real, v_dev::Real, L::Real; rng=MersenneTwister(n))
     velocities = v_dev * randn(rng, Float64, (3, n))
     bodies = MassBody[]
diff --git a/src/nbody_simulation.jl b/src/nbody_simulation.jl
@@ -8,9 +8,11 @@ include("./nbody_system.jl")
 
 const kb_SI = 1.38e-23 # J/K
 
-# This structure defines conditions under which we test our system of N-bodies.
-# With this wrapping we can make such fields as `boundary_conditions` necessary for every simulation
-# while allowing one to describe a particular system of N interacting particles.
+"""
+Simulation is an entity determining parameters of the experiment:
+time span of simulation, global physical constants, borders of the simulation cell, external magnetic or electric fields, etc.
+The required arguments for NBodySImulation constructor are the system to be tested and the time span of the simulation.
+"""
 struct NBodySimulation{sType <: NBodySystem,bcType <: BoundaryConditions,tType <: Real,thermType <: Thermostat}
     system::sType
     tspan::Tuple{tType,tType}
diff --git a/src/nbody_simulation_result.jl b/src/nbody_simulation_result.jl
@@ -1,5 +1,7 @@
-# SimulationResult sould provide an interface for working with properties of a separate particle
-# and with physical properties of the whole system.
+"""
+SimulationResult sould provide an interface for working with properties of a separate particle
+and with physical properties of the whole system.
+"""
 struct SimulationResult{sType <: NBodySystem}
     solution::DiffEqBase.AbstractTimeseriesSolution
     simulation::NBodySimulation{sType}
@@ -281,6 +283,9 @@ function initial_energy(simulation::NBodySimulation)
     return potential_energy(u0, simulation) + kinetic_energy(v0, ms)
 end
 
+"""
+Run the N-body simulation.
+"""
 function run_simulation(s::NBodySimulation, args...; kwargs...)
     if s.thermostat isa LangevinThermostat
         calculate_simulation_sde(s, args...; kwargs...)
@@ -619,7 +624,9 @@ function load(f::File{format"ProteinDataBank"})
         extract_from_pdb(s)
     end
 end
-
+"""
+Molecules for the SPC/Fw water model can be imported from a PDB file.
+"""
 function load_water_molecules_from_pdb(path_str)
     open(path_str) do file
         extract_from_pdb(file)
diff --git a/src/nbody_system.jl b/src/nbody_system.jl
@@ -1,3 +1,7 @@
+"""
+Bodies or Particles are the objects which will interact with each other
+and for which the equations of Newton's 2nd law are solved during the simulation process.
+"""
 abstract type NBodySystem
 end
 
@@ -24,24 +28,29 @@ struct PotentialNBodySystem{bType <: Body} <: NBodySystem
     bodies::Vector{bType}
     potentials::Dict{Symbol,<:PotentialParameters}
 end
-
+"""
+Structure that represents systems with a custom set of potentials.
+In other words, the user determines the ways in which the particles are allowed to interact.
+One can pass the bodies and parameters of interaction potentials into that system.
+In the case the potential parameters are not set, the particles will move at constant velocities without acceleration during the simulation.
+"""
 function PotentialNBodySystem(bodies::Vector{<:Body}; potentials::Vector{Symbol}=[])
 
     paramteres = Dict{Symbol,PotentialParameters}()
-    
+
     if :lennard_jones ∈ potentials
         paramteres[:lennard_jones] = LennardJonesParameters()
     end
 
-    if :electrostatic ∈ potentials 
+    if :electrostatic ∈ potentials
         paramteres[:electrostatic] = ElectrostaticParameters()
     end
 
-    if :gravitational ∈ potentials   
+    if :gravitational ∈ potentials
         paramteres[:gravitational] = GravitationalParameters()
     end
 
-    if :magnetostatic ∈ potentials   
+    if :magnetostatic ∈ potentials
         paramteres[:magnetostatic] = MagnetostaticParameters()
     end
 
diff --git a/src/thermostats.jl b/src/thermostats.jl
@@ -1,6 +1,11 @@
+"""
+Usually, during the simulation, a system is required to be at a particular temperature. NBodySimulator contains several thermostats for that purpose.
+"""
 abstract type Thermostat
 end
-
+"""
+No thermostat.
+"""
 struct NullThermostat <: Thermostat
 end
 

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+# Examples`
	`2`	`+`
	`3`	`+Further examples can be found [here](https://github.com/SciML/NBodySimulator.jl/tree/master/examples).`