Imported wiki documentation

doc/builders.rst

@@ -0,0 +1,47 @@
+Builders
+========
+
+Builders are not components by itself, but build a subtree using
+available components.
+
+LayeredModel
+------------
+
+Defines parameters at nodes, which are interpolated inbetween nodes.
+
+.. code-block:: YAML
+
+    !LayeredModel
+    map: <map> # Mapping to 1D (root component)
+    interpolation: (lower|upper|linear) 
+    parameters: [<dimension>, <dimension>, ...] # order of dimension
+    nodes:
+      <double>: [<double>, <double>, ...] # key: node position, value: dimension values
+      <double>: [<double>, <double>, ...]
+      ...
+
+:Domain:
+  *inherited*, must be 1D
+:Codomain:
+  length of coefficients sequence
+:Interpolation methods:
+  :lower:
+    Take the value of the lower (smaller) node
+  :upper:
+    Take the value of the upper (larger) node
+  :linear:
+    Linear interpolation
+:Example:
+  `3_layered_linear <https://github.com/SeisSol/easi/blob/master/examples/3_layered_linear.yaml>`_
+
+Include
+-------
+
+Includes another configuration file.
+
+.. code-block:: YAML
+
+    !Include <filename>
+
+:Example:
+  `f_120_sumatra <https://github.com/SeisSol/easi/blob/master/examples/f_120_sumatra.yaml#L24>`_

doc/components.rst

@@ -0,0 +1,39 @@
+Components
+==========
+
+In the following is a list of all components currently available in
+easi.
+
+Every component has a domain m and a codomain n which can be thought
+of as a function :math:`f:\mathbb{R}^m \rightarrow \mathbb{R}^n`.
+That is, a component accepts vectors in :math:`\mathbb{R}^m` and
+passes vectors in :math:`\mathbb{R}^n` to its child components
+(or as a result).
+The dimensions are labeled and a childs input dimensions must match
+its parent's output dimensions.
+
+Composite components
+--------------------
+
+Each composite may have a sequence of child components. Composite itself
+is abstract and may not be instantiated.
+Maps and Filters are always composite, builders are not.
+
+.. code-block:: YAML
+
+    !ABSTRACT
+    components:
+      - <Component>
+      - <Component>
+      - ...
+
+`example <https://github.com/SeisSol/easi/blob/master/examples/1_groups.yaml>`_
+
+Alternative for composites with a single child:
+
+.. code-block:: YAML
+
+    !ABSTRACT
+    components: <Component>
+
+Remark: Composites must of at least one child component.

doc/filters.rst

@@ -0,0 +1,100 @@
+Filters
+=======
+
+Filters accept only a subsets of points and allows for the spatial
+partitioning of models.
+
+Any
+---
+
+Any mostly serves as a root node and accepts every point and every
+group.
+
+.. code-block:: YAML
+
+    !Any
+
+:Domain:
+  *inherited*
+:Codomain:
+  *domain*
+:Example:
+  `1_groups <https://github.com/SeisSol/easi/blob/3f5783097808c486962fe8fa253f7738db3cfacb/examples/1_groups.yaml#L1>`_
+
+AxisAlignedCuboidalDomainFilter
+-------------------------------
+
+Accepts only points inside an axis-aligned bounding box, i.e. when
+:math:`l_x \leq x \leq u_x` and :math:`l_y \leq y \leq u_y` and ...
+
+.. code-block:: YAML
+
+    !AxisAlignedCuboidalDomainFilter
+    limits:
+      <dimension>: [<double>, <double>] # [l_x, u_x]
+      <dimension>: [<double>, <double>] # [l_y, u_y]
+      ...
+
+:Domain:
+  *codomain*
+:Codomain:
+  keys of limits
+:Example:
+  `f_103_scec <https://github.com/SeisSol/easi/blob/master/examples/f_103_scec.yaml#L28>`_
+
+SphericalDomainFilter
+---------------------
+
+Accepts only points inside a sphere, i.e. when :math:`\lVert x-c\rVert \leq r`.
+
+.. code-block:: YAML
+
+    !SphericalDomainFilter
+    radius: <double>
+    centre:
+      <dimension>: <double>
+      <dimension>: <double>
+      ...
+
+:Domain:
+  *codomain*
+:Codomain:
+  keys of centre
+
+GroupFilter
+-----------
+
+Accepts only points belonging to a set of groups.
+
+.. code-block:: YAML
+
+    !GroupFilter
+    groups: [<int>,<int>,...]
+
+:Domain:
+  *inherited*
+:Codomain:
+  *domain*
+:Example:
+  `120_sumatra <https://github.com/SeisSol/easi/blob/master/examples/120_sumatra.yaml#L7>`__
+
+Switch
+------
+
+Can be used to use select a component based on the requested parameters.
+
+.. code-block:: YAML
+
+    !Switch
+    [<parameter>,<parameter>,...]: <component>
+    [<parameter>,<parameter>,...]: <component>
+    ...
+
+:Domain:
+  *inherited*
+:Codomain:
+  *domain*
+:Example:
+  `120_sumatra <https://github.com/SeisSol/easi/blob/master/examples/120_sumatra.yaml#L1>`__:
+  [mu\_d, mu\_s, d\_c] are defined with a !ConstantMap
+  and [cohesion, forced\_rupture\_time] are defined with a !FunctionMap.

doc/getting_started.rst

@@ -1,3 +1,162 @@
+Getting Started with easi
 =========================
-Getting started with easi
-=========================
+
+easi is a header-only library written in C++11.
+Hence, one simply needs 
+(Only unit tests must be compiled with CMake.)
+
+Dependencies
+------------
+
+Easi depends on the following two projects:
+
+-  `ImpalaJIT <https://github.com/Manuel1605/ImpalaJIT>`__
+-  `yaml-cpp <https://github.com/jbeder/yaml-cpp>`__
+
+Make sure to link against these libraries when using easi.
+
+Usage example
+-------------
+
+easi is configured via `YAML <http://yaml.org>`__ configuration files.
+For example, such a configuration file could look like the following:
+
+.. code-block:: yaml
+
+    !Any
+    components:
+      - !AxisAlignedCuboidalDomainFilter
+        limits:
+          x: [-100000, 100000]
+          y: [-5000, 5000]
+          z: [-100000, 10000]
+        components:
+          - !ConstantMap
+            map:
+              lambda: 1e10
+              mu: 2e10
+              rho: 5000
+      - !LayeredModel
+        map: !AffineMap
+          matrix:
+            z: [0, 0, 1]
+          translation:
+            z: 0
+        interpolation: linear
+        parameters: [rho, mu, lambda]
+        nodes:
+          -100.0:   [2300.0, 0.1766e10, 0.4999e10]
+          -300.0:   [2300.0, 0.6936e10, 1.3872e10]
+          -1000.0:  [2600.0, 1.3717e10, 1.8962e10]
+          -3000.0:  [2700.0, 2.1168e10, 2.7891e10]
+          -6000.0:  [2870.0, 3.1041e10, 3.8591e10]
+          -31000.0: [3500.0, 3.9847e10, 4.3525e10]
+          -50000.0: [3200.0, 6.4800e10, 6.5088e10] 
+
+Here, all points with y-coordinate inbetween -5 km and +5 km would be
+assigned constant model parameters. For all other points, a linear
+interpolation, depending on the z-coordinate is used.
+
+Application example
+-------------------
+
+The first step is always to create a model.
+Here, we may use the YAMLParser class which creates models from YAML configuration files.
+
+.. code-block:: cpp
+  :linenos:
+
+  easi::YAMLParser parser(3);
+  easi::Component* model = parser.parse("test.yaml");  
+
+The argument in YAMLParser's constructor is the dimension of the input vectors.
+Here, we take 3 as we want to query our model in a 3-dimensional space.
+
+As a next step, we need to define a query, which defines the input vectors
+for which we want to evaluate our model.
+In the following example we add the points (1,2,3) and (2,3,4).
+Each point may have an additional group parameter, which may be used
+to distinguish points in an easi file.
+
+.. code-block:: cpp
+
+  easi::Query query(2,3);
+  query.x(0,0) = 1.0;
+  query.x(0,1) = 2.0;
+  query.x(0,2) = 3.0;
+  query.group(0) = 1;
+  query.x(1,0) = 2.0;
+  query.x(1,1) = 3.0;
+  query.x(1,2) = -4.0;
+  query.group(1) = 1;
+
+We need to store the output vectors somewhere.
+For this purpose, we always need to supply an adapter, which connects
+the output vector with locations in memory.
+In our sample application, the output vector shall be stored as array of
+structs, and hence we use an ArrayOfStructsAdapter.
+(Note that additional adapters can be implemented by overriding the class ResultAdapter.)
+
+.. code-block:: cpp
+  
+  struct ElasticMaterial {
+    double lambda, mu, rho;
+  };
+
+  ElasticMaterial material[2];
+  easi::ArrayOfStructsAdapter<ElasticMaterial> adapter(material);
+  adapter.addBindingPoint("lambda", &ElasticMaterial::lambda);
+  adapter.addBindingPoint("mu",     &ElasticMaterial::mu);
+  adapter.addBindingPoint("rho",    &ElasticMaterial::rho);
+
+Finally, a simple call to evaluate is sufficient, and the model should be
+deleted if is not required anymore.
+
+.. code-block:: cpp
+
+    model->evaluate(query, adapter);
+    delete model;
+
+The whole sample code is listed in the following:
+
+.. code-block:: cpp
+
+  #include <iostream>
+  #include "easi/YAMLParser.h"
+  #include "easi/ResultAdapter.h"
+
+  struct ElasticMaterial {
+    double lambda, mu, rho;
+  };
+
+  int main(int argc, char** argv)
+  {
+    easi::Query query(2,3);
+    query.x(0,0) = 1.0;
+    query.x(0,1) = 2.0;
+    query.x(0,2) = 3.0;
+    query.group(0) = 1;
+    query.x(1,0) = 2.0;
+    query.x(1,1) = 3.0;
+    query.x(1,2) = -4.0;
+    query.group(1) = 1;
+    
+    easi::YAMLParser parser(3);
+    easi::Component* model = parser.parse("test.yaml");  
+    
+    ElasticMaterial material[2];
+    easi::ArrayOfStructsAdapter<ElasticMaterial> adapter(material);
+    adapter.addBindingPoint("lambda", &ElasticMaterial::lambda);
+    adapter.addBindingPoint("mu",     &ElasticMaterial::mu);
+    adapter.addBindingPoint("rho",    &ElasticMaterial::rho);
+    
+    model->evaluate(query, adapter);
+    
+    delete model;
+    
+    for (unsigned j = 0; j < 2; ++j) {
+      std::cout << material[j].lambda << " " << material[j].mu << " " << material[j].rho << std::endl;
+    }  
+
+    return 0;
+  }

doc/glossary.rst

@@ -0,0 +1,21 @@
+Glossary
+========
+
+Domain and codomain
+  The set of all permitted inputs to a given function is called the domain
+  of the function, while the set of permissible outputs is called the
+  codomain.
+
+Map
+  A map transforms a m-dimensional input vector into an n-dimensional
+  output vector.
+
+Filter
+  A filter is a boolean function which either accepts or rejects input vectors.
+
+Composite components
+  A composite component is a component with attached components
+  (that is, a composite is the root of a tree).
+  Basically, it means that several components can be plugged to process
+  a chain of operations.
+  Maps and Filters are composite components, Builders are not.