CEP 19 - Cyclus Input Procedure Updates

CEP:

19

Title:

Cyclus Input Procedure Updates

Last-Modified:

2013-10-16

Author:

Dr. Tony Scopes & Robby Flanny

Status:

Withdrawn

Type:

Standards Track

Created:

2013-10-16

Introduction

This CEP proposes to update the Cyclus input paradigm and the module schemas such that they enable a wider variety of tools. This CEP was written with two types of tools in mind: graphical user interfaces and large scale parameter investigations. The goal of this CEP is to give the input scheme the descriptive power it needs to provide users and module developers with an elegent and clear method of building Cyclus input files.

The first major change is to develop a suite of patterns for use by Cyclus module schema. These patterns are meant to richly representing module input fields. These patterns will be a collection of elements that provide sufficient metadata needed by the two use cases listed above. For instance, one such additional element is ‘tooltip’.

The second change is the addition of an interface to modules. This interface will be used in conjuction with the current ‘schema()’ member function. This function will be called ‘default_inputs()’ and return an xml input file snippit for the facility with default values in all input fields.

Motivation

CycIC (and other less useful interfaces) requires this new suite of patterns to provide users with a better experience. For example integrated module documentation is part of this proposal. In addition, many elements of the pattern will also be useful for parametric sweeps.

Specification & Implementation

The following patterns are proposed to be added to the master Cyclus schema.

Tooltip

Tooltip elements is a short string of text that the developer can add to an input field that will show when a user scrolls over this field in the graphical user interface. This is an optional field.

<define name="tooltip">
  <element name="tooltip">
    <data type="string" />
   </element>
</define>

Help

Help elements will provide a more thorough explaination of the input field, it can be accessed through the graphical user interface. This is an optional field.

<define name="help">
  <element name="help">
    <data type="string" />
  </element>
</define>

Units

Units elements apply information to an input field that indicate to the user what units are attached to the value in this field.

<define name="units">
  <element name="units">
    <data type="string" />
  </element>
</define>

User Level

User level elements allow developers to set the user level of a specific input field. This value ranges from 0 to 10 with 0 being simple inputs and 10 being very advanced inputs. This is an optional field and if left blank the value will be set to zero by the graphical user interface.

<define name="userLevel">
  <element name="userLevel">
    <choice>
      <value>0</value>
      <value>1</value>
      <value>2</value>
      <value>3</value>
      <value>4</value>
      <value>5</value>
      <value>6</value>
      <value>7</value>
      <value>8</value>
      <value>9</value>
      <value>10</value>
    </choice>
  </element>
</define>

Vary

The ‘vary’ element is a special boolean element that allows a Cyclus user to set wether the input field it is attached to can be varied for a parametric study. This flag is optional and can take the values “true”, “false”, “1”, “0”.

<define name="vary">
  <element name="vary">
    <data type="boolean" />
  </element>
</define>

Sampling Function

Sampling function is an element that goes with the vary element. If the vary element is set to true a sampling function is required to provide the sampling behavior for the element. This is a string input that represents the mathematical expression of the sampling function. This is an optional flag.

<define name="samplingFunction">
  <element name="samplingFunction">
    <data type="string" />
  </element>
</define>

Field Types

The field types used for input fields are listed below. In general they are associated with a specific data type. In addition there are several field types that are categorical. This implies that the field has discrete values for which it can take.

<define name="floatField">
  <element name="floatField">
    <interleave>
      <element name="value">
        <data type="double" />
      </element>
      <optional>
        <element name="lower">
          <data type="double" />
        </element>
      </optional>
      <optional>
        <element name="upper">
          <data type="double" />
        </element>
      </optional>
      <optional>
        <ref name="userLevel" />
      </optional>
      <optional>
        <ref name="vary" />
      </optional>
      <optional>
        <ref name="samplingFunction" />
      </optional>
      <optional>
        <ref name="tooltip" />
      </optional>
      <optional>
        <ref name="help" />
      </optional>
      <optional>
        <ref name="units" />
      </optional>
    </interleave>
  </element>
</define>

<define name="intField">
  <element name="intField">
    <interleave>
      <element name="value">
        <data type="int" />
      </element>
      <optional>
        <element name="lower">
          <data type="int" />
        </element>
      </optional>
      <optional>
        <element name="upper">
          <data type="int" />
        </element>
      </optional>
      <optional>
        <ref name="userLevel" />
      </optional>
      <optional>
        <ref name="vary" />
      </optional>
      <optional>
        <ref name="samplingFunction" />
      </optional>
      <optional>
        <ref name="tooltip" />
      </optional>
      <optional>
        <ref name="help" />
      </optional>
      <optional>
        <ref name="units" />
      </optional>
    </interleave>
  </element>
</define>

<define name="boolField">
  <element name="boolField">
    <interleave>
      <element name="value">
        <data type="boolean" />
      </element>
      <optional>
        <element name="lower">
          <data type="boolean" />
        </element>
      </optional>
      <optional>
        <element name="upper">
          <data type="boolean" />
        </element>
      </optional>
      <optional>
        <ref name="userLevel" />
      </optional>
      <optional>
        <ref name="vary" />
      </optional>
      <optional>
        <ref name="samplingFunction" />
      </optional>
      <optional>
        <ref name="tooltip" />
      </optional>
      <optional>
        <ref name="help" />
      </optional>
      <optional>
        <ref name="units" />
      </optional>
    </interleave>
  </element>
</define>

<define name="stringField">
  <element name="stringField">
    <interleave>
      <element name="value">
        <data type="string" />
      </element>
      <optional>
        <ref name="userLevel" />
      </optional>
      <optional>
        <ref name="vary" />
      </optional>
      <optional>
        <ref name="samplingFunction" />
      </optional>
      <optional>
        <ref name="tooltip" />
      </optional>
      <optional>
        <ref name="help" />
      </optional>
      <optional>
        <ref name="units" />
      </optional>
    </interleave>
  </element>
</define>

<define name="blobField">
  <element name="blobField">
    <interleave>
      <element name="value">
        <data type="base64Binary" />
      </element>
      <optional>
        <ref name="userLevel" />
      </optional>
      <optional>
        <ref name="vary" />
      </optional>
      <optional>
        <ref name="samplingFunction" />
      </optional>
      <optional>
        <ref name="tooltip" />
      </optional>
      <optional>
        <ref name="help" />
      </optional>
      <optional>
        <ref name="units" />
      </optional>
    </interleave>
  </element>
</define>

<define name="categoricalBlobField">
  <element name="categoricalBlobField">
    <interleave>
      <element name="value">
        <data type="base64Binary" />
      </element>
      <element name="categories">
        <list>
          <oneOrMore>
            <data type="base64Binary" />
          </oneOrMore>
        </list>
      </element>
      <optional>
        <ref name="userLevel" />
      </optional>
      <optional>
        <ref name="vary" />
      </optional>
      <optional>
        <ref name="samplingFunction" />
      </optional>
      <optional>
        <ref name="tooltip" />
      </optional>
      <optional>
        <ref name="help" />
      </optional>
      <optional>
        <ref name="units" />
      </optional>
    </interleave>
  </element>
</define>

<define name="categoricalStringField">
  <element name="categoricalStringField">
    <interleave>
      <element name="value">
        <data type="string" />
      </element>
      <element name="categories">
        <list>
          <oneOrMore>
            <data type="string" />
          </oneOrMore>
        </list>
      </element>
      <optional>
        <ref name="userLevel" />
      </optional>
      <optional>
        <ref name="vary" />
      </optional>
      <optional>
        <ref name="samplingFunction" />
      </optional>
      <optional>
        <ref name="tooltip" />
      </optional>
      <optional>
        <ref name="help" />
      </optional>
      <optional>
        <ref name="units" />
      </optional>
    </interleave>
  </element>
</define>

<define name="categoricalIntField">
  <element name="categoricalIntField">
    <interleave>
      <element name="value">
        <data type="int" />
      </element>
      <element name="categories">
        <list>
          <oneOrMore>
            <data type="int" />
          </oneOrMore>
        </list>
      </element>
      <optional>
        <ref name="userLevel" />
      </optional>
      <optional>
        <ref name="vary" />
      </optional>
      <optional>
        <ref name="samplingFunction" />
      </optional>
      <optional>
        <ref name="tooltip" />
      </optional>
      <optional>
        <ref name="help" />
      </optional>
      <optional>
        <ref name="units" />
      </optional>
    </interleave>
  </element>
</define>

<define name="categoricalFloatField">
  <element name="categoricalFloatField">
    <interleave>
      <element name="value">
        <data type="double" />
      </element>
      <element name="categories">
        <list>
          <oneOrMore>
            <data type="double" />
          </oneOrMore>
        </list>
      </element>
      <optional>
        <ref name="userLevel" />
      </optional>
      <optional>
        <ref name="vary" />
      </optional>
      <optional>
        <ref name="samplingFunction" />
      </optional>
      <optional>
        <ref name="tooltip" />
      </optional>
      <optional>
        <ref name="help" />
      </optional>
      <optional>
        <ref name="units" />
      </optional>
    </interleave>
  </element>
</define>

Cycic Specific Tags

In order to facilitate loading Cyclus scenarios that were previously built with CycIC some additional fields are proposed to be added to the xml grammar. These fields will hold information on how to display the graphical parts of the simulation.

This portion of the xml file will not be read by Cyclus, and should have no impact on the Cyclus core code.

Top level Information

Here the name of the CycIC simulation, a description, and some comments about it can be saved.

<define name="cycicSimulation">
  <element name="cycicSimulation">
    <element name="name">
      <data type="string" />
    </element>
    <element name="description">
      <data type="string">
    </element>
    <element name="comments">
      <data type="string">
    </element>
    <oneOrMore>
      <ref name="facilityCircle" />
    </oneOrMore>
    <oneOrMore>
      <ref name="marketCircle" />
    </oneOrMore>
    <oneOrMore>
      <ref name="regionShape" />
    </oneOrMore>
    <oneOrMore>
      <ref name="institutionShape" />
    </oneOrMore>
  </element>
</define>

Facility Circles

Here the initital proposal is to save the x and y locations of the facilities so that they may be loaded in the proper place.

<define name="facilityCircle">
  <element name="facilityCircle">
    <element name="name">
      <data type="string" />
    </element>
    <element name="xPosition">
      <data type="double">
    </element>
    <element name="xPosition">
      <data type="double">
    </element>
  </element>
</define>

Market Circles

Here the initital proposal is to save the x and y locations of the markets so that they may be loaded in the proper place.

<define name="marketCircle">
  <element name="marketCircle">
    <element name="name">
      <data type="string" />
    </element>
    <element name="xPosition">
      <data type="double">
    </element>
    <element name="xPosition">
      <data type="double">
    </element>
  </element>
</define>

Region Shapes

Here the initital proposal is to save the x and y locations of the region nodes so that they may be loaded in the proper place.

<define name="regionShape">
  <element name="regionShape">
    <element name="name">
      <data type="string" />
    </element>
    <element name="xPosition">
      <data type="double">
    </element>
    <element name="xPosition">
      <data type="double">
    </element>
  </element>
</define>

Institution Shapes

Here the initital proposal is to save the x and y locations of the institution nodes so that they may be loaded in the proper place.

<define name="regionShape">
  <element name="regionShape">
    <element name="name">
      <data type="string" />
    </element>
    <element name="xPosition">
      <data type="double">
    </element>
    <element name="xPosition">
      <data type="double">
    </element>
  </element>
</define>

Document History

This document is released under the CC-BY 3.0 license.

References and Footnotes

References