diff --git a/doc/manual/manual-gettingstarted.tex b/doc/manual/manual-gettingstarted.tex index 7532aad43..0cb6e8f69 100644 --- a/doc/manual/manual-gettingstarted.tex +++ b/doc/manual/manual-gettingstarted.tex @@ -1,198 +1,198 @@ \chapter{Getting started} \section{Downloading the code} The \akantu source code can be requested using the form accessible at the URL \url{http://lsms.epfl.ch/akantu}. There, you will be asked to accept the LGPL license terms. \section{Compiling Akantu} Akantu is a \code{cmake} project, so to configure it you can either follow the usual way: \begin{command} > cd akantu > mkdir build > cd build > ccmake [ Set the options that you need ] > make > make install \end{command} Or, you can use a tool we added to help you. You can just use the given \code{Makefile} that handles the \code{cmake} configuration \begin{command} > cd akantu > make config > make > make install \end{command} \section{Writing a \code{main} function\label{sect:common:main}} First of all, \akantu needs to be initialized. There is a memory management included in the core library which allows a correct allocation and de-allocation of vectors, structures and/or objects. Moreover, in parallel computations the initialization procedure can perform the communication setup. This is achieved by a pair of functions (\code{initialize} and \code{finalize}) that are used as follows: \begin{cpp} int main(int argc, char *argv[]) { akantu::initialize(argc, argv); // your code ... akantu::finalize(); } \end{cpp} The \code{initialize} function takes the program parameters which can be interpreted by \akantu in due form. \section{Creating and loading a mesh\label{sect:common:mesh}} \akantu supports meshes generated with Gmsh~\cite{gmsh}, a free software available at \url{http://geuz.org/gmsh/} where a detailed documentation can be found. Consequently, this manual will not provide Gmsh usage directions. Gmsh outputs meshes in \code{.msh} format that can be read by \akantu. In order to import a mesh, it is necessary to create a \code{Mesh} object through the following function calls: \begin{cpp} UInt spatial_dimension = 2; Mesh mesh(spatial_dimension); \end{cpp} The only parameter that has to be specified by the user is the spatial dimension of the problem. Now it is possible to read a \code{.msh} file with a \code{MeshIOMSH} object that takes care of loading a mesh to memory. This step is carried out by: \begin{cpp} MeshIOMSH mesh_io; mesh_io.read("square.msh", mesh); \end{cpp} where the \code{MeshIOMSH} object is first created before being used to read the \code{.msh} file. The mesh file name as well as the \code{Mesh} object must be specified by the user. The \code{MeshIOMSH} object can also write mesh files. This feature is useful to save a mesh that has been modified during a simulation. The \code{write} method takes care of it: \begin{cpp} mesh_io.write("square_modified.msh", mesh); \end{cpp} which works exactly like the \code{read} method. \akantu supports also meshes generated by DIANA (\url{http://tnodiana.com}), but only in reading mode. A similar procedure applies where the only difference is that the \code{MeshIODiana} object should be used instead of the \code{MeshIOMSH} one. Additional mesh readers can be introduced into \akantu by coding new \code{MeshIO} classes. \section{Using \code{Arrays}} Data in \akantu can be stored in data containers implemented by the \code{Array} class. In its most basic usage the \code{Array} class implemented in \akantu is similar to the \code{vector} class of the Standard Template Library (STL) for C++. A simple \code{Array} containing a sequence of \code{nb\_element} values can be generated with: \begin{cpp} Array example_array(nb_element); \end{cpp} where \code{type} usually is \code{Real}, \code{UInt} or \code{bool}. Each value is associated to an index, so that data can be accessed by typing: \begin{cpp} type & val = example_array(index) \end{cpp} -\code{Arrays} can also contain a sequence of values for each -index. In that case the number of components of each sequence must be -specified at the \code{Array} creation. For example if we want to -create a \code{Array} to store the coordinates (sequences of three +\code{Arrays} can also contain tuples of values for each +index. In that case the number of components per tuple must be +specified at the \code{Array} creation. For example, if we want to +create an \code{Array} to store the coordinates (sequences of three values) of ten nodes, the appropriate code is the following: \begin{cpp} UInt nb_nodes = 10; UInt spatial_dimension = 3; Array position(nb_nodes, spatial_dimension); \end{cpp} -In this case the $x$ position of node number 8 will be given by +In this case the $x$ position of the eighth node number will be given by \code{position(7, 0)} (in C++, numbering starts at 0 and not 1). If the number of components for the sequences is not specified, the default value of 1 is used. It is very common in \akantu to loop over arrays to perform a specific treatment. This ranges from geometric calculation on nodal quantities to tensor algebra (in constitutive laws for example). The \code{Array} object has the possibility to request iterators in order to make the writing of loops easier and enhance readability. For instance, a loop over the nodal coordinates can be performed like: \begin{cpp} //accessing the nodal coordinates Array Array nodes = mesh.getNodes(); //creating the iterators - Array::iterator it = nodes.begin(spatial_dimension); - Array::iterator end = nodes.end(spatial_dimension); + Array::vector_iterator it = nodes.begin(spatial_dimension); + Array::vector_iterator end = nodes.end(spatial_dimension); for (; it != end; ++it){ - RVector & coords = (*it); + Vector & coords = (*it); //do what you need .... } \end{cpp} -In that example, each \code{RVector} is a geometrical array of size \code{spatial\_dimension} +In that example, each \code{Vector} is a geometrical array of size \code{spatial\_dimension} and the iteration is conveniently performed by the \code{Array} iterator. The \code{Array} object is intensively used to store tensor values. In that case it should be specified that the returned object type is a matrix when constructing the iterator. This is done when calling the \code{begin} function. For instance, assuming that we have a \code{Array} storing stresses, we can loop over the stored tensors by: \begin{cpp} //creating the iterators - Array::iterator it = stresses.begin(spatial_dimension,spatial_dimension); - Array::iterator end = stresses.end(spatial_dimension,spatial_dimension); + Array::iterator > it = stresses.begin(spatial_dimension,spatial_dimension); + Array::iterator > end = stresses.end(spatial_dimension,spatial_dimension); for (; it != end; ++it){ Matrix & stress = (*it); //do what you need .... } \end{cpp} In that last example the Matrix objects are \code{spatial\_dimension} $\times$ \code{spatial\_dimension} matrices. -The light objects \code{Matrix} and \code{RVector} can be used and combined +The light objects \code{Matrix} and \code{Vector} can be used and combined to do most common linear algebra. In general, a mesh consists of several kinds of elements. Consequently the amount of data to be stored can differ for each element type. The straightforward example is the connectivity array, namely the sequences of nodes belonging to each element. In order to easily manage this kind of data, a -particular data structure called \code{ByElementTypeArray} is available. +particular data structure called \code{ElementTypeMapArray} is available. It is just a group of \code{Arrays}, each associated to an element -type. The following code can retrieve the \code{ByElementTypeArray} +type. The following code can retrieve the \code{ElementTypeMapArray} which stores the connectivity arrays for a mesh: \begin{cpp} - ByElementTypeArray & connectivities = mesh.getConnectivities(); + ElementTypeMapArray & connectivities = mesh.getConnectivities(); \end{cpp} Then the specific array associated to a given element type can be obtained by \begin{cpp} Array & connectivity_triangle = connectivities[_triangle_3]; \end{cpp} where the first order 3-node triangular element was used in the presented piece of code. %%% Local Variables: %%% mode: latex %%% TeX-master: "manual" %%% End: