diff --git a/Documentation/Impl_FMI.tex b/Documentation/Impl_FMI.tex new file mode 100644 index 0000000..c7a01f7 --- /dev/null +++ b/Documentation/Impl_FMI.tex @@ -0,0 +1,72 @@ +\chapter{Functional Mock-up Interface TLM Plugin} +Functional Mock-up Interface (FMI) is a tool-independent standard for connecting simulation tools \cite{blochwitz2009}. +One tool can export a model as a Functional Mockup Unit (FMU), a ZIP package with the file extension FMU. +This file is in turn loaded by the master simulation tool, which can connect and simulate the model. +An FMU file contains a model description XML file called \texttt{modelDescription.xml}, binaries for different platforms and other optional content. +It is important that the FMU contains a binary file for the platform where the master simulation tool is executed. + +There are two versions of the FMI standard: FMI for Co-Simulation and FMI for Model Exchange. +The main difference is that FMUs for Co-Simulation contain their own built-in solvers, and only exchange data at predefined communication points. +FMUs for Model Exchange require a solver in the master simulation tool. + +The TLM framework is able to simulate aggregated systems of connected sub-models using asynchronous TLM communication. +Input, output and bidirectional interfaces are supported. +Bidirectional interfaces can be either 1D or 3D. +It is also possible to specifiy physical domains such as mechanical, rotational or hydraulic. +Including FMUs in the TLM framework requires a wrapper. +\texttt{FMIWrapper} is a generic wrapper for connecting functional mockup units (FMUs) to the TLM framework. +It uses the FMI Library from Modelon \cite{modelon2015} to load an FMU, and the TLMPlugin for socket communication with the framework, see figure \ref{fig:overview}. + +\begin{figure}[ht] +\begin{tikzpicture} +\def\dx{0.0495*\textwidth} + +\node[rectangle,draw,thick, + minimum width=5*\dx, + minimum height=5*\dx, + text depth=5*\dx-20pt] () {FMIWrapper}; + +\node[rectangle, draw, thick, + minimum width=3*\dx, + minimum height=3*\dx, + xshift=2.5*\dx, + fill=white] (tp1) {TLMPlugin}; + +\node[rectangle, draw, thick, + minimum width=3*\dx, + minimum height=3*\dx, + xshift=-2.5*\dx, + fill=white] (fl) {FMILibrary}; + +\node[rectangle, draw, thick, + minimum width=3*\dx, + minimum height=3*\dx, + xshift=-7.5*\dx] (fmu) {xmodel.fmu}; + +\node[rectangle, draw, thick, + minimum width=3.5*\dx, + minimum height=5*\dx, + text depth=5*\dx-20pt, + xshift=9.25*\dx, + fill=white] () {TLMManager}; + +\node[rectangle, draw, thick, + minimum width=3*\dx, + minimum height=3*\dx, + xshift=7.5*\dx, + fill=white] (tp2) {TLMPlugin}; + +\draw[thick,->,very thick] (fmu) edge[bend left] (fl); +\draw[thick,<-,very thick] (fmu) edge[bend right] (fl); +\draw[thick,->,very thick] (fl) edge[bend left] (tp1); +\draw[thick,<-,very thick] (fl) edge[bend right] (tp1); +\draw[thick,->,very thick] (tp1) edge[bend left] (tp2); +\draw[thick,<-,very thick] (tp1) edge[bend right] (tp2); +\end{tikzpicture} +\caption{FMIWrapper uses FMILibrary to import FMUs, and TLMPlugin for socket communication.} +\label{fig:overview} +\end{figure} + +Both FMI for co-simulation and FMI for model exchange are supported. +Model exchange requires a solver in the wrapper executable. +For this reason, the CVODE and IDA solvers from the Sundials package are included. diff --git a/Documentation/MM_FMI.tex b/Documentation/MM_FMI.tex new file mode 100644 index 0000000..f892177 --- /dev/null +++ b/Documentation/MM_FMI.tex @@ -0,0 +1,329 @@ +\chapter{Importing Functional Mock-up Units} +\label{MMFMI} + +\section{Setting up a simulation} +\label{sec:setting_up} +The FMI wrapper is started by the StartTLMFMIWrapper startup script. +This script generates the \texttt{tlm.config} file and calls the FMIWrapper executable. +The executable takes the following arguments:\\ + +\noindent \verb|FMIWrapper |\\ + +Example:\\ + +\noindent \verb|FMIWrapper C:\temp\folder mymodel.fmu solver=CVODE -d|\\ + +The last to arguments are optional. +Available solvers are \texttt{Euler}, \texttt{RungeKutta}, \texttt{CVODE} and \texttt{IDA}. +Section \ref{sec:fmi_me} contains more details about the different solvers. +These can currently only be changed by modifying the startup script, i.e. not from the graphical interface. + +An FMU keep track of its variables by integer numbers called \texttt{value references}. +However, it does not provide any information about the mapping between its variables and the TLM interface. +Hence, this information must be provided by the user. +A configuration file called \texttt{fmi.config} is used for this purpose, see listing \ref{lst:fmiconfig}. + +\lstdefinelanguage{fmiconfig} +{ + % list of keywords + keywords={ + substeps, + name + }, + keywords=[2]{ + position, + orientation, + speed, + ang_speed, + force + }, + keywordstyle=\ttfamily\bfseries\textcolor{blue}, + keywordstyle=[2]\ttfamily\bfseries + % sensitive=false, % keywords are not case-sensitive + % morecomment=[l]{//}, % l is for line comment + % morecomment=[s]{/*}{*/}, % s is for start and end delimiter + % morestring=[b]" % defines that strings are enclosed in double quotes +} + +\begin{lstlisting}[language=fmiconfig,basicstyle=\ttfamily,floatplacement=ht,caption=A configuration file maps value references to TLM variables,label=lst:fmiconfig] +substeps,10 + +name,tlm1 +dimensions,6 +causality,Bidirectional +domain,Mechanical +position,6,7,8 +orientation,136,139,142,137,140,143,138,141,144 +speed,9,10,11 +ang_speed,145,146,147 +force,133,134,135,167,168,169 + +name,tlm2 +dimensions,1 +causality,Bidirectional +domain,Mechanical +position,12 +speed,15 +force,136 + +name,input1 +dimensions,1 +causality,Input +domain,Signal +value,16 + +name,output1 +dimensions,1 +causality,Output +domain,Signal +value,17 +\end{lstlisting} +\newpage +As can be seen, data is stored in a comma-separated format. +The first line specifies the number of substeps used for FMI for Co-Simulation (see section \ref{sec:fmi_cs}). +After this comes the port information. +Each port is specified by name, dimensions, causality and domain, followed by a list of variables depending on the port type. +The numbers after each variable are the value references. +These can be obtained by analyzing the \texttt{modelDescription.xml} file. +Listing \ref{lst:modeldescription} shows an example. +The variable first torque component has the value reference 167. +Hence, this number should be inserted as number four on the "force" line in \texttt{fmi.config}. + +\begin{lstlisting}[language=XML,float,floatplacement=ht,caption=Value references for variables are obtained from \texttt{modelDescription.xml},label=lst:modeldescription] + + + +\end{lstlisting} + + +\clearpage +\section{FMI for Co-Simulation} +\label{sec:fmi_cs} +With FMI for Co-Simulation the solver is embedded within the FMU. +Variables can only be exchanged at predefined communication points. +Hence, it is not possible for the solver to obtain interpolated force variables during internal iteration steps. +Keeping the force constant during the entire communication interval may, however, have a negative effect on numerical stability. +For this reason it is possible to divide each communication interval into a fixed number of \textit{sub steps}, as defined in the \texttt{fmi.config}. +In this way the forces can at least be updated in the FMU at more fine-grained intervals. +Pseudo-code for the simulation loop in the wrapper is shown in listing \ref{lst:wrapper_cs}. +The real code also contains error handling, but it has been excluded here to enhance readability. + +\lstset{emph={fmu},emphstyle={\color{red}\bfseries}, + emph={[2]TLMPlugin},emphstyle={[2]\color{blue}\bfseries} +} +\begin{lstlisting}[language=c++, basicstyle=\ttfamily\small,floatplacement=htb,caption=Pseudo code for the simulation loop with FMI for co-simulation,label=lst:wrapper_cs] +while (tcur < tend) { + double hsub = hmax/nSubSteps; + for(size_t i=0; i + + + + + + + + + + + + + + + +\end{lstlisting} + +\begin{figure}[ht] +\centering +\includegraphics[width=0.75\textwidth]{figs/metamodel.png} +\caption{Graphical view of the complete meta model} +\label{fig:metamodel_omedit} +\end{figure} \ No newline at end of file diff --git a/Documentation/TLMPlugin.pdf b/Documentation/TLMPlugin.pdf index f32ec90..c6ddd38 100644 Binary files a/Documentation/TLMPlugin.pdf and b/Documentation/TLMPlugin.pdf differ diff --git a/Documentation/TLMPlugin.tex b/Documentation/TLMPlugin.tex index 75019db..5bca9ee 100644 --- a/Documentation/TLMPlugin.tex +++ b/Documentation/TLMPlugin.tex @@ -20,11 +20,13 @@ \usepackage{afterpage} % Clear floats after each page \usepackage{datetime} \usepackage{tikz} +\usepackage{listings} \usepackage{eepic} \usepackage{epic} \usepackage{rotating} +\input{listings-modelica.cfg} \titleformat{\chapter}[display]{\normalfont\Large\bfseries\color[rgb]{0,0.4,0.796078431372549}}{\normalfont\huge\bfseries\chaptername \space \thechapter}{16pt}{\Huge} \titleformat{\part}[display]{\centering\normalfont\Large\bfseries\color[rgb]{0,0.4,0.796078431372549}}{\centering\normalfont\huge\bfseries\partname~\thepart}{16pt}{\Huge} @@ -142,12 +144,14 @@ \input{Impl_Adams} \input{Impl_BEAST} \input{Impl_Modelica} +\input{Impl_FMI} %\chapter{Modelling} \input{MM_Adams} \input{MM_Simulink} \input{MM_Beast} \input{MM_Modelica} +\input{MM_FMI} %\input{RunningMMCoSim} diff --git a/Documentation/TLM_background.tex b/Documentation/TLM_background.tex index 5f925ed..e0d8c54 100644 --- a/Documentation/TLM_background.tex +++ b/Documentation/TLM_background.tex @@ -9,9 +9,9 @@ \chapter{TLM background theory} \begin{figure} \begin{center} {\includegraphics[width=9cm]{figs/TLMline.png}} -\caption{Delay line with the passing wave variables $c_1$ and $c_2$ -and velocity variables $v_1$ and $v_2$.} \end{center} +\caption{Delay line with the passing wave variables $c_1$ and $c_2$ + and velocity variables $v_1$ and $v_2$.} \label{figTLMline} \end{figure} @@ -53,8 +53,8 @@ \chapter{TLM background theory} \begin{figure} \begin{center} {\includegraphics[width=9cm]{figs/RotStiff.png}} -\caption{Estimating the rotational stiffness.} \end{center} +\caption{Estimating the rotational stiffness.} \label{figRotStiff} \end{figure} diff --git a/Documentation/bibliography.tex b/Documentation/bibliography.tex index 83fa6ab..e2d6fec 100644 --- a/Documentation/bibliography.tex +++ b/Documentation/bibliography.tex @@ -171,4 +171,18 @@ {\em An Open-Source Graphical Composite Modeling Editor and Simulation Tool Based on {FM}I and {TLM} Co-Simulation}, Proceedings of the 11th International Modelica Conference, Versailles, France, September 2015 +\bibitem{hindmarsh2005} Hindmarsh, A.~C. and Brown, P.~N. and Grant, K.~E. and Lee, S.~L. and Serban, R. and Shumaker, D.~E. and Woodward, C.~S. + {\em {SUNDIALS}: Suite of nonlinear and differential/algebraic equation solvers}, + ACM Transactions on Mathematical Software (TOMS), 2005 + +\bibitem{blochwitz2009} Blochwitz, T. and Otter M. and Arnold M. and Bausch C. and Clau{\ss} C. and Elmqvist H. and Junghanns A. and Mauss J. and Monteiro M. and Neidhold T. and Neumerkel D. and Olsson H. and Peetz J.~V. and Wolf S. + {\em The {Functional Mockup Interface} for Tool independent Exchange of Simulation Models}, + 8th International Modelica Conference 2011, Como, Italy, September 2009 + +\bibitem{modelon2015} Modelon AB, +{\em FMI Library: part of JModelica.org}, +http://www.jmodelica.org/FMILibrary, +Last visited on 10 October 2016 + + \end{thebibliography} diff --git a/Documentation/figs/metamodel.png b/Documentation/figs/metamodel.png new file mode 100644 index 0000000..80420f1 Binary files /dev/null and b/Documentation/figs/metamodel.png differ diff --git a/Documentation/figs/model_dymola.png b/Documentation/figs/model_dymola.png new file mode 100755 index 0000000..314c7d7 Binary files /dev/null and b/Documentation/figs/model_dymola.png differ diff --git a/Documentation/figs/model_omedit.png b/Documentation/figs/model_omedit.png new file mode 100755 index 0000000..988892d Binary files /dev/null and b/Documentation/figs/model_omedit.png differ diff --git a/Documentation/listings-modelica.cfg b/Documentation/listings-modelica.cfg new file mode 100644 index 0000000..26530db --- /dev/null +++ b/Documentation/listings-modelica.cfg @@ -0,0 +1,69 @@ +%% listings-modelica.cfg +%% Copyright 2014 Martin Sjoelund, Dietmar Winkler +% +% This work may be distributed and/or modified under the +% conditions of the LaTeX Project Public License, either version 1.3 +% of this license or (at your option) any later version. +% The latest version of this license is in +% http://www.latex-project.org/lppl.txt +% and version 1.3 or later is part of all distributions of LaTeX +% version 2005/12/01 or later. +% +% This work has the LPPL maintenance status `maintained'. +% +% The Current Maintainer of this work is Dietmar Winkler +% +% Code repository https://github.com/modelica-tools/listings-modelica +% +% This work consists of the file listings-modelica.cfg + +\lstdefinelanguage{modelica} +{ + morekeywords=[1]{ + algorithm,and,annotation,as,assert,block,break,case,class,connect,connector, + constant,constrainedby,der,discrete,each,else,elseif,elsewhen,encapsulated, + end,enumeration,equality,equation,expandable,extends,external,failure,final, + flow,for,function,guard,if,import,in,initial,inner,input,List,local,loop, + match,matchcontinue,model,not,operator,Option,or,outer,output,package,parameter, + partial,protected,public,record,redeclare,replaceable,return,stream, + subtypeof,then,Tuple,type,uniontype,when,while}, + morekeywords=[2]{true, false}, + % Do not make true,false keywords because fn(true,x, false ) shows up as fn(true,x, *false*) + sensitive=true, + comment=[l]//, + morecomment=[s]{/*}{*/}, + alsodigit={.,-}, + morestring=[b]', + morestring=[b]", +}[keywords,comments,strings] + +\definecolor{keywordcolor1}{rgb}{0,0,.4} +\definecolor{keywordcolor2}{rgb}{.90,0,0} +\definecolor{stringcolor}{rgb}{0.133,0.545,0.133} +% \definecolor{listingbgcolor}{rgb}{0.95,0.95,0.95} + +\lstset{ + breaklines=true, + language=modelica, + basicstyle=\ttfamily, + keywordstyle=[1]\color{keywordcolor1}\bfseries, + keywordstyle=[2]\color{keywordcolor2}, + stringstyle=\color{stringcolor}, +% backgroundcolor=\color{listingbgcolor}, + framexleftmargin=5pt, + xleftmargin=5pt, + xrightmargin=5pt, + showstringspaces=false, +} + +\lstset{breaklines=true,label=} +% \lstset{basicstyle=\ttfamily} + +\newcommand{\code}[1]{\texttt{\hyphenchar% +\font45% +\sloppy% +\fontdimen2\font=0.4em% +\fontdimen3\font=0.2em% +\fontdimen4\font=0.1em% +\fontdimen7\font=0.1em% + #1}}