Homec4science
Diffusion LibMultiScale (features/pybind) Browse

libmultiscale/doc/manual/chapters.tex
b05d5f2aba78features/pybind

Last Change
Raw File

chapters.tex
View Options

\chapter{Getting started}
\section{Getting \libmultiscale}
The \libmultiscale source code can be requested using the form accessible at the URL
\url{http://lsms.epfl.ch/libmultiscale}. There, you will be asked to accept the
CECILL-C license terms (\url{http://www.cecill.info/licences/Licence_CeCILL-C_V1-en.html})
\section{Compiling \libmultiscale}
\libmultiscale is a \code{cmake} project, so to configure it you can either follow the usual way:
\begin{command}
> cd libmultiscale
> mkdir build
> cd build
> ccmake <path to libmultiscale sources>
[ Set the options that you need ]
> make
> make install
\end{command}
\chapter{Configuration files}
\section{Parser syntax}
\subsection{Sections}
Configuration files are divided in sections which admit the syntax
\begin{lmconfig}
Section NAME UNITS
...
endSection
\end{lmconfig}
The user can place commands in the section with the simple structure
\begin{lmconfig}
Section NAME UNITS
...
KEYWORD arg1 arg2 ...
...
endSection
\end{lmconfig}
where units can be
\begin{itemize}
\item RealUnits: SI units \\ \\
length = meters \\
mass = kilograms \\
energy = Joule \\
time = seconds \\
temperature = Kelvins
\item AtomsUnits \\ \\
length = angstroms \\
mass = grams per mol \\
energy = kilo calory per mol \\
time = femto seconds \\
temperature = Kelvins
\item MetalUnits \\ \\
length = angstroms \\
mass = grams per mol \\
energy = eV \\
time = pico seconds \\
temperature = Kelvins
\end{itemize}
The unit system specify, for all values in the described section,
in what units are expressed the numerical values.
The parser allows multiline arguments or block reported arguments such as
the examples below
\begin{lmconfig}
Section NAME UNITS
...
KEYWORD arg1 \
arg2 \
arg3
...
KEYWORD arg1 BLOCK_PARAMS section2
endSection
#second section called by the BLOCK_PARAM
Section section2 UNITS
arg1 arg2
arg3
arg4
endSection
\end{lmconfig}
\subsection{Variables}
Variables can be defined using the LET command
\begin{lmconfig}
LET varname = cos(pi/2)
\end{lmconfig}
As you can see an algebraic parser is included and allows to
compute values within scripts and benefit from common unary functions.
all variable names can be recalled within arguments like
\begin{lmconfig}
Section NAME UNITS
...
LET varname = cos(pi/2)
KEYWORD varname
...
endSection
\end{lmconfig}
The user can also construct variable names with other variables using
the \verb&${}& dereferencing operator
\begin{lmconfig}
Section NAME UNITS
...
LET ANGLE = pi/2
LET cos\${ANGLE} = cos(ANGLE)
KEYWORD cos\${ANGLE} arg2 arg3
PRINT cos\${ANGLE}
...
endSection
\end{lmconfig}
Environment variables can also be defined and used using \verb&$()& operator
\begin{lmconfig}
Section NAME UNITS
...
LET ANGLE = \$(myangle)
LET cos\${ANGLE} = cos(ANGLE)
KEYWORD cos\${ANGLE} arg2 arg3
PRINT cos\${ANGLE}
...
endSection
In the example, \verb&myangle& must be defined in the environment context.
\end{lmconfig}
\subsection{Control blocks}
It is possible to use loops within the configuration files.
The iteration is done following the syntax
\begin{lmconfig}
FOR k in a b c
LET name = k
endFOR
\end{lmconfig}
or to explore a range of numerical values
\begin{lmconfig}
LET index = 0
FOR k in range start end increment
LET index = index + k
endFOR
\end{lmconfig}
\section{General keywords}
A \libmultiscale configuration file needs a \verb$MultiScale$ section. It is the entry
point for all configuration files.
\begin{lmconfig}
Section MultiScale Units
...
endSection
\end{lmconfig}
First of all, the \verb$MultiScale$ section should start by defining what
is the unit system used {\bf internally} by the code. It can differ
from the unit system of the section since the \libmultiscale parser
will handle the conversion for the user.
Secondly, the dimension of the space that is going to be simulated
needs to be given. For instance, these two things can be provided like
\begin{lmconfig}
Section MultiScale RealUnits
...
UNITCODE AtomsUnits
DIMENSION 3
...
endSection
\end{lmconfig}
Then you can construct some objects between three kinds
\begin{itemize}
\item MODELS: It is the storage of degrees of freedom and can be of nature:
\hyperref[section:md]{Molecular Dynamics},
\hyperref[section:continuum]{Continuum Mechanics-Finite Element} or
\hyperref[section:dd]{Dislocation dynamics}.
\item \hyperref[section:dumper]{DUMPER}: action that generate output files of various forms.
\item \hyperref[section:stimulator]{STIMULATOR}: action that alter a set of degrees of freedom, for instance to impose thermostats or initial conditions.
\item \hyperref[section:filter]{FILTER}: special container which select a subset of another container based on varisous criteria
\item \hyperref[section:filter]{COMPUTE}: special container which contains real value from dedicated
operations.
\item \hyperref[section:coupler]{COUPLER}: request creation of a coupler
\end{itemize}
In general these object are created following the syntax
\begin{lmconfig}
FAMILY nameID TYPE INPUT input KEY1 param1 KEY2
\end{lmconfig}
And a full description is provided in the lexicon presented in chapter \ref{chapter:lexicon}.
c4science · Help