Some essentials about the Object Modelling System

This post is to give people the taste of what OMS is. For the Installations, please refer to the Installation page.  The user manual introduction can be found below:

• OMS User Manual - Introduction (pdf, epub) 

• The philosophy behind OMS/GEOframe (YouTube video 2019, YouTube2020)
• The GEOframe deployment (YouTube2020)
• A brief introduction to the Object Modelling System (Vimeo2021, older version of it: YouTube video 2019,YouTube2020, Also on VIMEO2020)
• OMS User Manual - Introduction (pdf, epub) 
• The OMS working environment (Vimeo 2021, an older version: YouTube video 2020)
• OMS User Manual - The working Environment (pdf, epub)
• The structure of a .sim file (Vimeo2021, an older version of it: YouTube video 2019, YouTube2020)
• The existing manual excerpt (outdated but still useful) (pdf, epub)
• The OMS console (YouTube2020)
• Examples 2020.
• Examples 2019 (All the material in the .zip files. Notebooks in /docs folder)
• ex_00 (zip files)
• Examples-basic (zip files). Please find Jupyter notebook shown in video below in the doc directory of the zipped files.
• Example 001 (YouTube video 2019)
• Controlling Iteration (Ex 05) YouTube video 2019.
• Going on with examples: Again on You Tube Video Iteration, Bulk connect, Feedbacks
• Exercises 1&2
• Watertank  Example (zip files). Documentation in the doc folder.
• Water Tank example - Part I YouTube video 2019
• Exercises 3&4
• Creating a notebook from the scratch (Live YouTube video 2019 by Niccolò Tubini)

Radiation for hydrologists

At the Winter School we usually skip this part on radiation, not because it is not important. It is a fundamental part for getting right evaporation, transpiration and the snow budget.  However time is really constrained and we have to do some choices. Please, the interested reader can give a look to slides and concept themselves. 

Some very elementary slides about the sun:

• The Sun
• Stefan-Boltzmann law
• From Sun to Earth

Now some more complicate topics

• Copying with Earth Surface
• Shortwave absorptions by the atmosphere (Vimeo2020, YouTube video)
• Considering clouds (Vimeo2020, YouTube video)
• Shortwave-Terrain geometries (Vimeo2020, YouTube video)
• Longwave radiation (Vimeo2020, YouTube video)
• Table of Symbols

References

Corripio, J. G. (2002). Modelling the energy balance of high altitude glacierised basins in the Central Andes. Ph.D Dissertation, 1–175.

Corripio, J. G. (2003). Vectorial algebra algorithms for calculating terrain parameters from DEMs and solar radiation modelling in mountainous terrain, 17(1), 1–23.

Formetta, G., Rigon, R., Chávez, J. L., & David O. (2013). Modeling shortwave solar radiation using the JGrass-NewAge system. Geoscientific Model Development, 6(4), 915–928. http://doi.org/10.5194/gmd-6-915-2013

Formetta, G., Bancheri, M., David, O., & Rigon, R. (2016). Performance of site-specific parameterizations of longwave radiation. Hydrology and Earth System Sciences, 20(11), 4641–4654. http://doi.org/10.5194/hess-20-4641-2016

Installations of the 2021 GEOframe environment for Linux operative systems

Installation of the 2021 GEOframe environment on Linux

Credits to: Martin Morlot, martin.morlot@unitn.it

 

1) Install anaconda & openjdk-8:

check https://docs.anaconda.com/anaconda/install/linux/ and https://openjdk.java.net/install/ for instuctions for your distributions

 

2) create GeoFrame folder and change directory to it (in terminal):

mkdir GeoFrame

cd GeoFrame

 

3) Clone python4GEOframe  github repository (in terminal):

git clone git@github.com:geoframecomponents/python4GEOframe.git

 

4) Download, oms-console,  Ex01 and notebook test using your browser:

https://alm.engr.colostate.edu/cb/wiki/16961

https://osf.io/5e9jp/download

https://osf.io/fzy5g/download

- unzip them inside the Geoframe folder using your choice of file-extractor for the purpose.

 

5) Change directory to where you cloned python4GEOframe, and to anaconda_envs (using previously opened terminal):

cd python4GEOframe/Anaconda_envs

 

6)Activate anaconda in linux (in a terminal):

source /opt/anaconda/bin/activate root

 

7) Create environment for geoframe:

conda env create -f geoframe_rossano.yaml (will take some time)

 

8) activate the environmental created:

conda activate geoframe_rossano

 

9) set your conda java_home

export  JAVA_HOME=~/.conda/envs/geoframe_rossano/jre/

 

10) execute console.sh in new terminal:

cd GeoFrame/oms-3.6.28-console

./console.sh

 

11) set /home/$USERNAME/.conda/envs/geoframe_rossano/jre/ while replacing $USERNAME with your username  in the OMS console java home setting as in the instructions slides (slide 11)

 

12) run ex_1 as in the instructions slides that you can find at https://osf.io/xes9y/ (slide 12, 13) to check that it works.

 

13) run the notebook excercise: open jupyter notebook with your preferred jupyter editor (ie. Vscode, spyder) set interpreter to conda env created python ( ~/.conda/envs/geoframe_rossano/bin/python3) then run the notebook as specified in the instructions (slide 17)

Go to Installations on Windows

Go to Installations for Mac

Installations of the 2021 GEOframe environment and related information

 In this post you will find all what is requested to run the GEOframe models and tools.  GEOframe requires Python and Java and it is built upon the OMS3 infrastructure. However, you are not requested or assumed to know them for using GEOframe. We will communicate the appropriate notions during the classes but the interested can find plenty of courses on the web.

A presentation was prepared to explain what to install and how. You can find it by clicking on the figure below.

Installations of OMS and GEOframe environment 2021.1 from Ri Rigon on Vimeo.

An installation of the OMS3/GEOframe environment 2020.1 - "Rossano" from Ri Rigon on Vimeo.

For any problem contact us through the mailing list https://groups.google.com/forum/#!forum/geoframe-winter-schools. 

What is actually installed and why

• Java. GEOframe and OMS are written in Java and they require to have installed Java on your computer. Here you can find instructions to install Java on your computer.  Java JDK is installed using the Anaconda package manager. So, essentially you do not have to take care of it.  If you want to do it differently,  please note that you need the Java Development Toolkit (JDK) installed not the Java Runtime Environment (JRE).  You can watch several videos for Windows here but Windows user can follow our previous blogpost.  For Macs, look at here. Googling you can get more videos and information. 
• OMS v 3 Console. It is possible to use Docker to execute the programs but, after the experience of the last year with Docker installations on Windows, we preferred to use directly the Console. The OMS system installation traditional information can be found here: https://alm.engr.colostate.edu/cb/wiki/16961 and https://alm.engr.colostate.edu/cb/wiki/17107.
  

• To start the Console from Windows, just click on the .bat file
• To start the Console from Mac OSX or Linux, open a Terminal and execute:
• % ./console.sh &
• The "&" just free the command line back and gives it back to you. 

• During the School we will use Jupyter and Python 3 for data management and visualisation. It would be great if you could arrive with Jupyter installed.
• The post at this link contains all the information needed. For installation of the software, we suggest Anaconda. 
• To understand what a Jupyter notebook is about, please see its manual. However, we will use Jupyterlab.  (You can see a YouTube video about here).  One can think that Jupyter was heavily based on the look-and-feel of Mathematica notebooks: but Jupyterlab is a step ahead to something different. Installing Anaconda, you also have already installed Jupyter notebook. You can open Jupyter lab by the Anaconda Console, or issuing the command  Jupyter lab at a terminal (called DOS prompt in Windows).

• The manual of Jupyterlab is here.
• BTW, it will be useful to have also a GIS of your choice installed. We suggest QGIS.

Go to Installations for Linux

Go to the Index

Go to the next task (Radiation for hydrologists)

Why Excel is evil

 

The GEOframe Winter School 2021

The third edition of the Winter School on GEOframe (GWS2021) will be held between January 7 and 16, 2021 in Trento, Italy. The course is devoted to Ph.D. Students, Post-docs, Young researchers (and Professionals!) interested in estimating all the components of the hydrological cycle (rainfall, evapotranspiration, snow-melting, and river discharge). The system allows to work out catchments from very small to continental (e.g. Abera et al., 2017a,b), up to build operational solutions, as the one used in in Basilicata. The aim of the course is to enable participants to run their own simulations and, eventually, on their own catchments and estimate the hydrological budget components. Previous Winter school material is freely available at the GEOframe blog.
Compared to what was done in the past courses, there will be more practice and a more detailed work on evapotranspiration and rainfall-runoff. It will be much more focused on exercises and on getting the water budget performed under various hypotheses on models' structure.

Due to COVID-19/COVID-SARS-2 the lectures and the work will be limited to, at most, 10 people in presence but it will be possible to follow the class remotely either synchronous online and asynchronous online (we’ll use a “blended” type of teaching based on Zoom). There is no fee or subscription for the asynchronous classes (and no personal support, just the support coming through the geoframe users mailing list). Synchronous  classes with no personal support though require subscription and the payment of a small fee of 10 Euros or (for Italians) a subscription to the Italian Hydrological Society. However, who requires a certificate of participation, and want personal support, must pay a fee (150 euros). Getting the certificate will be subject to present a report and an analysis of a catchment performed with the GEOframe tools. Tourists are  welcomed but obviously real learning requires exercise and some effort.

Instructors will be

• Prof. Riccardo Rigon, Ph.D. (GS)
• Prof. Giuseppe Formetta, Ph.D. (GS)
• Ing. Marialaura Bancheri, Ph.D. (GS)
• Ing. Niccolò Tubini, Ph.D. candidate
• Ing. Concetta D’Amato, Ph.D student

Participants

• Participants resumè

Topics:

• Homework to do before the School - Installations and introduction to the Object Modelling System Infrastructure and Jupyter
• Homework -  Radiation for Hydrologists
• Day 1- Hydrologic Response Units delineation and treatment of spatial features
• Day 2- Interpolation of hydrometeorological datasets 
• Day 3 - Exercise with your own catchments under instructors supervision
• Day 4 - Evaporation and Transpiration with GEOframe-Prospero
• Day 5 - Modelling lumped models with GEOframe-ERM
• Day 6 - Adding features to your modellingg with ERM
• Day 7 - Looking forward

Next Day/Task

Subscriptions for having credits for this class and support can be obtained all year long after January 15,  2021: please visit https://webapps.unitn.it/form/en/Web/Application/winterschool/GEOframeWS2021 and compile the form or write to abouthydrology@gmail.con with subject: GWS2021 if you need more information. After payment of the fee you can have individual support and gain the participation certificate if you setup and perform an exercise with the GEOframe tools. You can do it on a your own catchment or we can provide you with a catchment and the required data. 

GEOframe Community Publication Policy (GCPP v 1.0)

After GEOframe is becoming widely used we believe it is time to set some fair rules for participation to GEOframe related publications, Since the components are usually released under GPL3 license, it allows the of the code almost without any restriction (except the maintaining the derived code Open Source and freely available), a condition mitigated by the fact that different OMS components can be released under other licenses.  However, because all of our recognition derives from publications (and proper citations), it is worth to remark what written below (partially derived from Jules community publication policies):

GEOframe Community Publication Policy (GCPP v1.0)

1. Introduction

GEOframe-NewAge is an open-source, semi-distributed, component-based hydrological modeling system. It was developed in Java and based on the environmental modeling framework Object Modeling System V3 (OMS3). 

The core of the project was born from the idea of Professor Rigon and mainly developed at the department of civil, environmental and mechanical engineering of University of Trento, Italy. During the last decade, GEOframe community grew and now is made of many scientists around the world who share their work, codes, knowledge and experiences for the benefit of all GEOframe users, whilst pursuing their individual research interests and careers.

Therefore, giving appropriate credits for the intellectual input through co-authorships or citations should be the proper functioning of the community.

This document sets out how members of the GEOframe community should recognise the intellectual contribution of the GEOframe community’s members. 

1. Principal web references

In the following, the principal GEOframe web references, where you can find the latest achievements, developments, publications, code versions, courses and ideas are reported: 

- http://abouthydrology.blogspot.com/search/label/GEOFRAME 

- http://geoframe.blogspot.com

- https://github.com/geoframecomponents

- https://github.com/GEOframeOMSProjects 

• https://osf.io/fk8ta/

1. General principles

The formal, legal conditions that govern the use of GEOframe at present are given by the G.P.L. v 3. Each GEOframe component can have its own license though. 

This Policy applies to all uses of GEOframe products, including but not limited to data and computer code, for research and teaching. It is not intended to restrict what can be done with them, rather to ensure appropriate acknowledgement and communication between users and developers. This policy will be updated regularly.

A developer is any person whose expertise has either significantly influenced the design of GEOframe code or who has written code, with no distinction between scientific and technical inputs.

Developers are encouraged to publish their work in reasonable time, while potential users should approach developers early in their study to avoid duplication or wasted effort on new developments. Developers may reserve the right for the first scientific application of their scheme and will be able to advise if and when co-authorship, citation or acknowledgement is appropriate. 

A list of new developments and the scientists responsible for them will be maintained on the GEOframe website. These contributions should be recognised by citations.

When writing the source code of a component, GEOframe developers should consider the following:

• Provide a brief description of what the program does.
• State the authors of the code and the following modifiers.
• Describe the input required to run the component and its output.
• Some notes concerning the limitations, and the algorithms used within the component. A wish-list for the future version and/or information.
• Articles or books which have inspired the codex or justified its necessity. Users are encouraged to cite these papers in their own work.
• A more detailed documentation about the code can be found in (link alla pagina con la documentazione delle componenti e il template per LaTeX.
• If you want to contribute code or documentation, create pull requests, we will consider them.

Ideally a committed code should conform to the rules required by Joss. 

Acknowledgments should be considered for a wider list of scientists who contributed to the modelling system, but whose contributions may not be documented in publications. A list of such scientists will be maintained on the GEOframe web page

When writing a paper, GEOframe users and developers should consider the following:

Co-authorship  

• Is expected if your research benefited from a new development, i.e. the development influenced your study to the extent that it was discussed in the paper. 
• Is expected if your research required substantial direct input from a developer, e.g. to make substantial modifications to the code that you used, to help design the experiments etc.
• Should be considered for a wider list of scientists who contributed to the modelling system, but whose contributions may not be documented in publications. A list of such scientists will be maintained on the GEOframe web page.
• Developers cannot claim the first (or primary) authorship of a paper where they did not contributed in writing and conceiving the main research topics. 

Acknowledgements 

• Should be considered for scientists involved in GEOframe code developments that have become established.

Citation of a published paper 

• Is expected if a citable paper describing a development exists. A narrative description of the model and a list of papers describing developments will be maintained on the GEOframe web page.

Please be generous in offering credit for other people’s work, as everyone benefits in the end. Use best judgement and, if in doubt, err on the side of inclusiveness.

You can find the pdf and Epub version of the document by clicking on the links. For the readers can also be interesting to consider the reading of About Authorship in Hydrology.