Grammar edits to documentation (#208)

Grammar edits to documentation
Small additions to make testing more clear

[ committed by @juliaputko ]
[ reviewed by @billschereriii ]

doc/code_of_conduct.rst

@@ -6,16 +6,16 @@ Code of Conduct
 
 Like the technical community as a whole, the SmartSim team and community is made up of a mixture of professionals and volunteers from all over the world, working on every aspect of the mission - including mentorship, teaching and connecting people.
 
-Diversity is one of our huge strengths, but it can also lead to communication issues and unhappiness. To that end, we have a few ground rules that we ask people to adhere to when they're participating within this community and project. These rules apply equally to founders, mentors and those seeking help and guidance.
+Diversity is one of our huge strengths, but it can also lead to communication issues and unhappiness. To that end, we have a few ground rules that we ask people to adhere to when they are participating within this community and project. These rules apply equally to founders, mentors and those seeking help and guidance.
 
-This isn't an exhaustive list of things that you can't do. Rather, take it in the spirit in which it's intended - a guide to make it easier to enrich all of us, the technical community and the conferences and usergroups we hope to guide new speakers to.
+This is not an exhaustive list of things that you cannot do. Rather, take it in the spirit in which it is intended - a guide to make it easier to enrich all of us, the technical community and the conferences and usergroups we hope to guide new speakers to.
 
-This code of conduct applies to all communication: this includes Slack, GitHub Issues, StackOverflow issues, and other forums such as Zoom, Skype, Google+ Hangouts, etc.
+This code of conduct applies to all communication. This includes: Slack, GitHub Issues, StackOverflow issues, and other forums such as Zoom, Skype, Google+ Hangouts, etc.
 
 * **Be welcoming, friendly, and patient.**
 * **Be considerate.** Your work will be used by other people, and you in turn will depend on the work of others. Any decision you make will affect users and colleagues, and you should take those consequences into account when making decisions.
-* **Be respectful.** Not all of us will agree all the time, but disagreement is no excuse for poor behaviour and poor manners. We might all experience some frustration now and then, but we cannot allow that frustration to turn into a personal attack. It's important to remember that a community where people feel uncomfortable or threatened is not a productive one. Members of the SmartSim community should be respectful when dealing with other members as well as with people outside the SmartSim community and with user groups/conferences, usergroup/conference organizers.
+* **Be respectful.** Not all of us will agree all the time, but disagreement is no excuse for poor behaviour and poor manners. We might all experience some frustration now and then, but we cannot allow that frustration to turn into a personal attack. It is important to remember that a community where people feel uncomfortable or threatened is not a productive one. Members of the SmartSim community should be respectful when dealing with other members as well as with people outside the SmartSim community and with user groups/conferences, usergroup/conference organizers.
 * **Be careful in the words that you choose.** Remember that sexist, racist, and other exclusionary jokes can be offensive to those around you. Be kind to others. Do not insult or put down other participants. Behave professionally. Remember that harassment and sexist, racist, or exclusionary jokes are not appropriate for the community.
-* **When we disagree, we try to understand why.** Disagreements, both social and technical, happen all the time and SmartSim is no exception. It is important that we resolve disagreements and differing views constructively. Remember that we're different. The strength of SmartSim comes from its varied community, people from a wide range of backgrounds. Different people have different perspectives on issues. Being unable to understand why someone holds a viewpoint doesn't mean that they're wrong. Don't forget that it is human to err and blaming each other doesn't get us anywhere, rather offer to help resolving issues and to help learn from mistakes.
+* **When we disagree, we try to understand why.** Disagreements, both social and technical, happen all the time and SmartSim is no exception. It is important that we resolve disagreements and differing views constructively. Remember that we are different. The strength of SmartSim comes from its varied community, people from a wide range of backgrounds. Different people have different perspectives on issues. Being unable to understand why someone holds a viewpoint does not mean that they are wrong. Do not forget that it is human to err and blaming each other does not get us anywhere. Rather, offer to help resolving issues and to help learn from mistakes.
 
 Original text courtesy of the `Speak Up! project <http://web.archive.org/web/20141109123859/http://speakup.io/coc.html>`_.

doc/community.rst

@@ -12,7 +12,7 @@ Need Help?
 ----------
 We encourage and welcome usage questions and bug reports from all users, even those who are new to SmartSim. There are a few things you can do to improve the likelihood of quickly getting a good answer.
 
- 1. **It's important to ask questions in the right place.** We strongly prefer the use of Stack Overflow or GitHub issues over Slack chat. GitHub and Stack Overflow are more easily searchable by future users, and therefore is more efficient for everyone’s time. Slack chat should be reserved for developer and community discussion. If you have a general question about how something should work or want best practices then use Stack Overflow. If you think you have found a bug then use GitHub
+ 1. **It is important to ask questions in the right place.** We strongly prefer the use of Stack Overflow or GitHub issues over Slack chat. GitHub and Stack Overflow are more easily searchable by future users, and therefore is more efficient for everyone’s time. Slack chat should be reserved for developer and community discussion. If you have a general question about how something should work or want best practices then use Stack Overflow. If you think you have found a bug then use GitHub.
 
  2. **Please ask only in one place.** Please restrict yourself to posting your question in only one place (likely Stack Overflow or GitHub) and don’t post in both.
 

doc/contributing_examples.rst

@@ -19,8 +19,8 @@ The Two Categories of the SmartSim Zoo
 
  2. SmartSim Applications (completed projects that use SmartSim)
 
-  * The README for the repository describes some of the larger applications of SmartSim. These examples fall under two categories;
-    examples by paper and examples by simulation model. The examples by paper are based on existing research papers e.g. , and the examples
+  * The README for the repository describes some of the larger applications of SmartSim. These examples fall under two categories:
+    examples by paper and examples by simulation model. The examples by paper are based on existing research papers, and the examples
     by simulation models are integrations of SmartSim with existing simulation models.
 
 How To Contribute
@@ -95,7 +95,7 @@ Summary of SmartSim Application Examples
 ########################################
 
  * **DeepDriveMD:** Based on the original DeepDriveMD work, extended to orchestrate complex workflows
-   with coupled applications without using the filesystem for exchanging information
+   with coupled applications without using the filesystem for exchanging information.
 
  * **TensorFlowFoam:** Uses TensorFlow inside of OpenFOAM simulations using SmartSim. Displays SmartSim's
    capability to evaluate a machine learning model from within a simulation with minimal external library

doc/developer.rst

@@ -4,7 +4,7 @@ Developer
 *********
 
 This section details common practices and tips for contributors
-to SmartSim and SmartRedis
+to SmartSim and SmartRedis.
 
 ================
 Testing SmartSim
@@ -37,7 +37,7 @@ Local
 =====
 
 There are two levels of testing in SmartSim. The first
-runs by default and doesn't launch any jobs out onto
+runs by default and does not launch any jobs out onto
 a system through a workload manager like Cobalt.
 
 If any of the above commands are used, the test suite will
@@ -111,16 +111,16 @@ Please check the following before submitting a pull request to the SmartSim repo
   1) Your feature is on a new branch off master.
   2) You are merging the feature branch from your fork into the main repository.
   3) All unnecessary whitespace has been purged from your code.
-  4) For Python code changes, Black and isort have been applied to format code and sort imports
-  5) Pylint errors have been minimized as much as possible
+  4) For Python code changes, Black and isort have been applied to format code and sort imports.
+  5) Pylint errors have been minimized as much as possible.
   6) All your code has been appropriately documented.
   7) The PR description is clear and concise.
   8) You have requested a review.
 
 Merging
 =======
 
-When merging there are a few guidelines to follow
+When merging, there are a few guidelines to follow
 
    - Wrap all merge messages to 70 characters per line.
 

doc/experiment.rst

@@ -4,7 +4,7 @@ Experiments
 ***********
 
 The Experiment acts as both a factory class for constructing the
-stages of an experiment (``Model``, ``Ensemble``, ``Orchestrator``, etc)
+stages of an experiment (``Model``, ``Ensemble``, ``Orchestrator``, etc.)
 as well as an interface to interact with the entities created by the experiment.
 
 Users can initialize an :ref:`Experiment <experiment_api>` at the beginning of a Jupyter notebook,
@@ -19,9 +19,9 @@ system through the specified launcher.
 |SmartSim Architecture|
 
 
-The interface was designed to be simple with as little complexity
+The interface was designed to be simple, with as little complexity
 as possible, and agnostic to the backend launching mechanism (local,
-Slurm, PBSPro, etc).
+Slurm, PBSPro, etc.).
 
 Model
 =====
@@ -45,7 +45,7 @@ Each launcher supports specific types of ``RunSettings``.
 These settings can be manually specified by the user, or auto-detected by the
 SmartSim Experiment through the ``Experiment.create_run_settings`` method.
 
-A simple example of using the Experiment API to create a model and run it locally.
+A simple example of using the Experiment API to create a model and run it locally:
 
 .. code-block:: Python
 
@@ -65,6 +65,7 @@ method will automatically create the appropriate ``RunSettings`` object and
 return it.
 
 For example with Slurm
+
 .. code-block:: Python
 
   from smartsim import Experiment
@@ -84,7 +85,7 @@ For example with Slurm
 
 The above will run ``srun -n 32 -N 1 echo Hello World!``, monitor it's execution,
 and inform the user when it is completed. This driver script can be executed in
-an interactive allocation, or placed into a batch script as follows
+an interactive allocation, or placed into a batch script as follows:
 
 .. code-block:: bash
 
@@ -111,11 +112,11 @@ Ensembles can be given parameters and permutation strategies that
 define how the ``Ensemble`` will create the underlying model objects.
 
 Three strategies are built in:
-  1. ``all_perm`` for generating all permutations of model parameters
-  2. ``step`` for creating one set of parameters for each element in `n` arrays
-  3. ``random`` for random selection from predefined parameter spaces.
+  1. ``all_perm``: for generating all permutations of model parameters
+  2. ``step``: for creating one set of parameters for each element in `n` arrays
+  3. ``random``: for random selection from predefined parameter spaces
 
-Here is an example that uses the ``random`` strategy to intialize 4 models
+Here is an example that uses the ``random`` strategy to intialize four models
 with random parameters within a set range. We use the ``params_as_args``
 field to specify that the randomly selected learning rate parameter should
 be passed to the created models as a executable argument.
@@ -145,12 +146,12 @@ be passed to the created models as a executable argument.
 
 
 A callable function can also be supplied for custom permutation strategies.
-The function should take two arguments: a list of parameter names and a list of lists
+The function should take two arguments: a list of parameter names, and a list of lists
 of potential parameter values. The function should return a list of dictionaries that
 will be supplied as model parameters. The length of the list returned will determine
 how many ``Model`` instances are created.
 
-For example, the following the the built-in strategy ``all_perm``.
+For example, the following is the built-in strategy ``all_perm``:
 
 .. code-block:: python
 
@@ -182,22 +183,22 @@ workload manager and available compute resources.
   - :ref:`CobaltBatchSettings <cqsub_api>` for Cobalt
   - :ref:`BsubBatchSettings <bsub_api>` for LSF
 
-If only passed ``RunSettings``, ``Ensemble`` objects will require either
+If it only passed ``RunSettings``, ``Ensemble``, objects will require either
 a ``replicas`` argument or a ``params`` argument to expand parameters
 into ``Model`` instances. At launch, the ``Ensemble`` will look for
 interactive allocations to launch models in.
 
-If passed ``BatchSettings`` without other arguments, an empty ``Ensemble``
+If it passed ``BatchSettings`` without other arguments, an empty ``Ensemble``
 will be created that ``Model`` objects can be added to manually. All ``Model``
 objects added to the ``Ensemble`` will be launched in a single batch.
 
-If passed ``BatchSettings`` and ``RunSettings``, the ``BatchSettings`` will
+If it passed ``BatchSettings`` and ``RunSettings``, the ``BatchSettings`` will
 determine the allocation settings for the entire batch, and the ``RunSettings``
 will determine how each individual ``Model`` instance is executed within
 that batch.
 
-The same example as above but tailored towards a running as a batch job
-on a slurm system
+This is the same example as above, but tailored towards a running as a batch job
+on a slurm system:
 
 .. code-block:: bash
 
@@ -233,7 +234,7 @@ on a slurm system
 
 
 This will generate and execute a batch script that looks something like
-the following
+the following:
 
 .. code-block:: bash
 

doc/installation.rst

@@ -109,13 +109,19 @@ SmartSim
 There are two stages for the installation of SmartSim.
 
  1. `pip` install SmartSim Python package
- 2. Build SmartSim using the `smart` commmand line tool installed by
+ 2. Build SmartSim using the `smart` command line tool installed by
     the pip package.
 
 Step 1: Install Python Package
 ==============================
 
-Activate a new virtual environment and install SmartSim from PyPi with
+Activate a new virtual environment:
+
+.. code-block:: bash
+
+    conda activate <env name>
+
+and install SmartSim from PyPi with
 the following command
 
 .. code-block:: bash
@@ -131,6 +137,10 @@ can request their installation through the ``ml`` flag as follows:
     pip install smartsim[ml]
     # add ray extra if you would like to use ray with SmartSim as well
     pip install smartsim[ml,ray]
+    # or if using ZSH
+    pip install smartsim\[ml\]
+    pip install smartsim\[ml,ray\]
+
 
 At this point, SmartSim is installed and can be used for more basic features.
 If you want to use the machine learning features of SmartSim, you will need
@@ -172,6 +182,8 @@ To install the default ML backends for CPU, run
     export CXX=g++
     export NO_CHECKS=1 # skip build checks
 
+.. code-block:: bash
+
     # run one of the following
     smart build --device cpu          # install PT and TF for cpu
     smart build --device cpu --onnx   # install all backends (PT, TF, ONNX) on gpu
@@ -196,7 +208,7 @@ CUDNN is not in your ``LD_LIBRARY_PATH`` or default loader locations.
   - ``CUDNN_INCLUDE_DIR``  - path to directory containing cudnn.h
   - ``CUDNN_LIBRARY``      - path to directory containing libcudnn.so
 
-For example, for bash do
+For example, for bash do:
 
 .. code-block:: bash
 
@@ -229,7 +241,7 @@ There are implementations of the SmartRedis client in
 4 languages: Python, C++, C and Fortran. The Python
 client is installed through ``pip`` and the compiled
 clients can be built as a static or shared library
-through cmake.
+through ``cmake``.
 
 SmartRedis Python supports the same architectures for
 pre-built wheels that SmartSim does.
@@ -336,7 +348,7 @@ With docker
   make docks
 
 Once the documentation has successfully built, users can open the
-main documents page from ``docs/develop/index.html``
+main documents page from ``docs/develop/index.html``.
 
 Without docker
 --------------
@@ -456,7 +468,7 @@ or otherwise, you can install them with ``conda``.
   export CUDNN_LIBRARY=/path/to/miniconda/pkgs/cudnn-x.x.x-cudax.x_x/lib
   export CUDNN_INCLUDE_DIR=/path/to/miniconda/pkgs/cudnn-x.x.x-cudax.x_x/include
 
-Be sure to get the cuDNN version that matches your CUDA installation
+Be sure to get the cuDNN version that matches your CUDA installation.
 The package_ names usually specify the versions.
 
 .. _package: https://anaconda.org/anaconda/cudnn/files
@@ -539,7 +551,7 @@ SmartSim on Cheyenne at NCAR
 Since SmartSim does not currently support the Message Passing Toolkit (MPT), Cheyenne
 users of SmartSim will need to utilize OpenMPI.
 
-The following module commands were utilized to run the examples
+The following module commands were utilized to run the examples:
 
 .. code-block:: bash
 
@@ -553,7 +565,7 @@ using the pip that comes with that installation.
 .. code-block:: bash
 
   $ pip install smartsim
-  $ smart build --device cpu  (Since Cheyenne does not have GPUs)
+  $ smart build --device cpu  #(Since Cheyenne does not have GPUs)
 
 To make the SmartRedis library (C, C++, Fortran clients), follow these steps with
 the same environment loaded.

doc/launchers.rst

@@ -9,16 +9,16 @@ launching them onto a system.
 
 The `launchers` allow SmartSim users to interact with their system
 programmatically through a python interface.
-Because of this, SmartSim users don't have to leave the Jupyter Notebook,
+Because of this, SmartSim users do not have to leave the Jupyter Notebook,
 Python REPL, or Python script to launch, query, and interact with their jobs.
 
 SmartSim currently supports 5 `launchers`:
-  1. ``local`` for single-node, workstation, or laptop
-  2. ``slurm`` for systems using the Slurm scheduler
-  3. ``pbs`` for systems using the PBSpro scheduler
-  4. ``cobalt`` for systems using the Cobalt scheduler
-  5. ``lsf`` for systems using the LSF scheduler
-  6. ``auto`` have SmartSim auto-detect the launcher to use.
+  1. ``local``: for single-node, workstation, or laptop
+  2. ``slurm``: for systems using the Slurm scheduler
+  3. ``pbs``: for systems using the PBSpro scheduler
+  4. ``cobalt``: for systems using the Cobalt scheduler
+  5. ``lsf``: for systems using the LSF scheduler
+  6. ``auto``: have SmartSim auto-detect the launcher to use.
 
 To specify a specific launcher, one argument needs to be provided
 to the ``Experiment`` initialization.
@@ -122,7 +122,7 @@ used to obtain allocations to launch on and release them after
     from smartsim.wlm import slurm
     alloc = slurm.get_allocation(nodes=1)
 
-The id of the allocation is returned as a string to the user so that
+The ID of the allocation is returned as a string to the user so that
 they can specify what entities should run on which allocations
 obtained by SmartSim.
 

doc/orchestrator.rst

@@ -117,7 +117,7 @@ create a Python reference to a Redis deployment so that users can launch, monito
 and stop a Redis deployment on workstations and HPC systems.
 
 Redis was chosen for the Orchestrator because it resides in-memory, can be distributed on-node
-as well as across nodes, and provides low-latency data access to many clients in parallel. The
+as well as across nodes, and provides low latency data access to many clients in parallel. The
 Redis ecosystem was a primary driver as the Redis module system provides APIs for languages,
 libraries, and techniques used in Data Science. In particular, the ``Orchestrator``
 relies on `RedisAI`_ to provide access to Machine Learning runtimes.