Merge pull request #350 from NCAR/verifying-installation-doc-update

Verifying installation doc update

CHANGELOG.rst

@@ -22,6 +22,10 @@ individual files.
 
 The changes are now listed with the most recent at the top.
 
+**May 16 2022 :: Installation documentation update. Tag: v9.16.3**
+
+- Improved installation documentation.
+
 **April 5 2022 :: Bug-fix for NetCDF variables with NaN attributes. Tag: v9.16.2**
 
 - Fix for checking attributes of NetCDF variables that have a NaN as the missing or _FillValue.

conf.py

@@ -21,7 +21,7 @@
 author = 'Data Assimilation Research Section'
 
 # The full version, including alpha/beta/rc tags
-release = '9.16.2'
+release = '9.16.3'
 master_doc = 'README'
 
 # -- General configuration ---------------------------------------------------

guide/verifying-installation.rst

@@ -2,7 +2,6 @@
 Verifying installation
 ######################
 
-
 .. note:: These verification steps require MATLAB®. `UCAR Member Institutions
           <https://www.ucar.edu/who-we-are/membership-governance/member-institutions>`_
           have access to institutional licenses for MATLAB, thus we have
@@ -16,7 +15,7 @@ model: what is it and why should we care? <lorenz-63-model>` or :doc:`What is
 data assimilation? <introduction-ensemble-da>` for more information.
 
 This sensitivity is of practical interest for verifying these results.
-The initial conditions files and observations sequences are provided in
+The initial conditions files and observation sequences are provided in
 ASCII, which is portable across systems, but there may be some
 machine-specific round-off error in the conversion from ASCII to machine
 binary. As Lorenz 63 is such a nonlinear model, extremely small
@@ -27,66 +26,131 @@ Your results should start out looking VERY SIMILAR and may diverge with
 time.
 
 The simplest way to determine if the installation is successful is to
-run some of the functions available in ``DART/diagnostics/matlab/``.
-Usually, we launch MATLAB from the ``DART/models/lorenz_63/work``
-directory and use the MATLAB *addpath* command to make the
-``DART/matlab/`` functions available for execution in any working
-directory.
+run some of the functions available in ``DART/diagnostics/matlab/``. If
+you have yet to download DART, see :doc:`Downloading DART <downloading-dart>` for
+instructions on how to do so. Usually, we launch MATLAB from the
+``DART/models/lorenz_63/work`` directory. First, open your terminal and navigate
+to the directory where you downloaded DART. Then, execute the following command
+in your terminal to navigate to the ``DART/models/lorenz_63/work`` directory.
+
+.. code-block:: bash
+
+   $ cd DART/models/lorenz_63/work
+
+.. note:: The lines of code that are marked with a ``$`` symbol are commands that
+          you will execute in your terminal. To execute a command, type it in
+          exactly as seen, unless specified otherwise, and press enter.
 
 In the case of this Lorenz model, we know the "true" (by definition)
-state of the model that is consistent with the observations, which was
-generated by the *perfect_model_obs* program as described in `Checking
-the build — running something <#runningSomething>`__. The following
-MATLAB scripts compare the ensemble members with the truth and can
-calculate the error in the assimilation:
+state of the model that is consistent with the observations, which is
+generated by running the ``perfect_model_obs`` program. We therefore must first
+run ``perfect_model_obs`` before launching MATLAB and running our diagnostic
+scripts. To do so, execute the following three commands in the terminal.
 
 .. code-block:: bash
 
-   $ cd DART/models/lorenz_63/work
-   $  matlab -nodesktop
-   (Skipping startup messages)
-
-       [matlab_prompt] addpath ../../../diagnostics/matlab
-       [matlab_prompt] plot_total_err
-       Input name of true model trajectory file;
-       (cr) for perfect_output.nc
-       perfect_output.nc
-       Input name of ensemble trajectory file;
-       (cr) for preassim.nc
-       preassim.nc
-       Comparing true_state.nc and
-                 preassim.nc
-       [matlab_prompt] plot_ens_time_series
-       Input name of ensemble trajectory file;
-       (cr) for preassim.nc
-
-       Comparing true_state.nc and
-                 preassim.nc
-       Using Variable state IDs 1  2  3
-
-       pinfo =
-
-         struct with fields:
-
-                        model: 'Lorenz_63'
-                      def_var: 'state'
-               num_state_vars: 1
-                   num_copies: 20
-              num_ens_members: 20
-             ensemble_indices: [1 2 3 ... 18 19 20]
-                min_state_var: 1
-                max_state_var: 3
-               def_state_vars: [1 2 3]
-                        fname: 'preassim.nc'
-                   truth_file: 'true_state.nc'
-                   diagn_file: 'preassim.nc'
-                   truth_time: [1 200]
-                   diagn_time: [1 200]
-                         vars: {'state'}
-                         time: [200x1 double]
-           time_series_length: 200
-                          var: 'state'
-                     var_inds: [1 2 3]       
+   $ csh quickbuild.csh
+   $ ./perfect_model_obs
+   $ ./filter
+
+You are now ready to launch MATLAB. To do so, execute the command
+``MATLABROOT/bin/matlab -nodesktop``, and replace ``MATLABROOT`` with the
+directory that MATLAB is installed in on your computer. By default, MATLAB is
+installed in the following locations:
+
+.. code-block:: text
+
+   Windows (64-bit):
+   C:\Program Files\MATLAB\R20XXx (64-bit MATLAB)
+   C:\Program Files (x86)\MATLAB\R20XXx (32-bit MATLAB)
+
+   Windows (32-bit):
+   C:\Program Files\MATLAB\R20XXx
+
+   Linux:
+   /usr/local/MATLAB/R20XXx
+
+   Mac:
+   /Applications/MATLAB_R20XXx.app
+
+``R20XXx`` must also be replaced with the version of MATLAB that you have
+installed. For example, the full command for a Mac user having installed the
+latest version of MATLAB would be ``/Applications/MATLAB_R2022a.app/bin/matlab -nodesktop``.
+
+If the corresponding MATLABROOT listed above does not work, you can identify the
+correct directory by opening the MATLAB application and executing the command
+``matlabroot``. This will display the directory where MATLAB is installed. It
+will have the correct version already incorporated into the MATLABROOT.
+
+Upon successfully launching MATLAB, the MATLAB header will be outputted to your
+terminal as it is below.
+
+.. code-block:: bash
+
+   $  MATLABROOT/bin/matlab -nodesktop
+
+
+                                             < M A T L A B (R) >
+                                   Copyright 1984-2022 The MathWorks, Inc.
+                               R2022a Update 1 (9.12.0.1927505) 64-bit (maci64)
+                                                April 6, 2022
+
+Now that you have launched MATLAB, you must now use the MATLAB *addpath* command
+to make the ``DART/diagnostics/matlab/`` functions available for execution in any working
+directory.
+
+.. code-block:: bash
+
+     $ addpath ../../../diagnostics/matlab
+
+You are now ready to run the diagnostics. The following MATLAB scripts (plot_total_err
+and plot_ens_time_series,) compare the ensemble members with the truth and can
+calculate the error in the assimilation. Running ``plot_total_err`` and
+``plot_ens_time_series`` will produce the graphics as shown below:
+
+.. note:: When prompted to input file names while running the diagnostics, simply
+          press enter to select the default.
+
+.. code-block:: bash
+
+   $ plot_total_err
+   Input name of ensemble trajectory file:
+   <cr> for preassim.nc
+
+   Comparing true_state.nc and
+             preassim.nc
+
+   $ plot_ens_time_series
+   Input name of ensemble trajectory file:
+   <cr> for preassim.nc
+
+   Comparing true_state.nc and
+             preassim.nc
+   Using Variable state IDs 1  2  3
+
+   pinfo =
+
+     struct with fields:
+
+                    model: 'Lorenz_63'
+                  def_var: 'state'
+           num_state_vars: 1
+               num_copies: 20
+          num_ens_members: 20
+         ensemble_indices: [1 2 3 ... 18 19 20]
+            min_state_var: 1
+            max_state_var: 3
+           def_state_vars: [1 2 3]
+                    fname: 'preassim.nc'
+               truth_file: 'true_state.nc'
+               diagn_file: 'preassim.nc'
+               truth_time: [1 200]
+               diagn_time: [1 200]
+                     vars: {'state'}
+                     time: [200x1 double]
+       time_series_length: 200
+                      var: 'state'
+                 var_inds: [1 2 3]
 
 
 |lorenz_63_total_err|
@@ -112,11 +176,11 @@ learn more about:
    workflow.
 -  :doc:`How do I run DART with my model? <required-model-mod-routines>`
 -  :doc:`How do I add my observations to DART? <adding-your-observations-to-dart>`
--  :doc:`How would I use DART for teaching students and/or
+-  :doc:`How would I use DART for teaching students or
    myself? <../theory/readme>`
 -  :doc:`How can I contribute to DART? <contributors-guide>`
 
-.. note:: 
+.. note::
 
    In the case that the above instructions had one or more issues that either
    did not work for you as intended or were confusing, please contact the DART