create par


The page defines the application programing interface specification for the par operation.


The command line interface for the par catagory of operations is:

usage: flashkit create par TEMPLATES [<flg>...]
Create an flash parameter file using specified templates and sources.

arguments:  
TEMPLATES      LIST  Specify a list of template files (e.g., rayleigh) to search for, without the
                     '.toml' extension. These will be combined and used to create the flash.par file.

options:
-p, --params   DICT  Specific parameters; which are collected in a section at the end of the parameter file.
-s, --sources  LIST  Which library defined sources to use for filling sections from configuration files;
                     defaults to ['space', 'mesh'] --> will fill domain and processor grid parameters).
-d, --dest     PATH  Path to parameter file; defaults to cwd.

flags:
-A, --auto           Force use of all templates specified in all configuration files and library sources.
-N, --nosources      Do not use any library specified template sources; AUTO takes precedences.
-D, --duplicates     Allow the writing of duplicate parameters if there are multiple matches.
-F, --nofile         Do not write the calculated coordinates to file. 
-R, --result         Return the calculated coordinates. 
-I, --ignore         Ignore configuration file provided arguments, options, and flags.
-O, --options        Show the available options (i.e., defaults and config file format) and exit.
-S, --available      List the available library defined sources and exit.
-h, --help           Show this message and exit.

notes:  If duplicates are not allowed, only the most significant instance of a parameter will be written to
        the parameter file, which means the parameter will be based on the depth-first-merge of all relavent 
        templates (and not SOURCES from configuration file variables, which is also the case with --ignore).

        The order of precedence for parameters with potential duplicate entries in ascending order is:
        0) specificed sources retrieved from library defaults
        1) depth-first-merge of specified sources retrieved from a depth-first-merge of configuration files,
        2) depth-first-merge of specified sources in templates (as per 1 above); templates are merged at each level,
        3) depth-first-merge of explicitly specified parameters in templates; templates are merged at each level,
        4) parameters provided at the command line.

Please consult the discussion on command line syntax for help in formating the above options (e.g., LIST or DICT).


The python interface for the par operation is accessed with the following code:

from flashkit import flash
...
flash.create.par(option=value, flag=True, ...)

The python interface specification for par is as follows:

par(**arguments: Any) → Optional[Any]

Python application interface for using templates to create a FLASH runtime parameter file.

This method creates a FLASH parameter file (INI format) using options and specified templates implemented in toml files to enable runtime context to the creation of parameter files. This supports improved consitancy, reproducability, and confidence in research. Additionally, the intent is to preserve human readability of the produced FLASH parameter file.

Keyword Arguments

  • templates (list) – Specify a list of template files (e.g., rayleigh) to search for, without the ‘.toml’ extension. These will be combined and used to create the flash.par file.

  • params (dict) – Specific parameters; which are collected in a section at the end of the parameter file.

  • sources (list) – Which library defined sources to use for filling sections from configuration files.

  • dest (str) – Path to parameter file.

  • auto (bool) – Force use all templates specified in all configuration files and library sources.

  • nosources (bool) – Do not use any library specified template sources; AUTO takes precedences.

  • duplicates (bool) – Allow the writing of duplicate parameters if there are multiple matches.

  • nofile (bool) – Do not write the calculated coordinates to file.

  • result (bool) – Return the calculated coordinates.

  • ignore (bool) – Ignore configuration file provided arguments, options, and flags.

Notes

If duplicates are not allowed, only the most significant instance of a parameter will be written to the parameter file, which means the parameter will be based on the depth-first-merge of all relavent templates (and not SOURCES from configuration file variables, which is also the case with –ignore).

The order of precedence for parameters with potential duplicate entries in ascending order is.

  1. specificed sources retrieved from library defaults

  2. depth-first-merge of specified sources retrieved from a depth-first-merge of configuration files,

  3. depth-first-merge of specified sources in templates (as per 1 above); templates are merged at each level,

  4. depth-first-merge of explicitly specified parameters in templates; templates are merged at each level,

  5. parameters provided at the command line.


The complete specification of library defaults values (as shown above) and mappings is as follows:

The following library defaults are provided for flashkit create par:

Options          Default Values
-------          --------------
sources          ['space', 'mesh']
dest             --
nofile           False
result           False


The following outlines the general section options, which can be mapped
in the configuration file, that are provided for flashkit create par:

Options          flash.toml Sections and Options
-------          -------------------------------
dest             [general.paths]
                 working = ...

nofile           [general.pipes]
                 nofile = ...

result           [general.pipes]
                 result = ...

Please consult the tutorial discussion on configuration file formating for help in specifying the above options in a flash.toml file and what mapping general options are, as well as the full specification on FlashKit library options.


The complete specification of library template sources is as follows:

The following library template key/value pairs are provided:
with the tags of <['sources']> defined in each section

 Section: space

Parameter	sources
---------	-------
xmin		['general', 'space', 'xrange', '_0']
xmax		['general', 'space', 'xrange', '_1']
ymin		['general', 'space', 'yrange', '_0']
ymax		['general', 'space', 'yrange', '_1']
zmin		['general', 'space', 'zrange', '_0']
zmax		['general', 'space', 'zrange', '_1']

 Section: mesh

Parameter	sources
---------	-------
iProcs		['general', 'mesh', 'iprocs']
jProcs		['general', 'mesh', 'jprocs']
kProcs		['general', 'mesh', 'kprocs']

Please consult the tutorial discussion on template file formating for help in applying the above sources in a template file and what template sources are, as well as the full specification on FlashKit library templates.

create interp create xdmf