Template File Syntax (Reference)
================================

File Layout
-----------
All attribute template and instance files must use
<SMTK_AttributeSystem> as the root XML element.

.. code-block:: xml

  <?xml version="1.0"?>
  <SMTK_AttributeSystem Version="2">

    <!-- children elements (sections) -->

  </SMTK_AttributeSystem>

The following table shows the XML
Attributes that can be included in this XML Element.

.. list-table:: XML Attributes for <SMTK_AttributeSystem> Element
   :widths: 10 40
   :header-rows: 1

   * - XML Attribute
     - Description

   * - Version
     - **(Required)**
       Integer value that indicates the SMTK attribute format

       Valid values are 1 or 2

The root <SMTK_AttributeSystem> element can contain
the following optional children XML Elements:

- Includes : used for including additional attribute files (see `Includes Section`_)
- AdvanceLevels : used to define various advanced-access levels used in
  GUIs (see `Advance Levels Section`_)
- Categories : used to define workflow specific categories (see `Categories Section`_)
- Analyses : used to define analysis groups (see `Analyses Section`_)
- Definitions : used to define attribute definitions (see `Definitions Section`_)
- Attributes : used to define attributes
- Views : used to define various Views (used to create GUIs)
- ModelInfo : deprecated

Includes Section
--------------------
The attribute format supports the ability to include other attribute
files.  This allows designers to assemble a complete attribute
description by referencing attribute files that represent specific
aspects.  For example a set of attribute definitions may be referenced
by several different simulation workflows.  Below is an example of
including two attribute files both located in a subdirectory
IncludeTest.

.. code-block:: xml

  <Includes>
    <File>includeTest/b.xml</File>
    <File>includeTest/a.xml</File>
  </Includes>

Each include file is contained within a File XML Element.

Advance Levels Section
-------------------------------------
This section is used to assign access levels to the editing fields
in GUIs created using SMTK's Qt Attribute classes.  For example, a
workflow could consist of the following advance levels:

- General
- Intermediate
- Expert

Using  the <AdvanceLevels> element the following represents the above
access levels.

.. code-block:: xml

  <AdvanceLevels>
    <Level Label="General" Color="0.0, 1.0, 0.0"> 0 </Level>
    <Level Label="Intermediate" Color="1.0, 1.0, 0.0"> 1 </Level>
    <Level Label="Expert" Color="1.0, 1.0, 0.0"> 2 </Level>
  </AdvanceLevels>

The value of each Level XML Element determines the  ordering
of the access levels and are used by the items contained within
Definitions.  Notice that in :ref:`the GUI example <GUIExample>`,
the upper left corner "Show Level" entry is based on the Advance Levels.

Advance Level Element Format
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Each advance level is represented by using a <Level> XML Element.  The
value of the element determines the absolute access level and should
not be repeated amoung sibling Level Elements.  The higher the value
the more "advance" the level.

The following table shows the XML
Attributes that can be included in this XML Element.

.. list-table:: XML Attributes for <Level> Element
   :widths: 10 40
   :header-rows: 1

   * - XML Attribute
     - Description

   * - Label
     - **(Required)**
       String value representing the access level name to be displayed
       in the GUI

   * - Color
     - (Optional)
       String value representing the color to be used when displaying
       items that are associated with this access level.  The format
       is "r, g, b" where r, g, and b are a value between 0 and 1
       inclusive


Categories Section
-----------------------------
This is an optional section describing the set of categories used
within the file.  Items within Definitions can then be associated with
these categories.  In addition, analyses are defined as sets of
categories.  For example, the following xml would define the following
categories:

- Constituent Transport
- Heat Transfer
- Flow
- Time
- General

.. code-block:: xml

  <Categories>
    <Cat>Constituent Transport</Cat>
    <Cat>Heat Transfer</Cat>
    <Cat>Flow</Cat>
    <Cat>Time</Cat>
    <Cat>General</Cat>
  </Categories>

Each category is contained within a Cat XML Element.

The following table shows the XML
Attributes that can be included in <Categories> Element.

.. list-table:: XML Attributes for <Categories> Element
   :widths: 10 40
   :header-rows: 1

   * - XML Attribute
     - Description

   * - Default
     - String value representing the default categories a Definition's
       Item belongs to when no category is specified.

Analyses Section
---------------------------
This is an optional section for defining analyses.  An analysis is
defined as a collection of categories.  For example, using the
categories defined in the `Categories Section`_, the following XML would
define two analyses (Ground Water Flow, and Ground Water with Heat
Transfer).

.. code-block:: xml

  <Analyses>
    <Analysis Type="Groundwater Flow">
      <Cat>Flow</Cat>
      <Cat>General</Cat>
      <Cat>Time</Cat>
    </Analysis>
    <Analysis Type="Groundwater Flow with Heat Transfer">
      <Cat>Flow</Cat>
      <Cat>General</Cat>
      <Cat>Heat Transfer</Cat>
      <Cat>Time</Cat>
    </Analysis>
  </Analyses>

Analysis Element Format
^^^^^^^^^^^^^^^^^^^^^^^
Each Analysis is defined within an <Analysis> XML Tag.

The following table shows the XML
Attributes that can be included in this XML Element.

.. list-table:: XML Attributes for <Analysis> Element
   :widths: 10 40
   :header-rows: 1

   * - XML Attribute
     - Description

   * - Type
     - **(Required)**
       String value representing the type of analysis being
       defined. Note that the type should be unique with
       respect to all other analyses being defined.


Each element contains a set of Cat XML Elements.

Definitions Section
---------------------------------
This is an optional section that defines a set of attribute
definitions used to specify the inputs to a simulation package.
This section is created using the <Definitions> XML Element.
See :ref:`the example XML <XMLExample>` for how to create a set
of attribute definitions.

The <Definitions> element is composed of a set of <AttDef> XML Elements.

AttDef Element Format
^^^^^^^^^^^^^^^^^^^^^
The <AttDef> element defines an attribute definition.
It can include the following XML attributes:

.. Note: Use pipe character to force newlines in list-table below

.. list-table:: XML Attributes for <AttDef> Element
   :widths: 10 40
   :header-rows: 1
   :class: smtk-xml-att-table

   * - XML Attribute
     - Description

   * - Type
     - **(Required)**
       String value representing the attribute definition type
       being defined.

       |

       Note that this value should be unique with respect to all
       other definitions being defined in this section, as well
       as all definitions being included via the <Includes> XML
       Element (See `Includes Section`_)

   * - Abstract
     - (Optional)
       Boolean value used to indicate if the definition is abstract.

       |

       If not specified, the definition is not abstract.
       Note that abstract definitions can not generate attributes.

   * - AdvanceLevel
     - (Optional)
       Integer value used to indicate the advance level associated
       with the definition and the attributes it generates.

       |

       This value should match one of the advance values
       defined in the `Advance Levels Section`_.
       If not specified, 0 is assumed.

   * - BaseType
     - (Optional)
       String value representing the attribute defintion that this
       definition is derived from.

       |

       Note that the base definition must be defined prior to this
       definition, either in this section or in a file specified
       in the Includes section.

   * - Label
     - (Optional)
       String value representing the text to display in a GUI.

       |

       Note that if not specified, the Type value is displayed.

   * - Nodal
     - (Optional)
       Boolean value used to indicate if the attribute effects the
       nodes of the analysis mesh or the elements.

       |

       If not specified the definition's attributes are not nodal.

   * - RootName
     - (Optional)
       String value used for assigning default names to attributes
       generated from this definition.

       |

       When an attribute is created, SMTK will assign
       a unique name if one is not provided to the API.
       Internally-assigned attributes names are generated from the
       RootName plus a numerical suffix.
       If not specified, the Type XML attribute is used.

   * - Unique
     - (Optional)
       Boolean value used to indicate if the attributes this definition
       generates are unique with respect to its model entity associations.
       A model entity can only have one attribute of a given unique
       type associated with it.

       |

       If not specified, the definition is assumed to be non-unique.

   * - Version
     - (Optional)
       Integer value representing the "version" of the definition.

       |

       The Version is not used internally by SMTK, but is provided
       for applications to track life-cycle changes to the definition.
       If not specified, 0 is assumed.


   * - Associations
     - **DEPRECATED in <SMTK_AttributeSystem> Version 2**.

       Use <AssociationsDef> element for Version 2 files.

       |

       String value indicating what type of model entities this
       definition's attributes can be associated on.
       (Optional)

       |

       The information is represented as a string consisting of
       a set of the following characters separated by vertical
       bars (|):

       |

       |  v (vertices)
       |  e (edges)
       |  f (faces)
       |  r (volumetric regions)
       |  m (model)
       |  g (groups)

       |

       An example would be "e|f" for an attribute which may
       be associated with both edges and faces.
       If not specified, the definition's attributes can not be
       associated with any model entities.

The <AttDef> element can contain the following children XML Elements:

.. list-table:: XML Children Elements for <AttDef> Element
   :widths: 10 40
   :header-rows: 1

   * - XML Child Element
     - Description

   * - <AssociationsDef>
     - Specifies which model entity types, if any, can be associated
       with attributes created from this definition.
       (Optional)

       |

       The contents of the <AssociationsDef> element are the
       same as the contents of the
       :ref:`ModelEntityItemDefinition` element.

   * - <BriefDescription>
     - Short description of the definition,
       typically 1-2 lines, suitable for GUI mouse-hover text.
       (Optional)

   * - <DetailedDescription>
     - Detailed description of the definition.
       (Optional)

   * - <DefaultColor>
     - String value representing the color to be used when coloring
       model entities that are associated with this definition's
       attribute by default.
       (Optional)

       |

       The format is "r, g, b" where r, g, and b are values between 0.0
       and 1.0 inclusive.
       If not specified, the value is "0, 0, 0".

   * - <ItemDefinitions>
     - A container for the individual items making up the contents
       of the definition.
       (Optional)

       |

       See `Item Definitions Format`_.

   * - <NotApplicationColor>
     - String value representing the color to be used when coloring
       model entities that are *not* associated with this
       definition's attribute.
       (Optional)

       |

       The format is "r, g, b" where r, g, and b are values between 0.0
       and 1.0 inclusive.
       If not specified, the value is "0, 0, 0".


Item Definitions Format
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
This subsection of an AttDef Element contains the definitions of all the
items to be created within the attributes created by the attribute
definition.  The section is represented by the <ItemDefinitions> XML
Element and can contain any of the elements decribed in the
`Item Definition Section`_.

Item Definition Section
------------------------

Item Definition Types
^^^^^^^^^^^^^^^^^^^^^^
Item definitions are used to specify and enumerate specific data
types and their corresponding requirements and constraints for
<AttDef> elements. The individual Item Definition elements,
which are children of the <ItemDefinitions> element, include:

.. omitting <MeshSelection>

.. list-table:: Item Definition XML Element Types
  :widths: 10 40
  :header-rows: 1

  * - Item Definition
    - Description

  * - <AttributeRef>
    - References attribute instances.
      Analogous, in some ways, to pointers used in C and
      other programming languages.

  * - <Dir>
    - References directories in the local filesystem.

  * - <Double>
    - Represents floating-point numbers, including expressions.

  * - <File>
    - References files in the local filesystem.

  * - <Group>
    - Represents ordered groups of item definitions.
      Analogous, in some ways, to structures used in C
      and other programming languages.

  * - <Int>
    - Represents fixed-point numbers.

  * - <MeshEntity>
    - References mesh collection or mesh set instances.

  * - <Model>
    - References model entity instances.

  * - <String>
    - Represents text strings.

  * - <Void>
    - No data. Typically used to represent on/off options.


Item Definition XML Attributes
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Item Definition elements can include the following XML
attributes. Note that some XML attributes only valid for
certain item definitions.

.. list-table:: XML Attributes for Item Definition Elements
   :widths: 10 10 40
   :header-rows: 1

   * - XML Attribute
     - Item Definitions
     - Description

   * - Name
     - all
     - **(Required)**
       String identifier for the item definition.

       |

       The Name must be unique with respect to all
       other item definitions contained within this attribute definition
       (including its Base Type).

   * - AdvanceLevel
     - all
     - (Optional)
       Integer value used to indicate the advance level associated
       with items created from this item definition.

       |

       This value should match one of the advance values
       defined in the `Advance Levels Section`_.
       If not specified, 0 is assumed.

   * - Extensible
     - <AttributeRef>

       <Dir>

       <Double>

       <File>

       <Group>

       <Int>

       <MeshEntity>

       <Model>

       <String>

     - (Optional)
       Boolean value indicating that the size of the data array
       is not fixed for items created from this item definition,
       but can be extended.

       |

       When Extensible is true, items created from this item definition
       shall stored a minimum number of elements set by NumberOfRequiredValues
       (for <Group> item definitions, NumberOfRequiredGroups).
       The maxiumum number can be optionally specified by MaxNumberOfValues
       (for <Group> item definitions, MaxNumberOfGroups).

   * - IsEnabledByDefault
     - all
     - (Optional)
       Boolean value indicating if the item is considered to be
       enabled by default.

       |

       Note this is only used when Optional="true".
       If not specified, the item is considered to be disabled.

   * - Label
     - all
     - (Optional)
       String to use as the label in editors or other GUI
       elements that display items created from this item definition.

       |

       If not specified, Name is used.

   * - MaxNumberOfGroups
     - <Group>
     - (Optional)
       Integer value indicating the maximum size of the array for
       each GrouptItem created from this item definition.

       |

       Only applicable if the item definition specified as Extensible.

   * - MaxNumberOfValues
     - <AttributeRef>

       <Dir>

       <Double>

       <File>

       <Int>

       <MeshEntity>

       <Model>

       <String>

     - (Optional)
       Integer value indicating the maximum size of the data array for
       each item created from this item definition.

       |

       Only applicable if the item definition specified as Extensible.

   * - MultipleLines
     - <String>
     - (Optional)
       Boolean indicating if the preferred user interface displays
       a multiple-line editor for string items created from
       this item definition.

       |

       If not specified, then a single-line editing field
       is assumed.

   * - NumberOfRequiredGroups
     - <Group>
     - (Optional)
       Integer value indicating the size of the array for
       each GrouptItem created from this item definition.

       |

       If the item definition is Extensible, then
       NumberOfRequiredGroups represents the *minimum* number of
       groups in each item created from this item definition.
       If not specified, NumberOfRequiredGroups is 1.

   * - NumberOfRequiredValues
     - <AttributeRef>

       <Dir>

       <Double>

       <File>

       <Int>

       <MeshEntity>

       <Model>

       <String>

     - (Optional)
       Integer value indicating the size of the data array for
       each item created from this item definition.

       |

       If the item definition is Extensible, then
       NumberOfRequiredValues represents the *minimum*
       number of values in each item created from this item definition.
       If not specified, NumberOfRequiredValues is 1.

   * - Optional
     - all
     - (Optional)
       Boolean value indicating if items created from this definiiton are
       considered optional or required.

       |

       If not specified, the item are considered to be required.

   * - Units
     - <Double>

       <Int>

       <String>
     - (Optional)
       String value used as a units label for editors and other
       GUI elements.

   * - Version
     - all
     - (Optional) Integer value representing the "version" of the item definition.

       |

       The Version is not used internally by SMTK, but is provided
       for applications to track life-cycle changes to the item definition.
       If not specified, 0 is assumed.


..
  For now, leave Secured, AdvanceReadLevel and AdvanceWriteLevel
  undocumented, since they were provided for a special/custom use case

   * - AdvanceReadLevel
     - all
     - Integer value used to indicate the advance read level associated
       with the item.
       (Optional)

       This value should match one of the advance values
       defined in the `Advance Levels Section`_.
       Note that this is ignored if the AdvanceLevel XML Attribute is used.

       If not specified, 0 is assumed.

   * - AdvanceWriteLevel
     - all
     - Integer value used to indicate the advance write level associated
       with the item.
       (Optional)

       This value should match one of the advance values
       defined in the `Advance Levels Section`_.
       Note that this is ignored if the AdvanceLevel XML Attribute is used.

       If not specified, 0 is assumed.


Item Definition Children Elements
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Item Definition elements can contain the following children XML
elements. Note that some children XML elements are only valid for
certain item definitions.

.. list-table:: XML Children Elements for Item Definition Elements
   :widths: 10 10 40
   :header-rows: 1

   * - XML Child Element
     - Item Definitions
     - Description

   * - <BriefDescription>
     - all
     - Provides a brief description of the item (Optional).

   * - <Categories>
     - all
     - Defines the categories that the item belongs to.
       (Optional)

       This element contains at set of <Cat> elements with each
       containing a category defined is the Category Section.

       See `Categories Section`_.

   * - <ChildrenDefinitions>
     - <Double>

       <Int>

       <String>
     - Used in conjunction with <DiscreteInfo> elements to
       specify conditional children items.

       |

       todo: More details

   * - <ComponentLabels>
     - <AttributeRef>

       <Dir>

       <Double>

       <File>

       <Group>

       <Int>

       <MeshEntity>

       <Model>

       <String>

     - Specifies labels to use with item definitions specifying
       multiple elements (via NumberOfRequiredValues).

       |

       For item definitions that are not discrete and have a
       NumberOfRequiredValues greater than 1, it is possible to
       provide a separate label for each element in the array
       stored by the item. For example, a <Double> item definition
       for a 3-D vector could include component labels for each
       coordinate value:

       .. code:: xml

         <ComponentLabels>
           <Label>X: </Label>
           <Label>Y: </Label>
           <Label>Z: </Label>
         </ComponentLabels>

   * - <DefaultValue>
     - <Dir>

       <Double>

       <File>

       <Int>

       <String>
     - For double, integer, string, and filesystem items,
       this element's text
       contains the default value for the item. This element is
       not allowed for other ItemDefinition types. (Optional)

       |

       For items that are not discrete and not extensible but do have
       NumberOfRequiredValues greater than 1, it is possible to
       provide a different default value for each component.
       In this case, commas are assumed to separate the values.
       If you wish to use a different separator, specify the "Sep"
       attribute on the DefaultValue tag.

       |

       For example, a String item with 2 components might use

       |

       .. code:: xml

          <DefaultValue Sep=":">Yep:maybe</DefaultValue>

       to specify different defaults for each component.
       You can also use the separator to prevent a default value
       from having per-component values. For instance, the same
       String item might use

       |

       .. code:: xml

          <DefaultValue Sep=":">Commas, OK</DefaultValue>

       to force the default value to have a single entry used to
       initialize all components.

   * - <DetailedDescription>
     - all
     - Provides a detailed description of the item (Optional).

   * - <DiscreteInfo>
     - <Double>

       <Int>

       <String>
     - Specifies a discrete set of values that can be assigned to
       items created from this item definition.

       |

       *todo: More details for discrete items*

   * - <ExpressionType>
     - <Double>
     - Specifies the Type of attribute (same as its <AttDef> Type)
       to represent the value of the <Double> item.

       |

       Conceptually, any <AttDef> can be used as an expression,
       although SMTK provides a GUI for one specific <AttDef> layout.

       |

       *todo: More details for SMTK expressions*

   * - <ItemDefinitions>
     - <Group>
     - **(Required)**
       The container for individual item definitions making up
       the contents of the <Group> item definition.

       |

       Children elements can be any valid list of item definitions
       (including other <Group> item definitions, which can be used
       to define a hierarchy of item definitions). This simple example
       shows a <Group> item definition with 3 children item
       definitions, comprising two <Double> and one <Int> types.

       .. code:: xml

         <Group Name="test-data">
           <ItemDefinitions>
             <Double Name="pressure" />
             <Double Name="temperature" />
             <Int Name="number-of-observers" />
           </ItemDefinitions>
         </Group>

       Although not shown in the example, <Group> item definitions
       may contain <Group> item definitions, allowing hierarchical
       tree structures to be defined.

   * - <RangeInfo>
     - <Double>

       <Int>
     - (Optional)
       Defines the range of valid values for <Double> or
       <Int> item definitions.

       |

       The <RangeInfo> element can have 1 or 2 children
       elements: (i) a <Min> element specifying the minimum
       valid value, and/or (ii) a <Max> element specifying
       a maximum valid Value. Both <Min> and <Max> elements
       can include an optional "Inclusive" XML attribuite
       to indicate if the specified value itself is valid.
       If the "Inclusive" attribute is not specified, a
       "false" value is assumed.

       |

       An example of the <RangeInfo> for a <Double> item definition:

       .. code:: xml

         <Double Name="range-example">
           <RangeInfo>
             <Min Inclusive="true">2.71828</Min>
             <Max Inclusive="false">3.14159</Max>
           </RangeInfo>
         </Double>


Basic Value Items
^^^^^^^^^^^^^^^^^^^^^^^^




XML attributes
^^^^^^^^^^^^^^^^^^^^^^^

Children elements
~~~~~~~~~~~~~~~~~

File Item Definition <File>
"""""""""""""""""""""""""""
.. todo::

   Describe file items and how they are serialized

Group Item Definition <Group>
"""""""""""""""""""""""""""""
.. todo::

   Describe group items and how they are serialized

Integer Item Definition <Int>
"""""""""""""""""""""""""""""
.. todo::

   Describe integer items and how they are serialized

String Item Definition <String>
"""""""""""""""""""""""""""""""
.. todo::

   Describe string items and how they are serialized

Ref Item Definition <Ref>
"""""""""""""""""""""""""
.. todo::

   Describe attribute reference items and how they are serialized

.. _ModelEntityItemDefinition:

Model Entity Item Definition <Model>
""""""""""""""""""""""""""""""""""""""""""

A :smtk:`ModelEntityItem`, which appears in XML as a <Model> is an
item belonging to an attribute stored as a UUID that refers to an
SMTK model entity.
These model entities may be regions, faces, edges, vertices, or even
higher-level conceptual entities such as models, groups, or instances (used
in modeling scene graphs and assemblies).

.. code-block:: xml

  <Model Name="model" Label="Model" Version="0" NumberOfRequiredValues="1">
    <MembershipMask>model</MembershipMask>
  </Model>


Void Item Definition <Void>
"""""""""""""""""""""""""""
.. todo::

   Describe "void" items and how they are serialized

Views Section <Views>
---------------------------
.. todo::

   Describe root views and how they are serialized


Attribute Section <Attributes>
------------------------------
.. todo::

   Describe attributes and how they are serialized
