From d43674f059a1b3c0c54aa740a925a899f0ca865a Mon Sep 17 00:00:00 2001 From: Marlee Smith Date: Thu, 5 May 2022 16:44:08 -0600 Subject: [PATCH 01/14] Creating remote branch. Removing redundant link. --- guide/verifying-installation.rst | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) diff --git a/guide/verifying-installation.rst b/guide/verifying-installation.rst index bea7a1d9a7..097cd364a4 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 @@ -35,8 +34,7 @@ directory. 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 +generated by the *perfect_model_obs* program. The following MATLAB scripts compare the ensemble members with the truth and can calculate the error in the assimilation: @@ -86,7 +84,7 @@ calculate the error in the assimilation: time: [200x1 double] time_series_length: 200 var: 'state' - var_inds: [1 2 3] + var_inds: [1 2 3] |lorenz_63_total_err| @@ -116,7 +114,7 @@ learn more about: 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 From 6f9d7cf8e8e1bf4e3751daa627674b6f2ed02dd9 Mon Sep 17 00:00:00 2001 From: Marlee Smith Date: Tue, 10 May 2022 12:45:03 -0600 Subject: [PATCH 02/14] Reorganizing code into smaller blocks, allowing for more comprehensive descriptions of each command --- guide/verifying-installation.rst | 141 ++++++++++++++++++++----------- 1 file changed, 91 insertions(+), 50 deletions(-) diff --git a/guide/verifying-installation.rst b/guide/verifying-installation.rst index 097cd364a4..0046197538 100644 --- a/guide/verifying-installation.rst +++ b/guide/verifying-installation.rst @@ -28,63 +28,104 @@ 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. +directory. Execute the following command in your terminal to navigate to this directory. -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. The following -MATLAB scripts compare the ensemble members with the truth and can -calculate the error in the assimilation: +.. 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 hit enter. .. code-block:: bash $ cd DART/models/lorenz_63/work - $ matlab -nodesktop + +In the case of this Lorenz model, we know the "true" (by definition) +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 + + $ csh quickbuild.csh + $ ./filter + $ ./perfect_model_obs + +We are now ready to launch MATLAB. To execute the following command, replace MATLABROOT +with the directory that MATLAB is installed in on your computer. By default, +MATLAB is installed in the following locations: +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 + +If these do not work, and you are still faced with the error ``command not found: matlab``, +you can identify your path by opening the MATLAB application and using ``matlabroot``. + +.. code-block:: bash + $ MATLABROOT/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] +Now that we have launched MATLAB, we will now use the MATLAB *addpath* command to make the + ``DART/matlab/`` functions available for execution in any working directory. + +.. code-block:: bash + + [matlab_prompt] addpath ../../../diagnostics/matlab + +We will now run the diagnostics. The following MATLAB scripts (plot_total_err, +plot_ens_time_series, and perfect_model_obs) compare the ensemble members with +the truth and can calculate the error in the assimilation: + +.. note:: When prompted to input file names while running the diagnostics, you can +simply hit enter to select the default. + +.. code-block:: bash + + [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] |lorenz_63_total_err| From 0f94a8c7471d658ff712b3a3e317070b03e78023 Mon Sep 17 00:00:00 2001 From: Marlee Smith Date: Tue, 10 May 2022 15:24:58 -0600 Subject: [PATCH 03/14] Fixing simple formatting errors --- guide/verifying-installation.rst | 63 ++++++++++++++++++-------------- 1 file changed, 36 insertions(+), 27 deletions(-) diff --git a/guide/verifying-installation.rst b/guide/verifying-installation.rst index 0046197538..65aee212dd 100644 --- a/guide/verifying-installation.rst +++ b/guide/verifying-installation.rst @@ -27,12 +27,12 @@ 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. Execute the following command in your terminal to navigate to this directory. +Usually, we launch MATLAB from the ``DART/models/lorenz_63/work`` directory. +Execute the following command in your terminal to navigate to this directory. .. 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 hit enter. + you will execute in your terminal. To execute a command, type it in + exactly as seen, unless specified otherwise, and hit enter. .. code-block:: bash @@ -40,9 +40,9 @@ seen, unless specified otherwise, and hit 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 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. +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 @@ -50,28 +50,37 @@ the following three commands in the terminal. $ ./filter $ ./perfect_model_obs -We are now ready to launch MATLAB. To execute the following command, replace MATLABROOT -with the directory that MATLAB is installed in on your computer. By default, -MATLAB is installed in the following locations: -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 - -If these do not work, and you are still faced with the error ``command not found: matlab``, -you can identify your path by opening the MATLAB application and using ``matlabroot``. +We are now ready to launch MATLAB. To execute the following command, replace +MATLABROOT with the directory that MATLAB is installed in on your computer. By +default, MATLAB is installed in the following locations: .. code-block:: bash - $ MATLABROOT/matlab -nodesktop + + $ cd DART/models/lorenz_63/work + 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 + +If these do not work, and you are still faced with the error ``command not +found: matlab``, you can identify your path by opening the MATLAB application +and using the ``matlabroot`` command. + +.. code-block:: bash + + $ MATLABROOT/bin/matlab -nodesktop (Skipping startup messages) -Now that we have launched MATLAB, we will now use the MATLAB *addpath* command to make the - ``DART/matlab/`` functions available for execution in any working directory. +Now that we have launched MATLAB, we will now use the MATLAB *addpath* command +to make the ``DART/matlab/`` functions available for execution in any working +directory. .. code-block:: bash @@ -81,8 +90,8 @@ We will now run the diagnostics. The following MATLAB scripts (plot_total_err, plot_ens_time_series, and perfect_model_obs) compare the ensemble members with the truth and can calculate the error in the assimilation: -.. note:: When prompted to input file names while running the diagnostics, you can -simply hit enter to select the default. +.. note:: When prompted to input file names while running the diagnostics, you + can simply hit enter to select the default. .. code-block:: bash From 6e4ce4b211c4f4853f3489fa975ac127fc9745da Mon Sep 17 00:00:00 2001 From: Marlee Smith Date: Wed, 11 May 2022 13:30:42 -0600 Subject: [PATCH 04/14] Adding supplemental information on MATLABROOT --- guide/verifying-installation.rst | 45 ++++++++++++++++++-------------- 1 file changed, 25 insertions(+), 20 deletions(-) diff --git a/guide/verifying-installation.rst b/guide/verifying-installation.rst index 65aee212dd..46e2ef9046 100644 --- a/guide/verifying-installation.rst +++ b/guide/verifying-installation.rst @@ -40,8 +40,8 @@ Execute the following command in your terminal to navigate to this directory. In the case of this Lorenz model, we know the "true" (by definition) 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 +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 @@ -54,20 +54,18 @@ We are now ready to launch MATLAB. To execute the following command, replace MATLABROOT with the directory that MATLAB is installed in on your computer. By default, MATLAB is installed in the following locations: -.. code-block:: bash +* Windows (64-bit): +* C:\Program Files\MATLAB\R20XXx (64-bit MATLAB) +* C:\Program Files (x86)\MATLAB\R20XXx (32-bit MATLAB) - $ cd DART/models/lorenz_63/work - 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 - Windows (32-bit): - C:\Program Files\MATLAB\R20XXx +* Linux: +* /usr/local/MATLAB/R20XXx - Linux: - /usr/local/MATLAB/R20XXx - Mac: - /Applications/MATLAB_R20XXx.app +* Mac: +* /Applications/MATLAB_R20XXx.app If these do not work, and you are still faced with the error ``command not found: matlab``, you can identify your path by opening the MATLAB application @@ -76,7 +74,16 @@ and using the ``matlabroot`` command. .. code-block:: bash $ MATLABROOT/bin/matlab -nodesktop - (Skipping startup messages) + + + < 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 + + + To get started, type doc. + For product information, visit www.mathworks.com. Now that we have launched MATLAB, we will now use the MATLAB *addpath* command to make the ``DART/matlab/`` functions available for execution in any working @@ -96,14 +103,12 @@ the truth and can calculate the error in the assimilation: .. code-block:: bash [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 + Input name of ensemble trajectory file: + for 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 From 279d9877096afcd95da8451df5b1b7977c7daf88 Mon Sep 17 00:00:00 2001 From: Marlee Smith Date: Wed, 11 May 2022 13:35:49 -0600 Subject: [PATCH 05/14] adjustment to the graphics description --- guide/verifying-installation.rst | 42 +++++++++++++++++--------------- 1 file changed, 23 insertions(+), 19 deletions(-) diff --git a/guide/verifying-installation.rst b/guide/verifying-installation.rst index 46e2ef9046..7b49fb2047 100644 --- a/guide/verifying-installation.rst +++ b/guide/verifying-installation.rst @@ -50,9 +50,9 @@ scripts. To do so, execute the following three commands in the terminal. $ ./filter $ ./perfect_model_obs -We are now ready to launch MATLAB. To execute the following command, replace -MATLABROOT with the directory that MATLAB is installed in on your computer. By -default, MATLAB is installed in the following locations: +You are now ready to launch MATLAB. To do so, execute the command below, and +replace ``MATLABROOT`` with the directory that MATLAB is installed in on your computer. +By default, MATLAB is installed in the following locations: * Windows (64-bit): * C:\Program Files\MATLAB\R20XXx (64-bit MATLAB) @@ -67,9 +67,16 @@ default, MATLAB is installed in the following locations: * Mac: * /Applications/MATLAB_R20XXx.app -If these do not work, and you are still faced with the error ``command not -found: matlab``, you can identify your path by opening the MATLAB application -and using the ``matlabroot`` command. +``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 MATLABROOT by opening the MATLAB application and executing the command +``matlabroot``, which will display the correct location. + +Upon successfully launching MATLAB, the MATLAB header will be outputted to your +terminal as it is below. .. code-block:: bash @@ -81,35 +88,32 @@ and using the ``matlabroot`` command. R2022a Update 1 (9.12.0.1927505) 64-bit (maci64) April 6, 2022 - - To get started, type doc. - For product information, visit www.mathworks.com. - -Now that we have launched MATLAB, we will now use the MATLAB *addpath* command +Now that you have launched MATLAB, you must now use the MATLAB *addpath* command to make the ``DART/matlab/`` functions available for execution in any working directory. .. code-block:: bash - [matlab_prompt] addpath ../../../diagnostics/matlab + $ addpath ../../../diagnostics/matlab -We will now run the diagnostics. The following MATLAB scripts (plot_total_err, -plot_ens_time_series, and perfect_model_obs) compare the ensemble members with -the truth and can calculate the error in the assimilation: +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. They will produce the graphics as shown +below: -.. note:: When prompted to input file names while running the diagnostics, you - can simply hit enter to select the default. +.. note:: When prompted to input file names while running the diagnostics, simply + hit enter to select the default. .. code-block:: bash - [matlab_prompt] plot_total_err + $ plot_total_err Input name of ensemble trajectory file: for preassim.nc Comparing true_state.nc and preassim.nc - [matlab_prompt] plot_ens_time_series + $ plot_ens_time_series Input name of ensemble trajectory file; (cr) for preassim.nc From 0015c987b6d64c58adef7c0022637487acc110e8 Mon Sep 17 00:00:00 2001 From: Marlee Smith Date: Wed, 11 May 2022 14:01:04 -0600 Subject: [PATCH 06/14] fixing structure of list --- guide/verifying-installation.rst | 17 +++++++++-------- 1 file changed, 9 insertions(+), 8 deletions(-) diff --git a/guide/verifying-installation.rst b/guide/verifying-installation.rst index 7b49fb2047..d765a147db 100644 --- a/guide/verifying-installation.rst +++ b/guide/verifying-installation.rst @@ -55,25 +55,26 @@ replace ``MATLABROOT`` with the directory that MATLAB is installed in on your co By default, MATLAB is installed in the following locations: * Windows (64-bit): -* C:\Program Files\MATLAB\R20XXx (64-bit MATLAB) -* C:\Program Files (x86)\MATLAB\R20XXx (32-bit MATLAB) + * 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 + * C:\Program Files\MATLAB\R20XXx * Linux: -* /usr/local/MATLAB/R20XXx + * /usr/local/MATLAB/R20XXx * Mac: -* /Applications/MATLAB_R20XXx.app + * /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 MATLABROOT by opening the MATLAB application and executing the command -``matlabroot``, which will display the correct location. +correct directory by opening the MATLAB application and executing the command +``matlabroot``, which will display the correct location with the correct version +incorporated into the MATLABROOT. Upon successfully launching MATLAB, the MATLAB header will be outputted to your terminal as it is below. @@ -98,7 +99,7 @@ directory. 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. They will produce the graphics as shown +calculate the error in the assimilation. They will produce the graphics as shown below: .. note:: When prompted to input file names while running the diagnostics, simply From d2525f1ec2e02b84e5cb7529e605f6bfa06c3d7a Mon Sep 17 00:00:00 2001 From: Marlee Smith Date: Wed, 11 May 2022 14:35:46 -0600 Subject: [PATCH 07/14] fixing structure of list --- guide/verifying-installation.rst | 20 +++++++++++--------- 1 file changed, 11 insertions(+), 9 deletions(-) diff --git a/guide/verifying-installation.rst b/guide/verifying-installation.rst index d765a147db..68bf22b6a5 100644 --- a/guide/verifying-installation.rst +++ b/guide/verifying-installation.rst @@ -54,18 +54,20 @@ You are now ready to launch MATLAB. To do so, execute the command below, and replace ``MATLABROOT`` with the directory that MATLAB is installed in on your computer. By default, MATLAB is installed in the following locations: -* Windows (64-bit): - * C:\Program Files\MATLAB\R20XXx (64-bit MATLAB) - * C:\Program Files (x86)\MATLAB\R20XXx (32-bit MATLAB) +.. code-block:: bash + + 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 + Windows (32-bit): + C:\Program Files\MATLAB\R20XXx -* Linux: - * /usr/local/MATLAB/R20XXx + Linux: + /usr/local/MATLAB/R20XXx -* Mac: - * /Applications/MATLAB_R20XXx.app + 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 From cb1d2a793c7f0b3a78584581b33d3cd92494da3b Mon Sep 17 00:00:00 2001 From: Marlee Smith Date: Wed, 11 May 2022 17:20:12 -0600 Subject: [PATCH 08/14] removing syntax highlighting from list --- guide/verifying-installation.rst | 21 +++++++++++---------- 1 file changed, 11 insertions(+), 10 deletions(-) diff --git a/guide/verifying-installation.rst b/guide/verifying-installation.rst index 68bf22b6a5..e452a669f2 100644 --- a/guide/verifying-installation.rst +++ b/guide/verifying-installation.rst @@ -30,14 +30,14 @@ run some of the functions available in ``DART/diagnostics/matlab/``. Usually, we launch MATLAB from the ``DART/models/lorenz_63/work`` directory. Execute the following command in your terminal to navigate to this directory. -.. 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 hit enter. - .. 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 hit 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 is generated by running the ``perfect_model_obs`` program. We therefore must first @@ -50,11 +50,12 @@ scripts. To do so, execute the following three commands in the terminal. $ ./filter $ ./perfect_model_obs -You are now ready to launch MATLAB. To do so, execute the command below, and -replace ``MATLABROOT`` with the directory that MATLAB is installed in on your computer. -By default, MATLAB is installed in the following locations: +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:: bash +.. code-block:: text Windows (64-bit): C:\Program Files\MATLAB\R20XXx (64-bit MATLAB) @@ -101,8 +102,8 @@ directory. 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. They will produce the graphics as shown -below: +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 hit enter to select the default. From 0c2516b817335fdccd31abb43abdd776f7b10a94 Mon Sep 17 00:00:00 2001 From: Marlena Smith <44214771+mjs2369@users.noreply.github.com> Date: Fri, 13 May 2022 12:41:28 -0600 Subject: [PATCH 09/14] Update guide/verifying-installation.rst Co-authored-by: hkershaw-brown <20047007+hkershaw-brown@users.noreply.github.com> --- guide/verifying-installation.rst | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/guide/verifying-installation.rst b/guide/verifying-installation.rst index e452a669f2..58ec0b43bb 100644 --- a/guide/verifying-installation.rst +++ b/guide/verifying-installation.rst @@ -76,8 +76,7 @@ latest version of MATLAB would be ``/Applications/MATLAB_R2022a.app/bin/matlab - 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``, which will display the correct location with the correct version -incorporated into the MATLABROOT. +``matlabroot``, which will display the directory where MATLAB is installed. Upon successfully launching MATLAB, the MATLAB header will be outputted to your terminal as it is below. From a4d783decacd7c994ca9e447397b84d507e09b1b Mon Sep 17 00:00:00 2001 From: Marlee Smith Date: Fri, 13 May 2022 14:04:33 -0600 Subject: [PATCH 10/14] addressing feedback and fixing small errors in the text --- guide/verifying-installation.rst | 25 ++++++++++++++----------- 1 file changed, 14 insertions(+), 11 deletions(-) diff --git a/guide/verifying-installation.rst b/guide/verifying-installation.rst index e452a669f2..54bb32d23b 100644 --- a/guide/verifying-installation.rst +++ b/guide/verifying-installation.rst @@ -15,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 @@ -26,9 +26,12 @@ 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. -Execute the following command in your terminal to navigate to this 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 @@ -36,7 +39,7 @@ Execute the following command in your terminal to navigate to this directory. .. 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 hit enter. + 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 is @@ -47,8 +50,8 @@ scripts. To do so, execute the following three commands in the terminal. .. code-block:: bash $ csh quickbuild.csh - $ ./filter $ ./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 @@ -76,8 +79,8 @@ latest version of MATLAB would be ``/Applications/MATLAB_R2022a.app/bin/matlab - 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``, which will display the correct location with the correct version -incorporated into the MATLABROOT. +``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. @@ -93,7 +96,7 @@ terminal as it is below. April 6, 2022 Now that you have launched MATLAB, you must now use the MATLAB *addpath* command -to make the ``DART/matlab/`` functions available for execution in any working +to make the ``DART/diagnostics/matlab/`` functions available for execution in any working directory. .. code-block:: bash @@ -106,7 +109,7 @@ 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 - hit enter to select the default. + press enter to select the default. .. code-block:: bash @@ -173,7 +176,7 @@ 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? ` From c0306e42501a09e1389817d338c1d2ac464e909f Mon Sep 17 00:00:00 2001 From: hkershaw-brown <20047007+hkershaw-brown@users.noreply.github.com> Date: Fri, 13 May 2022 14:34:35 -0600 Subject: [PATCH 11/14] rst formatting for `` --- guide/verifying-installation.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guide/verifying-installation.rst b/guide/verifying-installation.rst index 54bb32d23b..d7d4d56d36 100644 --- a/guide/verifying-installation.rst +++ b/guide/verifying-installation.rst @@ -31,7 +31,7 @@ you have yet to download DART, see :doc:`Downloading DART ` fo 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. +in your terminal to navigate to the ``DART/models/lorenz_63/work`` directory. .. code-block:: bash From 69965985f0d6a30ca2526c4f03fe51c2a9801a52 Mon Sep 17 00:00:00 2001 From: Marlee Smith Date: Fri, 13 May 2022 14:38:40 -0600 Subject: [PATCH 12/14] missing space character --- guide/verifying-installation.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guide/verifying-installation.rst b/guide/verifying-installation.rst index 54bb32d23b..d7d4d56d36 100644 --- a/guide/verifying-installation.rst +++ b/guide/verifying-installation.rst @@ -31,7 +31,7 @@ you have yet to download DART, see :doc:`Downloading DART ` fo 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. +in your terminal to navigate to the ``DART/models/lorenz_63/work`` directory. .. code-block:: bash From 1f9e79a3d1b6532a414fa00dec05bfec7faa6586 Mon Sep 17 00:00:00 2001 From: kdraeder Date: Fri, 13 May 2022 15:00:09 -0600 Subject: [PATCH 13/14] Update verifying-installation.rst A couple more tiny changes for consistency with the previous instructions. --- guide/verifying-installation.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/guide/verifying-installation.rst b/guide/verifying-installation.rst index d7d4d56d36..ab3fec3ff3 100644 --- a/guide/verifying-installation.rst +++ b/guide/verifying-installation.rst @@ -121,8 +121,8 @@ calculate the error in the assimilation. Running ``plot_total_err`` and preassim.nc $ plot_ens_time_series - Input name of ensemble trajectory file; - (cr) for preassim.nc + Input name of ensemble trajectory file: + for preassim.nc Comparing true_state.nc and preassim.nc From e0a94d95d2bc235ad2b4af41dcdbe0658f5171bb Mon Sep 17 00:00:00 2001 From: Helen Kershaw Date: Mon, 16 May 2022 11:12:40 -0600 Subject: [PATCH 14/14] bump version and changelog for release --- CHANGELOG.rst | 4 ++++ conf.py | 2 +- 2 files changed, 5 insertions(+), 1 deletion(-) 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 ---------------------------------------------------