What is Model Builder?
======================
ModelBuilder is a platform designed to integrate every process involved in the
whole life cycle of numerical simulation. It combines the individual
preprocessing, solver, and post-processing softwares into one application which
allows the user to create or import geometry, generate or import mesh, assign
simulation parameters to the model, generate the simulation input decks for the
solver, as well as view and process the computational results.

Key Concepts
------------

In order to show how ModelBuilder works, we need to clarify a few concepts:

Model
`````
A model refers to the geometrical representation of the simulation object. It
can be either 2D or 3D. In ModelBuilder, model can be created or imported. The
different origins of the models determines the different operations that can be
applied to them. Common operations include Save, Export, Delete, Add Auxiliary
geometry etc. See :ref:`The Model Tab <model-tab>` for details.

Session
```````
ModelBuilder is capable of handling models created by a variety of applications,
each of them use a different way to represent their model, the interface between
ModelBuilder and the application creates the model is called a session. In other
words, sessions are used to handle models of different origins. For example, the
polygon session is intrinsic to ModelBuilder, which is the only session that
is capable to create a model interactively in ModelBuilder; the discrete session
uses VTK data structures so that it can handle models in VTK. See :ref:`The
Session Operators <session-operators>` for details.

Mesh
````
Mesh is a key component of a lot of computational methods. It is consist of
vertex, edge, face, and their connectivities. It can be imported to ModelBuilder,
but unlike the model, mesh currently cannot be generated by ModelBuilder itself.
However, the users can link their own meshers to MOdelBuilder and then generate
the mesh within the ModelBuilder's framework. Mesh can be deleted, exported,
interpolated etc. See :ref:`The Mesh Tab <mesh-tab>` for details.

Attribute
`````````
Each simulation package (e.g., Albany_, OpenFOAM_, `Deal II`_) accepts
different sets of parameters.
ModelBuilder calls such a set of parameters an *attribute*.
Attributes consist of child *items*, i.e., individual parameters. Besides,
there are conditional parameters which may or may not exist depending on the
values of other items. All the parameters form a tree of items that control the
simulation.

ModelBuilder can be customized for any simulation package by writing:

1. an XML description of the parameters accepted by the simulation
(called a *template*)

2. a Python script (called an *exporter*) that, given particular parameter values
   entered into ModelBuilder GUI, generates an input deck for the simulation

More often, you will use a pre-existing template and exporter.
Some of them come with ModelBuilder and some of them may be provided by your
organization. Refer to `SMTK's Attribute System
<http://smtk.readthedocs.io/en/latest/userguide/attribute/index.html>`_ for details.

Work Flow
---------
The work flow of ModelBuilder can be summarized into the following steps:

1. Model:
As the first step, a geometry model must be created or imported to ModelBuilder.
Further operations such as grouping entities, coloring entities etc. can be
applied to the model.

2. Mesh:
The next step is to generate or import a mesh as described above.

3. Attributes:
The last step is to assign simulation parameters to the model and export,
which further breaks down to:

 a. Load the simulation template as discussed above, and define the simulation
 parameters through the ModelBuilder GUI.

 b. Associate the parameters to the geometry regions in the model.
 For example, while modeling groundwater flow, once the different sediment layers
 are defined, they must be related, or *associated*, to a geometric portion of
 the earth being simulated.

 c. Export the input decks for the solver.
 Finally, once the simulation parameters have been specified and related
 to the geometry, ModelBuilder can be used to *export* an input deck
 for submission to a simulation.

Note that post-processing module has not been developed yet, so the work flow
ends at exporting the simulation inputs.

.. _Albany: http://software.sandia.gov/albany
.. _Deal II: http://www.dealii.org/
.. _OpenFOAM: http://openfoam.org/
