New version of the manual

[rs028]

This includes all the updates (and cosmetic changes) to the User Manual in preparation for release 1.2 (#397).

Note that some things have been moved to the wiki, which now contains only a minimal set of instructions and "extra" information.

[spco]

@rs028 I've pushed 2ba4c6b so FRUIT should install properly now, and not break the builds on the remaining PRs if you rebase the branches to include that fix

[rs028]

Great, thanks!

[codecov]

Codecov Report

Merging #403 into master will not change coverage.
The diff coverage is n/a.

@@           Coverage Diff           @@
##           master     #403   +/-   ##
=======================================
  Coverage   88.72%   88.72%           
=======================================
  Files          17       17           
  Lines        2262     2262           
=======================================
  Hits         2007     2007           
  Misses        255      255           

Flag	Coverage Δ
#build	62.45% <0.00%> (ø)
#tests	87.88% <0.00%> (ø)
#unittests	35.76% <0.00%> (ø)

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 0e08d7c...0e08d7c. Read the comment docs.

[rs028]

@spco Any idea why it fails on mac?

[spco]

Seems that brew install gettext isn't installing libintl.h correctly. I'll have a play.

[spco]

Ok, I've fixed it with #410 . I'm not sure why it's suddenly broken - it must be either the Travis OSX image has changed, or the behaviour of brew install gettext. But just rebase on top of #410 and the build should now work.

Alternatively, just add the change manually to .travis.yml:

if [[ "$TRAVIS_OS_NAME" == "osx" && ! -d /usr/local/Cellar/[email protected]/4.9.4_1/bin ]] ; then brew update ; brew install [email protected] libffi gettext ;  fi

to

if [[ "$TRAVIS_OS_NAME" == "osx" && ! -d /usr/local/Cellar/[email protected]/4.9.4_1/bin ]] ; then brew update ; brew install [email protected] libffi gettext ; brew link gettext --force ;  fi

[spco]

I've just deleted the cache to make the Mac build pass again. However, it may be that the caching isn't working with the brew link step. I'll ask it to run the same build again in a few minutes to see whether that breaks when using the cache.

[spco]

Hmm, seems like the caching breaks the brew link ☹️ will need to work out a fix.

[spco]

Ok, #411 has solved the issue - the issue was that the default gettext version number has incremented to 0.20.1, but numdiff was hard-coded to look for 0.18.0.1.

If this gets incremented again, it will break again - I'm not sure of the best way to address that at the moment.

Please rebase once again :)

[rs028]

Thanks for your help. I guess there is no other way to deal with this than to change the script if it breaks again.

The new manual is slowly coming together and it is the last piece of version 1.2. But we need to decide if PR #408 is going to be included in this version or will remain open for the time being.

[spco]

Yes- I'm spending a bit of time on that today (but had to fix these issues first - sigh), so hopefully I will have a working version for you soon.

[rs028]

Great thank you so much.

PS: did you see my question on this PR?

[spco]

I saw there was a question, but the links were broken because of a later force-push - could you repeat it please?

[rs028]

"The current version of AtChem2 limits the number of species that can be output to 100"
To change this number one needs to modify line 375 of src/outputFunctions.f90. Is this correct?

[spco]

I believe that's the case, from examining the code. You'd also need to modify line 366 to get the header line as well.

[rs028]

Quick question: when you add a path to .profile or .bash_profile (see install of dependencies) is it:

PATH=$PATH:$HOME/.... or export PATH=$PATH:$HOME/....?

I could never understand what is recommended or even the difference. It seems the kind of thing everybody has a different opinion about.

[spco]

export will make the variable available to subprocesses, rather than just the current shell. So use export if you want subprocesses to use the new value.

There is nothing special about .bash_profile or .profile except that they are run at the point when the shell starts up.

I don't think it makes much difference in our case - I would go for export in general to make it clear that all subprocesses will also use the same value, which perhaps reduces the cognitive load when debugging.

[rs028]

@spco is the limit on the number of species that can be output still present? I tried to test it but it seems it there is no limit. Was it removed? Maybe one of the changes to outputFunctions.f90 in Aug 2018?

[spco]

From my understanding, Fortran is able to use reversion to repeat the given format string. So while we have

write (50, '(100 (ES15.6E3)) ')

we could just as easily write

write (50, '(ES15.6E3)')

and it would repeat the format string as many times as needed. I am not able to test that right now, but could you try it out?

[rs028]

No, that is not what I mean. In the paper we say "the output of the calculated concentrations is
currently limited to 100 chemical species selected by the user in the model configuration (Sect. 2.5), although this number can be changed by modifying the Fortran source code."
However when I tried to list 200 species in outputSpecies.config the model output all of them. So I was wondering if this limitation has been removed more recently.

[spco]

I think the only "limitation" to 100 was the use of write (50, '(100 (ES15.6E3)) '), but in hindsight I think that Fortran is already repeating the ES15.6E3 as many times as is required, so the "limitation" does not in fact exist anyway. That's how I understand things, if you say that printing 200 works fine. I don't think there's been a change to the code, but rather when we wrote the documentation we were conservative and assumed Fortran would only output 100, which doesn't turn out to be true. Does that make sense?

[rs028]

I think so, thanks for the clarification.

[rs028]

@spco could you please have a quick look at the new text in the Development chapter, especially the Test Suite section to check that it is all correct?

[spco]

I think that's all fine in the Test section - perhaps at the top of p45, where it mentions FRUIT, I think that's the first time FRUIT is mentioned, so perhaps you could explain that then? (or refer back to §2.3.2 ?)

[rs028]

I think this is finished now (finally!). Anything to add?

Quick question: the testsuite.log file is generated only if there is a fail, right?

[spco]

2 comments, looks great otherwise :)

[rs028]

Great thanks. Did you see the question about testsuite.log?

[spco]

Ah yes. You are correct - it's only generated upon failure.

[rs028]

Ok, with this I think it is done. Merge?

[spco]

Looks good. Thanks for the enormous amount of work you've put into this!