ReadTheDocs documentation for KPP 2.5.0 #41

yantosca · 2022-05-16T21:43:52Z

I've made several updates to the ReadTheDocs documentation and I think we are now in a pretty good place to releasing KPP 2.5.0. Please take a look at https://kpp.readthedocs.io and let me know if you have any suggested changes.

We now have separated the document into Getting Started, Using KPP, Technical Information, Citations, and Help and Reference. Also move the various rst files around into subfolders of source. Also added a bibtex.json file for the citations. Updated conf.py so that citations can be automatically added from the *.bib files. Signed-off-by: Bob Yantosca <yantosca@seas.harvard.edu>

src/gen.c - Change the comment for Vdotout that is added to subroutine Fun(). This fixes a copy-and-paste typo. Signed-off-by: Bob Yantosca <yantosca@seas.harvard.edu>

(1) Split files across docs/source/getting_started, docs/source/using_kpp, docs/source/tech_info, docs/source/citations, and docs/source/reference (2) Updated conf.py to remove the rubric for references (3) Updated content in "Input for KPP" and "Output from KPP" (4) Added figures and table titles (5) Trimmed trailing whitespace Signed-off-by: Bob Yantosca <yantosca@seas.harvard.edu>

Made several formatting updates to the "Input for KPP" and "Output from KPP" chapters, mostly involving tables and references. Also added some extra information in the form of "information" or "tip" boxes. Also added references to bibtex.json, which will list in the References page. Signed-off-by: Bob Yantosca <yantosca@seas.harvard.edu>

Also added some formatting changes Signed-off-by: Bob Yantosca <yantosca@seas.harvard.edu>

- Added a section on C-I tests - Added the model coefficients for RODAS-3 and RODAS-4 - Added remaining citations to journal articles - Fixed link issues - Removed references to Fortran77 - Trimmed trailing whitespace - Condensed BibTeX files "adrian.bib" and "rolf.bib" into "kpp.bib", located in the citations folder. Signed-off-by: Bob Yantosca <yantosca@seas.harvard.edu>

Signed-off-by: Bob Yantosca <yantosca@seas.harvard.edu>

docs/source/index.rst - Updated Mike Long's affiliation docs/source/tech_info/06_info_for_kpp_developers.rst - Fixed grammar ("that" instead of "which") - Changed "section" to "sections" at the end of the C-I tests main section Signed-off-by: Bob Yantosca <yantosca@seas.harvard.edu>

.ci-pipelines/*.sh - Add "small_strato" to the for loop so that it will be included in the tests (and cleanup) ci-tests/small_strato/* - Define a C-I test using the same KPP definition file as listed in Chapter 2 of the KPP Manual on kpp.readthedocs.io. Signed-off-by: Bob Yantosca <yantosca@seas.harvard.edu>

RolfSander · 2022-05-17T09:49:38Z

Thanks, this must have been a lot of work! I will go through the
documentation and leave a comment here whenever I find something...

RolfSander · 2022-05-17T10:10:31Z

00_revision_history.html:

for KPP 2.2.3, add:
- There were more new integrators: (kpp_)dvode.f90, runge_kutta.f90,
  runge_kutta_adj.f90, runge_kutta_tlm.f90, sdirk_adj.f90,
  sdirk_tlm.f90
- new Rosenbrock method Rang3
- Several vector and array functions from BLAS (WCOPY, WAXPY, ...)
  were replaced by Fortran 90 expressions.
I think the introductory sentence for the changes in KPP 2.1 can be
deleted: "This user manual describes recently added features of KPP as
well as those which have been available for a longer period. Here we
give an overview about the recent changes:"

RolfSander · 2022-05-17T10:11:15Z

01_installation.html:

broken link in "Clone the KPP source code from the KPP Github
repository:"
maybe we should also mention gcc as a dependency?
"If you use the bash shell, edit ??? and add:" -> file name missing
"You can add the following statements..." -> the ABOVE statements?
"If necessary, edit and enter the name of your C compiler in
src/Makefile." -> this should be Makefile.defs

RolfSander · 2022-05-17T10:16:49Z

02_running_kpp_sample_mech.html:

"In this paper we will refer to this name as ROOT." -> Maybe "here"
instead of "In this paper".
"The #INTEGRATOR and #INTFILE commands select a specific numerical
integration routine" -> I don't think we need to mention #INTFILE
here. The user only needs #INTEGRATOR.
"is the normalized sunlight intensity" -> The word "SUN"is missing.

RolfSander · 2022-05-17T12:50:36Z

04_input_for_kpp.html:

"An exception is the file atoms, which has no suffix." -> Maybe we
should rename this file to atoms.kpp? I don't see a good reason why
it doesn't have a suffix yet.
"KPP accepts only one of these files as input, but using the command,
code from separate files can be combined." -> The word #INCLUDE is
missing.
"i.e. when another sign occurs at the beginning of a line." -> # is
missing.
Hmm, there seem to be many more cases where the command names like
#SOMETHING have disappeared from the manual...

yantosca · 2022-05-17T13:46:52Z

"An exception is the file atoms, which has no suffix." -> Maybe we
should rename this file to atoms.kpp? I don't see a good reason why
it doesn't have a suffix yet.

Agreed. We should rename that. I can do that in the docs branch.

"KPP accepts only one of these files as input, but using the command,
code from separate files can be combined." -> The word #INCLUDE is
missing.

"i.e. when another sign occurs at the beginning of a line." -> # is
missing.

Hmm, there seem to be many more cases where the command names like
#SOMETHING have disappeared from the manual...

Yes, pandoc somehow didn't bring over text beginning with #. I have had to add them manually, and I probably didn't catch everything. I've been going back & forth between the PDF and the ReadTheDocs, and I'll go over it again to make sure I catch any more missing commands. In the meantime if you see any more missing # then let me know.

yantosca · 2022-05-17T13:53:14Z

00_revision_history.html:

for KPP 2.2.3, add:

There were more new integrators: (kpp_)dvode.f90, runge_kutta.f90,
runge_kutta_adj.f90, runge_kutta_tlm.f90, sdirk_adj.f90,
sdirk_tlm.f90
new Rosenbrock method Rang3
Several vector and array functions from BLAS (WCOPY, WAXPY, ...)
were replaced by Fortran 90 expressions.

I think the introductory sentence for the changes in KPP 2.1 can be
deleted: "This user manual describes recently added features of KPP as
well as those which have been available for a longer period. Here we
give an overview about the recent changes:"

Now done, will push soon.

RolfSander · 2022-05-17T13:58:05Z

Maybe we should rename this file to atoms.kpp?

Agreed

OK, I'll take care of this.

Yes, pandoc somehow didn't bring over text beginning with #.

I noticed that the same problem also occurs for text without #, for
example the "IGNORE" is missing in the description of #CHECK:

"The _____ atom can also be used to control mass balance checking."

Maybe the problem is that pandoc could not treat the self-defined
command \code{...} in the LaTeX file of the user manual.

RolfSander · 2022-05-17T14:01:15Z

Agreed. We should rename that. I can do that in the docs branch.

Oops. I overlooked that you volunteered to do this...

Yes, please go ahead if you want...

RolfSander · 2022-05-17T14:18:03Z

index.html:

the KPP license is GPL, not MIT
The doi points to a GEOS-Chem-specific archive. No need to change this
now, but eventually we should get a generic DOI for KPP-3.0.0.

We have removed the models/atoms file and renamed that to models/atoms.kpp, so that all important files will have an extension. Also updated the symbolic links in the various ci-tests folders. Signed-off-by: Bob Yantosca <yantosca@seas.harvard.edu>

models/saprc99.spc models/saprcnov.spc models/small_strato.spc Changed #INCLUDE atoms to #INCLUDE atoms.kpp Signed-off-by: Bob Yantosca <yantosca@seas.harvard.edu>

msl3v · 2022-05-18T02:47:00Z

04_input_for_kpp.html
Can an example of #DECLARE be provided?

(There's a lot of KPP I didn't know about!)

RolfSander · 2022-05-18T07:05:57Z

Can an example of #DECLARE be provided?

I haven't used #DECLARE myself but I think the idea is this: If
NSPEC is a Fortran PARAMETER, a clever compiler can insert its value
into C(NSPEC) at compile-time. A stupid compiler will look up the
value of NSPEC every time it encounters C(NSPEC). If NSPEC=7, KPP
can directly generate C(7) for those stupid compilers.

msl3v · 2022-05-18T12:16:20Z

Very good explanation It seems like a lot of thought went into getting inefficiencies ironed out.

…

On 5/18/22 03:06, Rolf Sander wrote: Can an example of #DECLARE be provided? I haven't used |#DECLARE| myself but I think the idea is this: If |NSPEC| is a Fortran PARAMETER, a clever compiler can insert its value into |C(NSPEC)| at compile-time. A stupid compiler will look up the value of |NSPEC| every time it encounters |C(NSPEC)|. If NSPEC=7, KPP can directly generate |C(7)| for those stupid compilers. — Reply to this email directly, view it on GitHub <#41 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/ABVE23YY32XBQ6SQBDMKVW3VKSJGDANCNFSM5WC3H74A>. You are receiving this because your review was requested.Message ID: ***@***.***>

RolfSander · 2022-05-18T12:25:43Z

Running KPP with an example mechanism has also been updated to list
things more in a step-by-step fashion.

Thanks, this section has improved a lot!

(I fixed a small error about SUN)

RolfSander · 2022-05-18T13:15:50Z

Another idea regarding atoms.kpp: I would like to add Pls and Min
as "pseudo-atoms" here. If these are used in the elemental composition
of ions in the *.spc file, it becomes possible to check the charge
balance of the equations.

In MECCA, we use this for ions in the aqueous phase and also for ions in
the upper atmosphere.

docs/source/getting_started/02_running_kpp_sample_mech.rst - Updated the doc to explain that the user does not need to copy the other files to the example folder. Also include the small_strato.def file with comments. models/small_strato.def - Add comments - Remove F77_INLINE Signed-off-by: Bob Yantosca <yantosca@seas.harvard.edu>

Signed-off-by: Bob Yantosca <yantosca@seas.harvard.edu>

The second line of {} comments within the F90_INIT caused a compilation error. These have now been removed for all *_INIT blocks in small_strato.def. The manual page has also been updated. Signed-off-by: Bob Yantosca <yantosca@seas.harvard.edu>

docs/source/getting_started/02_running_kpp_sample_mech.rst - Reorder sections in the KPP definition file description so that they match the order listed in the definition file small_strato.kpp models/small_strato.def - Now place {} comments above the _INIT sections, to avoid compile-time errors Signed-off-by: Bob Yantosca <yantosca@seas.harvard.edu>

docs/source/using_kpp/04_input_for_kpp.rst - Rewrite description of #LUMP w/ text supplied by Mike Long - Add a more detailed description of the #DECLARE command Signed-off-by: Bob Yantosca <yantosca@seas.harvard.edu>

KPP can look for the relevant files to include in the models/, drv/, int/, and examples/ folders, so there is no need to link to these files. In each folder in ci-tests/, only keep the KPP definition file. Also updated the .ci-pipelines/ci-manual-cleanup-script.sh to remove the KPP-generated Makefile in each subfolder in ci-tests. Signed-off-by: Bob Yantosca <yantosca@seas.harvard.edu>

Signed-off-by: Bob Yantosca <yantosca@seas.harvard.edu>

In the current docs branch, the RK RADAU5 integrator option is named kpp_radau5. In the cleanup_int branch we are renaming this to just radau5. Restore the kpp_radau5 in docs in order to get C-I tests to pass. Signed-off-by: Bob Yantosca <yantosca@seas.harvard.edu>

yantosca · 2022-05-18T16:38:25Z

@msl3v: I added your sample text to 04_input_for_kpp.rst, and added a better description of the #DECLARE command. I rewrote the 02_running_kpp_sample_mech.rst to remove the commands to copy the files over to the example folder. I also reordered the explanation of each command in the example.

docs/source/getting_started/02_running_kpp_sample_mech.rst - Move "we will now look at the following..." to before the #MODEL small_strato section - Removed extraneous word "species" - Fixed broken ref links - Indented the equations section to fall under ".. code_block::" - Trimmed trailing whitespace Signed-off-by: Bob Yantosca <yantosca@seas.harvard.edu>

Reword some sentences in the "Running KPP with an example stratospheric mechanism" for better readability. Signed-off-by: Bob Yantosca <yantosca@seas.harvard.edu>

yantosca · 2022-05-18T17:06:09Z

@RolfSander @msl3v let me know when the doc is good enough to move to release 2.5.0 ...

Signed-off-by: Bob Yantosca <yantosca@seas.harvard.edu>

Forgot to add it in the last update Signed-off-by: Bob Yantosca <yantosca@seas.harvard.edu>

RolfSander · 2022-05-18T17:21:22Z

let me know when the doc is good enough to move to release 2.5.0 ...

We still have to improve the documentation but that shouldn't stop us
from releasing 2.5.0 now.

Since the documentation is now online, people will always find the
latest version at kpp.readthedocs.io, even if they have 2.5.0 locally on
their computers.

docs/source/getting_started/00_revision_history.rst - Added variables and files in :code: or :file: blocks docs/source/using_kpp/04_input_for_kpp.rst - Updates for readability Signed-off-by: Bob Yantosca <yantosca@seas.harvard.edu>

yantosca · 2022-05-18T17:42:14Z

Great! I'll move to release later today.

This will make the table of contents look consistent, with only the first character of each section & subsection heading capitalized (excluding subsections that are commands etc.) Signed-off-by: Bob Yantosca <yantosca@seas.harvard.edu>

msl3v · 2022-05-19T01:56:03Z

/05_output_from_kpp.html

ROOT_Model: Suggest restating this to something like, "ROOT_Model.f90 unifies all model definitions in a single module. This simplifies inclusion into external Fortran programs.

Table 5: Add that the values are from the small_strato example and maybe hyperlink it to that description.

ROOT_Function: I get a "Math Processing Error" here affter ... example stratospheric mechansim) is:"

Also suggest adding a briefstatement about what Function() does at the beginning of this section.

ROOT_Jacobian: Another Math Processing Error. Also add a statement about the contents of ROOT_Jacobian and ROOT_JacobianSP.

... more later

yantosca added 7 commits May 13, 2022 11:20

Bug fix: Edit comment for Vdotout saved to Fun()

0081e6d

src/gen.c - Change the comment for Vdotout that is added to subroutine Fun(). This fixes a copy-and-paste typo. Signed-off-by: Bob Yantosca <yantosca@seas.harvard.edu>

Added section on C-I tests to "Info for KPP developers" chapter

f024752

Also added some formatting changes Signed-off-by: Bob Yantosca <yantosca@seas.harvard.edu>

Removed warning text about ReadTheDocs being incomplete in index.rst

ebb4b91

Signed-off-by: Bob Yantosca <yantosca@seas.harvard.edu>

yantosca requested review from jimmielin, msl3v, RolfSander and laestrada May 16, 2022 21:43

yantosca self-assigned this May 16, 2022

yantosca added the documentation Improvements or additions to documentation label May 16, 2022

yantosca added this to the 2.5.0 milestone May 16, 2022

yantosca mentioned this pull request May 16, 2022

Create ReadTheDocs documentation for KPP #39

Closed

yantosca linked an issue May 16, 2022 that may be closed by this pull request

Create ReadTheDocs documentation for KPP #39

Closed

yantosca added 2 commits May 17, 2022 14:08

Changed #INCLUDE atoms to #INCLUDE atoms.kpp in species definition files

0098c27

models/saprc99.spc models/saprcnov.spc models/small_strato.spc Changed #INCLUDE atoms to #INCLUDE atoms.kpp Signed-off-by: Bob Yantosca <yantosca@seas.harvard.edu>

SUN

89c693d

RolfSander and others added 11 commits May 18, 2022 15:55

more bug fixes for pandoc-generated rst file

63f9658

for consistency, use the name "Equation tags"

72ca9f9

sentence repaired

2fa6cff

Merge Rolf Sander's docs update w/ Bob Y.'s cleanup of Ch. 2

ec607c9

Signed-off-by: Bob Yantosca <yantosca@seas.harvard.edu>

Updates to "Input for KPP

079810b

docs/source/using_kpp/04_input_for_kpp.rst - Rewrite description of #LUMP w/ text supplied by Mike Long - Add a more detailed description of the #DECLARE command Signed-off-by: Bob Yantosca <yantosca@seas.harvard.edu>

Strip trailing whitespace in the 04_input_for_kpp.rst file

ef87b19

Signed-off-by: Bob Yantosca <yantosca@seas.harvard.edu>

yantosca added 2 commits May 18, 2022 12:46

More text updates in 02_running_kpp_example_mech.rst

4d12dcd

Reword some sentences in the "Running KPP with an example stratospheric mechanism" for better readability. Signed-off-by: Bob Yantosca <yantosca@seas.harvard.edu>

yantosca added 2 commits May 18, 2022 13:12

Bug fix in 04_input_for_kpp.rst: Indent code blocks in #DECLARE section

f033968

Signed-off-by: Bob Yantosca <yantosca@seas.harvard.edu>

Add missing ..code-block:: F90 in #DECLARE section of "Input for KPP

7bdf412

Forgot to add it in the last update Signed-off-by: Bob Yantosca <yantosca@seas.harvard.edu>

RolfSander approved these changes May 18, 2022

View reviewed changes

Fixed a couple more documentation issues

1b115c8

docs/source/getting_started/00_revision_history.rst - Added variables and files in :code: or :file: blocks docs/source/using_kpp/04_input_for_kpp.rst - Updates for readability Signed-off-by: Bob Yantosca <yantosca@seas.harvard.edu>

yantosca merged commit c2c790f into dev May 18, 2022

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

ReadTheDocs documentation for KPP 2.5.0 #41

ReadTheDocs documentation for KPP 2.5.0 #41

yantosca commented May 16, 2022

RolfSander commented May 17, 2022

RolfSander commented May 17, 2022

RolfSander commented May 17, 2022

RolfSander commented May 17, 2022

RolfSander commented May 17, 2022

yantosca commented May 17, 2022 •

edited

Loading

yantosca commented May 17, 2022 •

edited

Loading

RolfSander commented May 17, 2022

RolfSander commented May 17, 2022

RolfSander commented May 17, 2022

msl3v commented May 18, 2022

RolfSander commented May 18, 2022

msl3v commented May 18, 2022 via email

RolfSander commented May 18, 2022

RolfSander commented May 18, 2022

yantosca commented May 18, 2022

yantosca commented May 18, 2022

RolfSander commented May 18, 2022

yantosca commented May 18, 2022

msl3v commented May 19, 2022

ReadTheDocs documentation for KPP 2.5.0 #41

ReadTheDocs documentation for KPP 2.5.0 #41

Conversation

yantosca commented May 16, 2022

RolfSander commented May 17, 2022

RolfSander commented May 17, 2022

RolfSander commented May 17, 2022

RolfSander commented May 17, 2022

RolfSander commented May 17, 2022

yantosca commented May 17, 2022 • edited Loading

yantosca commented May 17, 2022 • edited Loading

RolfSander commented May 17, 2022

RolfSander commented May 17, 2022

RolfSander commented May 17, 2022

msl3v commented May 18, 2022

RolfSander commented May 18, 2022

msl3v commented May 18, 2022 via email

RolfSander commented May 18, 2022

RolfSander commented May 18, 2022

yantosca commented May 18, 2022

yantosca commented May 18, 2022

RolfSander commented May 18, 2022

yantosca commented May 18, 2022

msl3v commented May 19, 2022

yantosca commented May 17, 2022 •

edited

Loading

yantosca commented May 17, 2022 •

edited

Loading