User Documentation for PyModelData

Principles

PyModelData uses YAML as native file format. This format is designed to be read and written by humans and programs alike. PyModelData extends YAML to allow the inclusion of external files in YAML or other formats. The simplest use case is a single YAML file that can be parsed with one line of code. More useful is to add a template file, also in YAML, that has declarative definitions of the input. This template can be considered a part of the source code. It will be used to validate the input.

YAML

The format YAML is designed to be used with VHLL (very high level languages) such as Python. It can be parsed directly into Python data structures. A piece of YAML might look like this:

group1:
    item1:
        value: myValue

group2:
    item1:
        value: 
               - 1
               - 2
               - 3
    # comment

It will be parsed into a dictionary of dictionaries and a list:

{'group1': {'item1': {'value': 'myValue'}}, 'group2': {'item1': {'value': [1, 2, 3]}}}

There are a few more syntactic elements but those shown above are the most common for the purposes of PyModelData.

Single File Input

The simplest case is to use just one YAML input file. This can be useful for small scripts and the like.

Input with a Template

A more useful case is to have a template file that serves as declarative input description.

A template might look like this:

general:
    title:
        default: test model for pymodeldata
        unit: None
        comment: >
            describes a very simplified flow model
            for flow through 8 compartments

times:
    start:
        default: 2001-01-01
        required:
            - value
        unit: date
        comment: start of model calculations
        help: >
            This variable holds start date of calculation
            in yyyy-mm-dd format. The default time is 00:00:00.0 .
            Optionally a time may be specifed in the format
            hh:mm:ss.ddd where dd stands for decimal places of seconds.  

External Files

Using the directive !INCLUDE it is possible to include external files:

!INCLUDE
    file_name: geometry.yaml
    file_format: yaml

!INCLUDE
    file_name: connections.txt
    file_format: columns_whitespace
    group_name: connections
    from:
        unit: None
    to:
        unit: None
    overflow_height:
        unit: m
        alias: h

If the included file is in YAML-format, it can in turn include another file. There is no nesting limit for YAML-files. Files in other formats than YAML can not include other files. All meta information about a file in another format need to be made in the YAML file that refers to it.

Usage

Loading a single file without a template requires to specify a mode: either 'model_data' or 'template'. Depending on this mode different StandardProperties are allowed in the file.

import pymodeldata as pmd

input_ = pmd.Input()
input_.value_type = 'model_data'   # 'template' is other option
data = input.load_single('filename.yaml'))

Loading an input file with a corresponding template file is also simple:

import pymodeldata as pmd

input_ = pmd.Input()
data = input_.load(template_file_name, model_data_file_name)

In both cases data is a dictionary with all input data originally contained in the model data file(s) and the template file(s). If data are missing in the model data file, they will be replaced by the default data. If

required:
    - value

is specified in the template file, a value needs to be given in the model data file.