diff --git a/CHANGELOG.rst b/CHANGELOG.rst index cf2e558e0e..a728a7b625 100644 --- a/CHANGELOG.rst +++ b/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. diff --git a/conf.py b/conf.py index ca2e659a17..f0affea537 100644 --- a/conf.py +++ b/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 --------------------------------------------------- diff --git a/guide/verifying-installation.rst b/guide/verifying-installation.rst index bea7a1d9a7..ab3fec3ff3 100644 --- a/guide/verifying-installation.rst +++ b/guide/verifying-installation.rst @@ -2,7 +2,6 @@ Verifying installation ###################### - .. note:: These verification steps require MATLAB®. `UCAR 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? ` or :doc:`What is data assimilation? ` 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 ` 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: + for preassim.nc + + Comparing true_state.nc and + preassim.nc + + $ plot_ens_time_series + Input name of ensemble trajectory file: + 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? ` - :doc:`How do I add my 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? ` -.. 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