ReadTheDocs documentation for KPP 2.5.0

[yantosca]

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.

[RolfSander]

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]

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]

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]

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]

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]

"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]

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]

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]

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]

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.

[yantosca]

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...

atoms is now atoms.kpp in commit 0098c276010ad65ec225f1e08fb7a5bbfa84d16e

[yantosca]

@RolfSander, I think I've fixed most of the remaining issues in commits https://github.com/KineticPreProcessor/KPP/pull/41/commits/1597faf8b6eb8f96cc86f4b122cda72540b1d8f4, https://github.com/KineticPreProcessor/KPP/pull/41/commits/6c563cd04b7f6f24b584ee2c1c249ef303b6de87, and https://github.com/KineticPreProcessor/KPP/pull/41/commits/7bca904e511e6055f148b98ba0d658c7609ac13c.

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

[msl3v]

• "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.

On "Input for KPP", should #INCLUDE atoms.kpp be #INCLUDE atoms? or is "atoms" being renamed to "atoms.kpp"?

[msl3v]

04_input_for_kpp.html Suggest rewriting

"The example below shows how the concentration of can be replaced by the sum of concentrations for and which is considered to be a single variable. At the end of the integration, the concentration of is computed by substraction from the lumped variable."

to

"In the example below, species NO and NO2 are summed and treated as a single lumped variable, NO2. Following integration, the individual species concentrations are recomputed from the lumped variable."

[msl3v]

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

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

[RolfSander]

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]

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 https://github.com/KineticPreProcessor/KPP/pull/41#issuecomment-1129648486, or unsubscribe https://github.com/notifications/unsubscribe-auth/ABVE23YY32XBQ6SQBDMKVW3VKSJGDANCNFSM5WC3H74A. You are receiving this because your review was requested.Message ID: @.***>

[RolfSander]

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]

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.

[yantosca]

@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.

[yantosca]

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

[RolfSander]

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.

[yantosca]

Great! I'll move to release later today.

[msl3v]

/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