Editing paper and documentation

docs/paper.md

@@ -92,33 +92,33 @@ bibliography: paper.bib
 
 # Summary
 
-How neutrons move through space, direction of travel, energy, and time is important in modeling inertial confinement fusion systems, pulsed neutron sources, and nuclear criticality safety experiments, etc.
+How neutrons move through space, angle, energy, and time is important in modeling inertial confinement fusion systems, pulsed neutron sources, and nuclear criticality safety experiments, etc.
 This can be modeled with a Monte Carlo simulation, wherein particles with an associated statistical importance are spawned and transported to produce a particle history [@lewis_computational_1984].
-The specific set of events that occur within their history as well as their path are governed by pseudo-random numbers, known probabilities (from things like material data), and known geometries.
+A particle's path and the specific set of events that occur within its history are governed by pseudo-random numbers, known probabilities (*e.g.*, from material data), and known geometries.
 Information about how particles move and/or interact with the system are tallied to construct a histogram solution of parameters of interest with an associated statistical error from the Monte Carlo process. 
-When moving to dynamic simulations novel numerical methods are required to compute a solution performantly.
+When simulating dynamic systems, novel numerical methods are required to performantly compute a solution.
 We designed Monte Carlo / Dynamic Code (`MC/DC`) to explore these novel numerical methods on modern high performance compute systems.
-We avoid the need of a compiled or domain specific language by use of the Numba compiler for Python to accelerate and abstract our compute kernels to near compiled code speeds.
-Using this scheme we have implemented many novel algorithms, and in some verification tests we approach the performance of industry standard codes at the tens of thousands of processors scale.
+We avoid the need of a compiled or domain specific language by using the Numba compiler for Python to accelerate and abstract our compute kernels to near compiled code speeds.
+We have implemented many novel algorithms using this scheme, and in some verification tests have approached the performance of industry-standard codes at the scale of tens of thousands of processors.
 
 # Statement of need
 
 `MC/DC` is a performant rapid methods development platform for novel dynamic neutron transport algorithms on modern high performance compute systems.
 It uses the Numba compiler for Python to compile compute kernels to a desired hardware target, including support for graphics processing units (GPUs) [@lam_numba_2015].
-`MC/DC` uses `mpi4py` to gain distributed memory parallelism [@mpi4py_2021] and has run at the tens of thousands of processors scale [@variansyah_mc23_mcdc].
-These acceleration and abstraction techniques allow for `MC/DC` developers to remain in a pure Python development environment without need to support compiled or domain specific languages. 
-This has allowed `MC/DC` to grow from nothing to supporting full performant neutron transport and investigating novel transport algorithms in under two years with development mostly from relative novices.
+`MC/DC` uses `mpi4py` to gain distributed memory parallelism [@mpi4py_2021] and has run at the scale of tens of thousands of processors [@variansyah_mc23_mcdc].
+These acceleration and abstraction techniques allow `MC/DC` developers to remain in a pure Python development environment without needing to support compiled or domain specific languages.
+This has allowed `MC\DC` to grow from its instantiation less than two years ago into a codebase that supports full performant neutron transport and investigation of novel transport algorithms, with development mostly from relative novices.
 
-Many of the traditionally developed neutron transport codes are export controlled (not open source and difficult to get) and notoriously difficult to install, use, and develope.
-`MC/DC` being an open source easily installable Python package (with a `pip` distribution) means that it is ideal in an academic environment for both research and education.
-This is only further assisted by a test suite we have developed to do unit, regression, verification and performance tests, most of which run on a continuous integration basis.
+Many of the traditionally developed neutron transport codes are export controlled (*i.e.*, are not open source and are difficult to get) and notoriously difficult to install, use, and develop in.
+Because `MC/DC` is an open source and easily-installable Python package (with a `pip` distribution), it is ideal in an academic environment for both research and education.
+This is further assisted by a test suite we have developed for unit, regression, verification and performance tests, most of which run on a continuous integration basis.
 
 `MC/DC` has support for continuous energy and multi-group treatments of the neutron distribution in energy.
 It can solve k-eigenvalue problems (used to determine neutron population growth rates in reactors) as well as fully dynamic simulations.
-It has a novel continuous geometry movement function (other codes use step functions) that allows for better modeling of things like reactor control rods or pulsed neutron experiments.
+It has a novel continuous geometry movement function that models transient elements (*e.g.*, control rods or pulsed neutron experiments) more accurately than the step functions used by other codes.
 It also supports some simple domain decomposition, with more complex algorithms currently being implemented.
 
-`MC/DC` enabled explorations into dynamic neutron transport algorithms have been successful, including, quasi-Monte Carlo techniques [@mcdc:variansyah_physor22_pct], hybrid iterative techniques for k-eigenvalue simulations [@mcdc:qmc; @mcdc:qmcabs], transient population control techniques [@mcdc:variansyah_nse22_pct], hash based random number generation, global uncertainty quantification [@mcdc:clements_mc23], residual Monte Carlo methods, and machine learning techniques for dynamic node scheduling, among others.
+`MC/DC`-enabled explorations into dynamic neutron transport algorithms have been successful, including quasi-Monte Carlo techniques [@mcdc:variansyah_physor22_pct], hybrid iterative techniques for k-eigenvalue simulations [@mcdc:qmc; @mcdc:qmcabs], transient population control techniques [@mcdc:variansyah_nse22_pct], hash-based random number generation, uncertainty and global sensitivity analysis [@mcdc:clements_mc23], residual Monte Carlo methods, and machine learning techniques for dynamic node scheduling, among others.
 
 # Future Work
 

docs/source/index.rst

@@ -16,7 +16,7 @@ a rapid methods development platform for for modern HPCs and is targeting CPUs a
 
 MC/DC has support for continuous energy and multi-group transport.
 It can solve more traditional k-eigenvalue problems (used to determine neutron population growth rates in reactors) as well as fully dynamic simulations.
-It has a novel continuous geometry movement function (other codes use step functions) that allows for better modeling of things like control rods.
+It has a novel continuous geometry movement function that models transient elements (*e.g.*, control rods or pulsed neutron experiments) more accurately than the step functions used by other codes.
 It also supports some simple Domain decomposition, with more complex algorithms currently being implemented.
 
 MC/DC is machine portable and is validated to run on:
@@ -105,9 +105,9 @@ Indices and tables
 To build the docs
 =================
 
-#. Install dependencies (we recommend: ``conda install sphinx`` and ``pip install furo``). Note that these dependencies are not installed as a part of base MC/DC
-#. Run ``make html`` to compile
-#. Then launch ``build/html/index.html`` with your browser of choice
+#. Install dependencies (we recommend: ``conda install sphinx`` and ``pip install furo sphinx_toolbox``). Note that these dependencies are not installed as part of base MC/DC.
+#. From the `MCDC/docs/` directory, run ``make html`` to compile.
+#. Launch ``build/html/index.html`` with your browser of choice.
 
 To Cite MC/DC
 =============
@@ -123,4 +123,4 @@ please cite our article in the Journal of Open Source software
         author = {},
         date = {},
         doi = {},
-    }
+    }

docs/source/install.rst

@@ -4,20 +4,32 @@
 Installation Guide
 ===================
 
-Most users should be able to install MC/DC using,
+Developers in MC/DC (on any machine) or users on HPC machines should install using the installation script included with the source code; 
+start by :ref:`creating-a-conda-environment`. 
+Installing from source via the installation script is the most resilient way to get properly configured dependencies.
+Most other users can install using pip. 
+
+-------------------
+Installing with pip
+-------------------
+Users who:
+
+#. are unix based (macOS, linux, etc.),
+#. have a working version of openMPI (from conda, brew, or apt),
+#. are using an environment manager like conda or have administrator privileges, and
+#. plan to *use* MC/DC, not develop features for MC/DC
+
+can install using pip. 
+We recommend doing so within an active conda (or other environment manager) environment, 
+which avoids the need for any admin access and keeps dependencies clean. 
+
 .. code-block:: sh
 
     pip install mcdc
 
-provided they have,
-
-#. a working version of openMPI (from sources like conda, brew, or apt)
-#. have administrator privileges or are using environment managers like conda
-#. are using a `unix` based (`macOS`, `linux`, etc.)
-#. are not trying to develope
+Now you're ready to run in pure Python mode!
 
-The rest of this guide outlines the basic steps to install MC/DC for development, on a local
-machine, or on HPC machine. The is the most resilient way to get the dependencies configured properly.
+.. _creating-a-conda-environment:
 
 -----------------------------------
 Creating an MC/DC Conda environment
@@ -30,7 +42,7 @@ We can't force you to use it, but we do *highly* recommend it, particularly
 if you plan on running MC/DC in `numba mode <https://numba.pydata.org/>`_.
 **The included installation script will fail if executed outside of a conda environment.**
 
-First, `conda` should be installed with `Miniconda <https://docs.conda.io/en/latest/miniconda.html>`_
+First, ``conda`` should be installed with `Miniconda <https://docs.conda.io/en/latest/miniconda.html>`_
 or `Anaconda <https://www.anaconda.com/>`_. HPC instructions: 
 
 `Quartz <https://hpc.llnl.gov/hardware/compute-platforms/quartz>`_ (LLNL, x86_64), 
@@ -49,7 +61,7 @@ or `Anaconda <https://www.anaconda.com/>`_. HPC instructions:
     bash Miniconda3-latest-Linux-ppc64le.sh
 
 
-Then create and activate a new conda environment called `mcdc-env` in
+Then create and activate a new conda environment called *mcdc-env* in
 which to install MC/DC. This creates an environment with python3.11 
 installed.
 
@@ -119,4 +131,4 @@ or run the script after instillation as a stand alone operation with
     bash config_cont_energy.sh
 
 Both these operations will clone the internal directory to your MCDC directory, untar the compressed folder, then set an environment variable in your bash script.
-NOTE: this does assume you are using bash shell.
+NOTE: this does assume you are using bash shell.