GENIE BFG Files
Example BFG metadata files
Examples of BFG definition, composition and deployment files are discussed below. A description of BFG itself can be found here: What is the Bespoke Framework Generator (BFG)?
Example Definition file
The example definition file below shows definition data for model "arg1". Note that this is a "scientific" model rather than a "transformation" model. There are two initialisation entry points, "init1" and "init2", an update entry point "ts" and a deinitialisation entry point "finalise". A constraint is specified: init1 must be called before init2. Fields are mostly "argpass" - passed in and out of models through arguments to the entry point subroutines, however one field of init2 is "inplace" - a put that happens under the init2 entry point within the model source code itself. Note that inplace fields will be associated with an entry point even in the case of "minimally compliant" models that contain their own control code - at least one entry point must be supplied to BFG so that it can start the model running. The model timestep is 10 framework timesteps, meaning that the "ts" subroutine will only run on every 10th iteration of the framework update loop.
| <?xml version="1.0" encoding="UTF-8"?> |
| <!-- edited with XML Spy v4.4 U (http://www.xmlspy.com) by Rupert Ford (Manchester Informatics Ltd.) --> |
| <definition xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="C:\Documents and Settings\rupert\My Documents\work\bfg2\definition.xsd"> |
| <name>arg1</name> |
| <type>scientific</type> |
| <language>f90</language> |
| <entryPoints> |
| <entryPoint type="init" name="init1"> |
| <data direction="in" form="argpass" id="1" dataType="real" dimension="0"/> |
| <data direction="out" form="argpass" id="2" dataType="real" dimension="0"/> |
| </entryPoint> |
| <entryPoint type="init" name="init2"> |
| <data direction="in" form="argpass" id="1" dataType="real" dimension="0"/> |
| <data direction="inout" form="argpass" id="2" dataType="real" dimension="0"/> |
| <data direction="out" form="argpass" id="3" dataType="real" dimension="0"/> |
| <data direction="out" form="inplace" id="7" dataType="real" dimension="0"/> |
| </entryPoint> |
| <entryPoint type="iteration" name="ts"> |
| <data direction="in" form="argpass" id="1" dataType="real" dimension="0"/> |
| <data direction="inout" form="argpass" id="2" dataType="real" dimension="0"/> |
| <data direction="in" form="argpass" id="3" dataType="logical" dimension="0"/> |
| </entryPoint> |
| <entryPoint type="final" name="finalise"/> |
| <constraints> |
| <constraint ep1="init1" expression="precedes" ep2="init2"/> |
| </constraints> |
| </entryPoints> |
| <timestep>10</timestep> |
| </definition> |
Example Composition file
The example composition file below shows different methods of priming for the initialisation entry points "init1" and "init2" of model "simpleMixed1": from a namelist, NetCDF file, constant, another entry point (argument ID 1 of init2 is primed from argument ID 3 of init1), and internally (priming by the model itself). The composition file also demonstrates connections between coupling fields made using set notation (for "argpass" coupling) and point-to-point notation (for "inplace" coupling):
- The timestep subroutines for models "simpleMixed1" and "simpleMixed2" share a field through argpass coupling (argument ID 1 for both timestep subroutines). Whether the field is input or output from the respective models is determined by the data "direction" attributes for the ID 1 arguments in the definition file (examples of which are shown in section 5.1). Note that the order entry point subroutines are called in (the schedule, found in the deployment file) also affects where arguments go from and to, as discussed in section 3.2.2.
- A second field is shared between models "simpleMixed1" and "simpleMixed2" through inplace coupling. The field is sent by put ID 2 (which occurs under the "simpleMixed1" timestep subroutine), and is received by get ID 3 (which occurs under the "simpleMixed2" timestep subroutine).
| <?xml version="1.0" encoding="UTF-8"?> |
| <!-- edited with XML Spy v4.4 U (http://www.xmlspy.com) by Rupert Ford (Manchester Informatics Ltd.) --> |
| <composition xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="C:\Documents and Settings\rupert\My Documents\work\bfg2\composition.xsd"> |
| <connections> |
| <priming> |
| <model name="simpleMixed1"> |
| <entryPoint name="init1"> |
| <primed id="1"> |
| <file type="namelist" dataRef="r1a" nlName="data" name="bfg2Data.in"/> |
| </primed> |
| <primed id="2"> |
| <file type="netcdf" dataRef="real1" name="bfg2Data.nc"/> |
| </primed> |
| <primed id="5"> |
| <data dimension="0" datatype="real" value="3.14"/> |
| </primed> |
| </entryPoint> |
| <entryPoint name="init2"> |
| <primed id="1"> |
| <model name=" simpleMixed1" entryPoint="init1" id="3"/> |
| </primed> |
| <primed id="2"> |
| <internal/> |
| </primed> |
| </entryPoint> |
| </model> |
| </priming> |
| <timestepping> |
| <set> |
| <field modelName=" simpleMixed1" epName="timestep" id="1"/> |
| <field modelName=" simpleMixed2 " epName="timestep" id="1"/> |
| </set> |
| <modelChannel inModel="simpleMixed2" outModel="simpleMixed1"> |
| <epChannel outEP=" timestep" inEP=" timestep"> |
| <connection outID="2" inID="3"/> |
| </epChannel> |
| </modelChannel> |
| </timestepping> |
| </connections> |
| </composition> |
Example Deployment file
The example deployment file below represents a concurrent framework deployed as a single executable (deployment unit). The deployment unit contains two sequence units: the first sequence unit is run by two threads (MPI processes), and consists of models "single" and "single2"; the second sequence unit consists of just one model ("multiple") run by three threads. An alternative implementation would be to place each sequence unit in a separate deployment unit (executable). The schedule in the second half of the file provides the order for the framework control code. In a sequential implementation of the framework, this would also be the order of execution for the model entry points, but in the concurrent implementation given below the "multiple" timestep entry point may not necessarily run after the "single2" and "single" subroutines, as the multiple model is part of a different sequence unit. In contrast, the threads running the "single" and "single2" models are guaranteed to run those models in the order indicated by the schedule because they both belong to the same sequence unit. The schedule also shows that 100 iterations of the framework timestep loop will be carried out. This doesn't necessarily mean that the models will be called every iteration: each model has its own timestep, set in the definition data for that model - for instance, model "single2" may only be run every 10th iteration.
| <?xml version="1.0" encoding="UTF-8"?> |
| <!-- edited with XML Spy v4.4 U (http://www.xmlspy.com) by Rupert Ford (Manchester Informatics Ltd.) --> |
| <deployment xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="C:\cygwin\bfg2\schema\deployment.xsd"> |
| <deploymentUnits> |
| <deploymentUnit language="f90"> |
| <sequenceUnit threads="2"> |
| <model name="single"/> |
| <model name="single2"/> |
| </sequenceUnit> |
| <sequenceUnit threads="3"> |
| <model name="multiple"/> |
| </sequenceUnit> |
| </deploymentUnit> |
| </deploymentUnits> |
| <target>mpi</target> |
| <schedule> |
| <bfgiterate> |
| <init> |
| <model name="multiple" ep="init1"/> |
| <model name="multiple" ep="init2"/> |
| </init> |
| <iterate> |
| <loop niters="100"> |
| <model name="single2" ep="singlesub"/> |
| <model name="single" ep="singlesub"/> |
| <model name="multiple" ep="tstep1"/> |
| </loop> |
| </iterate> |
| <final> |
| <model name="multiple" ep="finish"/> |
| </final> |
| </bfgiterate> |
| </schedule> |
| </deployment> |