First Notions of Catalogs
==========================
+Catalog
+-------
+
Catalogs are a simple way to express a data model.
It organizes the elements and specifies relationships between them.
This could be seen as a hierarchical model ordered in a tree.
-Catalogs have a python syntax :ref:`python-label`
+Once the catalog is well-defined, EFICAS generates automatically an XSD file which may be customized.
+These are two views of the same data model. This business model is a "kind" of user data template file.
+The user data set python and/or xml file(s) is/are validated in respect to the catalog and/or XSD file.
+One may write these files by hands or using EFICAS-toolkit or EFICAS-gui to generate it.
+
+The generated python/xml parameter files can be seen in two ways :
+
+ 1. This can be seen as an organized way of calling data object contructors with their parameters
+ * Constructing a new user data set that conforms to a dataflow model consists in selecting the desired data objects from the available data organized by the model.
+
+ 2. This can be seen as an a set of computational steps (commands) with their arguments
+ * Constructing a new user commands set that conforms to a workflow model consists in selecting the desired commands from the available commands organized by the model.
+
+| Each selected data/command has its specific parameters that the user must define. Some are required, others require multiple occurrences, others require the user to name the returned concept.
+| A "concept" is a user defined class declaration used to refer it in the catalog. Nothing is prejudged about its implementation.
+| The actual definition/implementation can be found in the context of your code project.
+
+
+| The data/commands available as hierarchical graph roots are called steps.
+| A VIMMP user data/commands set is a collection of 'step'.
+| Each step is a coherent process/part of the complete workflow/dataflow. This allows to understand the whole scheme of the workflow/dataflow.
-The 'root node' is called 'JdC'. it has to be defined as :
-::
-
- JdC = JDC_CATA (
- code = 'MyCodeName',
- )
-
-
-Apart of the root node, catalogs contains three natures of items :
- - terminal leaves or Keyword
- - group of elements :
- - inside elements are leaves or others groups.
- - grouping these elements has significance from the point of view of business data modeling.
- - a set of elements can be conditional : it becomes necessary only if another parameter has a specfic value. (ie wind_direction is needed only if wind_speed is not nul)
- - commands : PROC (shortcut for procedure) or OPER (shortcut for operator).
- - they constitute the second level of the hierachical tree (after root node).
- - both "proc" and "oper" contain other elements (group or leaves).
- - an OPER returns an object (which has to be named and typed), unlike PROC which returns nothing.
+Simulation example
+------------------
+For example, VIMMP platform will typically address/execute the following steps for :
+
+CFD-type simulations :
+~~~~~~~~~~~~~~~~~~~~~~
+
+ * Upload the mesh of the domain (note that the geometry of the domain is contained in the mesh);
+ * Define the physical properties of the fluid(s) involved (e.g., density, viscosity, thermal diffusivity, etc.);
+ * Define the boundary conditions to be applied (e.g., inlet/outlet/symmetry/wall boundaries);
+ * Define the simulation parameters (e.g., time step, number of iterations of the simulated time lapse);
+ * Define the fields to be stored as outputs (note that “classical CFD methods” usually handles fields and, therefore, mesh- and vector-based fields)
+
+DPD-type simulations :
+~~~~~~~~~~~~~~~~~~~~~~
+
+ * Upload the geometry of the domain in which the simulation is to be performed;
+ * Define the physical variables attached to each particle (note that classical DPD formulations, as most particle-based mesoscopic methods, relies on the kinetic approach in which only particle positions and velocities are retained (meaning that 6 variables are attached to each particle). However, this is not necessarily always the case for recent DPD formulations for multi-component systems, such as fluid-colloids systems, and for other particle-based methods used, for instance, in hybrid particle/fluid models. (cf \*)
+ * Define the boundary conditions to be applied (typically, periodic conditions or more involved ones when needed)
+ * Define the physical parameters for the particle system (i.e., masses, electric charges, etc.)
+ * Define the parameters entering the selected expressions of inter-particle forces (e.g., expression and parameters entering the soft potential used for the conservative force between DPD particles, weight function and friction coefficient for the dissipative force, temperature (thermostat) used explicitly in the random or Brownian force, cut-off length for potentials, target values such as temperature and pressure, etc.);
+ * Define the simulation parameters (e.g., time step and number of particles to be simulated in the domain. Note that each particle is a “computational element” similar to a cell in a mesh);
+ * Define the statistics to be extracted from the particle set (e.g., diffusivity, surface tension, etc.), which are the outputs to be mapped to another code in a linked workflow.
+
+*\*Addendum : In some cases, particle forces are not to be regarded as physical variables since no evolution equation is written for them and since they are derived from the knowledge of particle velocities and positions through the chosen Material Relations.*
+
+These several points will be steps for VIMMP data/commands models.
+
+Catalog vocabulary
+------------------
+
+Apart of the root node JDC_CATA, catalogs contains three natures of entities :
+
+ - terminal_symbol : SIMP (SIMPle type) or SIMP_keyword
+ - group_of_eficas_keyword : FACT (shorcut for FACTOR) or BLOC (conditionnal FACT):
+ - content elements are terminal_symbol or group_of_eficas_keyword
+ - grouping these keywords has significance from the point of view of business data modeling.
+ - group_of_eficas_keyword can be conditional and becomes necessary only if another parameter respects a condition (ie wind_direction is needed only if wind_speed is not nul)
+ - eficas_keyword : terminal_symbol or group_of_eficas_keyword
+ - commands : PROC (shortcut for procedure) or OPER (shortcut for operator).
+ - they constitute the second level of the hierachical tree (after root node).
+ - both PROC and OPER contain other keywords (group or terminal_symbol).
+ - an OPER returns a user class, unlike PROC which returns nothing.
+
+Catalogs have a python syntax :ref:`python-label`
Defining steps in a catalog
===========================
-Definition and Usage
-____________________
+Root node
+_________
+The 'root node' is called 'JdC'.
+| It has to be declared at the very begininng in the catalog file such as :
-The generated python parameter files can be seen in two ways :
- * This can be seen as an organized way of calling data object contructors with their parameters
- * This can be seen as an a set of computational steps (commands) with their arguments
-
-| Constructing a new user data set that conforms to a dataflow model consists in selecting the desired data objects from the available data organized by the model.
-| Constructing a new user commands set that conforms to a workflow model consists in selecting the desired commands from the available commands organized by the model.
-
-| Each selected data/command has its specific parameters that the user must define. Some are required, some require multiple occurrences, others require the user to name the returned concept
-
-| The data/commands available as hierarchical graph roots are called steps.
-| A VIMMP user data/commands set is a collection of 'step'.
-| Each step is a coherent process/part of the complete workflow/dataflow. This allows to understand the whole scheme of the workflow/dataflow.
+::
-For example, VIMMP platform will typically address/execute the following steps for :
+ from Accas import *
+
+ jdc = JDC_CATA (
+ code = 'MyCodeName',
+ )
-CFD-type simulations :
- * Upload the mesh of the domain (note that the geometry of the domain is contained in the mesh);
- * Define the physical properties of the fluid(s) involved (e.g., density, viscosity, thermal diffusivity, etc.);
- * Define the boundary conditions to be applied (e.g., inlet/outlet/symmetry/wall boundaries);
- * Define the simulation parameters (e.g., time step, number of iterations of the simulated time lapse);
- * Define the fields to be stored as outputs (note that “classical CFD methods” usually handles fields and, therefore, mesh- and vector-based fields)
-
-DPD-type simulations :
- * Upload the geometry of the domain in which the simulation is to be performed;
- * Define the variables attached to each particle (note that classical DPD formulations, as most particle-based mesoscopic methods, relies on the kinetic approach in which only particle positions and velocities are retained (meaning that 6 variables are attached to each particle).
- However, this is not necessarily always the case for recent DPD formulations for multi-component systems, such as fluid-colloids systems, and for other particle-based methods used, for instance, in hybrid particle/fluid models!);
- * Define the boundary conditions to be applied (when needed)
- * Define the parameters entering the selected expressions of inter-particle forces (e.g., expression and parameters entering the soft potential used for the conservative force between DPD particles, weight function and friction coefficient for the dissipative force, temperature (thermostat) used explicitly in the random or Brownian force);
- * Define the simulation parameters (e.g., number of particles to be simulated in the domain. Note that each particle is a “computational element” similar to a cell in a mesh);
- * Define the statistics to be extracted from the particle set (e.g., diffusivity, surface tension, etc.), which are the outputs to be mapped to another code in a linked workflow.
-These several points will be steps for VIMMP data/commands models.
+Step nodes
+__________
-Syntax
-______
-General syntax
+General syntax
~~~~~~~~~~~~~~
A step can be :
* PROC : a simple procedure
Defining a user concept type
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-To describe an OPER , you have first to describe a user-defined type of concept. Declarations appears at the beginning of the catalogs. User classes inherits from ASSD. Most of the time, pass statement is all you need.
+To describe an OPER , you have first to describe a user-defined type of concept.
+Declarations appears at the beginning of the catalogs. User classes inherits from ASSD. Most of the time, pass statement is all you need.
+
::
from Accas import *
- class myInteger(ASSD) : pass
- class mesh(ASSD) : pass
- class meshEntity(ASSD): pass
+ class myInteger(ASSD) : pass
+ class mesh(ASSD) : pass
+ class meshEntity(ASSD) : pass
class meshNode(meshEntity) : pass
class meshEdges(meshEntity): pass
- class field(ASSD) : pass
+ class field(ASSD) : pass
+
+OPERs return value. The return_type is a user-defined data type.
-OPERs return value. The return_type is a user-definded data type.
::
class mesh(ASSD) : pass
);
+::
+
+ mymesh = ReadMesh(MyFile="/tmp/vimmp.mesh");
+ myField = CalculateField(is_on_mesh=mymesh, calculFunction=...);
+
End user can then define a mesh with ReadMesh OPER (This mesh will be named) and then uses this mesh in order to defined a Field....
Other useful attributes
Definition and Usage
____________________
-Sometimes, the dataset must comply with building rules.
-They affects the structure of the dataset (not the value)
-They can apply to any concepts ( OPER, PROC, JDC, SIMP or BLOC)
+Sometimes the user wants his data to comply with certain construction rules.
+These rules affect the structure of the user data set (not the value).
+They can be applied to any entity (OPER, PROC, JDC, BLOC or MYCONCEPT).
Syntax
______
AU_MOINS_UN
-----------
-AU_MOINS_UN rule forces to create at least one concept in the list. More than one can be created.
+AU_MOINS_UN rule forces to create at least one eficas_keyword in the list. More than one can be created.
::
Structure = FACT ( statut ='f',
If Structure is defined, one of the keyword 'Beam', 'Bar', 'Grid' is also defined.
* If none of these keywords is present, Structure is unvalid.
- * If only Beam is present, Strucure is valid.
+ * If only Beam is present, Structure is valid.
* If both Beam and Bar are present, Structure is valid.
UN_PARMI
--------
-UN_PARMI rule obliges the user to create one and only one concept of the list.
+UN_PARMI rule obliges the user to create one and only one eficas_keyword of the list.
::
FOR_DPD = BLOC(condition = "code=='DPD'",
EXCLUS
------
-EXCLUS means that, if one of the keyword is created, the others won't be allowed.
+EXCLUS means that, if one of the eficas_keyword is created, the others won't be allowed.
::
JOB_DURATION = FACT(statut='o',
ENSEMBLE
--------
-The rule means that if one keyword is selected, the others have to be also.
+The rule means that if one eficas_keyword is selected, the others have to be also.
The keywords order is not meaningful.
::
PRESENT_PRESENT
---------------
-The rule means that if the FIRST keyword is selected, the others have to be also.
+The rule means that if the FIRST eficas_keyword is selected, the others have to be also.
The keywords order is meaningful.
::
PRESENT_ABSENT
--------------
-The rule means that if the FIRST keyword is selected, the others aren't allowed.
+The rule means that if the FIRST eficas_keyword is selected, the others aren't allowed.
The keywords order is meaningful.
::
