Thursday, November 19, 2015

The long wave radiation component - LWRB

This is the long wave radiation component documentation. It works as usual. Clicking on the image will redirect you to Slihdeshare.
To learn how to use it, please use the documentation below, relative to a modeling solution, which also gives you some data to execute it.
Any suggestion, error report, should be send to the Author of the documentation.


The Simple Water Budget Component - SWB

This document the simple water budget components (SWB) developed by Marialaura Bancheri. It integrates, as explained in the document, the water budget solving the non linear water budget equation. Please read the documentation for details.
Clicking on the image above you will be redirected to the Slideshare site where the document is. Otherwise you can see it on Overleaf here.

Below instead you will find the documentation of a modelling solution using the SWB component.
Please click on the Figure to find it. Otherwise click here for the Overleaf version. 



Thursday, November 12, 2015

The Long wave radiation (LWRB) as an example of uploading the documentation of JGrass-NewAGE

This post uses the long wave radiation component documentation to illustrate how to upload documentation of components. The first operation made, after having used the appropriate template to write in LaTeX the documentation, and produce the pdf file was to upload the component to slideshare. For our internal use, we opened a new slideshare user called NewAGE-GEOtop-doc, at the address:  http://www.slideshare.net/NewAGE-GEOtop-doc.
The pdf file was named like the component itself, i.e. LWRB-linkers. "Linkers" meaning that this documentation is for whom will use the component with others, and are, therefore able to write an OMS3 .sim file (documentation missing here, at the moment), described in the companion LWRB-ms (ms like "modelling solution") documentation file. The pdf has been subsequently loaded to slideshare for having a public repository.
The Figure above is a ,jpg of the first page of the documentation file and clicking on it, the reader is redirected to the full file in slideshare. The jar file containing the component can be found here (missing link). The source code, as specified in the documentation file itself can be found, instead here. 

Mailing lists about GEOtop and JGrass-NewAGE

There are three mailing list active to which any GEOtop or NewaGE users/developer/sympathizer can send request and information:

GEOtop users: it treats questions about GEOtop usage, GEOtop new realeses announcements, GEOtop's physics, parameters setting, suggestions, the production of documentation, etc

GEOtop developers: it treats  about GEOtop bugs, malfunctions, source code, source code development etc.

newAgeUsers: it discusses the use of  Jgrass-NewAGE components, their releases, their physics, parameters setting, and everything about NewAGE

newAgeDevelopers: it discusses the source code of any NewAGE components, question related to the newAGE repository, bugs, the development of new components, the cleaning of old ones, etc.

Everybody can participate.

Saturday, November 7, 2015

Documenting GEOFRAME components

This is a first trial to produce some standard templates for documenting our modeling work (taken verbatim from an Abouthydrology post). It starts from the idea that we use a component-based environment (OMS) and there are at least three types of actors that can use (or help to produce) our software:

  • Developers: these are those who develops the components. What they need to know is the overall scope of the component, its design, its classes, the algorithms it uses and some reference to check it all. 
  • Linkers: these are those who uses the components to create modelling solutions (MS). Their work is made before run-time by means of a scripting language (in our case based on Groovy). In our case they produce a .sim file that allows the execution of the model inside the OMS3 console. They need also to have information about the IO data each component require and they could not be necessarily know the internals of each component, like the cook do not need to know how the cooker internals are made (they call it encapsulation of information, and information hiding, which has a positive connotation in object oriented modeling)
  • Users : They just run MS, but they should also provide information about their run. So one of the template can be used for documenting single runs of MS, specifying the inputs and the setup  of the numerical experiment.

Thus, we actually delineated four types of documentation (for internals, for externals of each component, for their compositions, and for specific runs)  which we can solve with four templates. They are produced in LaTeX and are still experimental:
One could observe that actually these four types of documentation can should be produced at different stages of the component's production.
The Developer documentation should be produced while designing the component, and, potentially, before the component is produces. Its structure can greatly help the design, and avoid the production of software without design.  The Linkers' documentation should be produced just after the production of the component, while the component is tested. The Users documentation which presente assembly (composition) of components during experiments setup, or, if of the fourth type, before (in contemporary) a run is sent.  This implies a little discipline but it would help a lot to save personal and collective time. Besides, it would be easy then to obey to  the requirement of making replicable research.

All of this is work in progress and will be improved during the effective use of the templates. Suggestions are welcomed.

Saying this is to produce components documentation, we still are missing an appropriate type of documentation for Application, like, for instance the OMS console. For this type of documentation, we also have a template, copied from the uDig walktroughs. An example, also in LaTeX, can be found here.