51 |
52 |
53 |
54 |
55 |
56 |
137 |
138 |
139 | """
140 | for elem in root.findall('.//table'):
141 | with open("index.html", "w") as f:
142 | f.write(head)
143 | f.write(ET.tostring(elem).decode('utf-8'))
144 | f.write(tail)
145 | sys.exit(0)
146 | sys.exit(1)
147 |
--------------------------------------------------------------------------------
/.CI/latexml/Dockerfile:
--------------------------------------------------------------------------------
1 | FROM ubuntu:bionic
2 |
3 | ENV PATH="/usr/local/texlive/bin/x86_64-linux:${PATH}"
4 |
5 | RUN sed -i s,http://archive.ubuntu.com/ubuntu/,mirror://mirrors.ubuntu.com/mirrors.txt, /etc/apt/sources.list \
6 | && apt-get update \
7 | && export DEBIAN_FRONTEND=noninteractive \
8 | && apt-get install -qy perl ca-certificates make libxslt1.1 libxslt-dev libxml2 libxml2-dev gcc wget curl git unzip cpanminus cm-super --no-install-recommends --no-install-suggests \
9 | && export PATH="/tmp/texlive/bin/x86_64-linux:$PATH" \
10 | && REMOTE="http://mirror.ctan.org/systems/texlive/tlnet" \
11 | && INSTALL="/tmp/install-texlive" \
12 | && mkdir -p $INSTALL \
13 | && echo "export PATH=$PATH:/usr/local/texlive/2022/bin" >> /etc/environment \
14 | && curl -sSL $REMOTE/install-tl-unx.tar.gz | tar -xzv -C $INSTALL --strip-components=1 \
15 | && echo selected_scheme scheme-basic > texlive.profile \
16 | && echo TEXDIR /usr/local/texlive/ >> texlive.profile \
17 | && echo TEXMFLOCAL /usr/local/texmf-local >> texlive.profile \
18 | && echo TEXMFSYSCONFIG /usr/local/texmf-config >> texlive.profile \
19 | && echo TEXMFSYSVAR /usr/local/texmf-var >> texlive.profile \
20 | && echo tlpdbopt_autobackup 0 >> texlive.profile \
21 | && echo tlpdbopt_install_docfiles 0 >> texlive.profile \
22 | && echo tlpdbopt_install_srcfiles 0 >> texlive.profile \
23 | && $INSTALL/install-tl --profile texlive.profile \
24 | && rm texlive.profile \
25 | && tlmgr update --self --all --reinstall-forcibly-removed \
26 | && tlmgr install latexmk listings caption cleveref xcolor float multirow tocloft parskip etoolbox index biblatex biber newtxtt txfonts cmap \
27 | && cpanm JSON \
28 | && cpanm LaTeXML \
29 | && apt-get autoremove -qy make gcc wget git cpanminus libxml2-dev libxslt-dev \
30 | && latexmk --version \
31 | && apt-get clean && rm -rf /var/lib/apt/lists/* /tmp/* /var/tmp/ /root/.cpanm/work*
32 |
--------------------------------------------------------------------------------
/.CI/latexml/README.md:
--------------------------------------------------------------------------------
1 | # Updating the docker image
2 |
3 | The docker image is stored at the [docker hub](https://hub.docker.com/r/modelicaspec/latexml).
4 | If you need write access to the organization, contact @sjoelund.
5 |
6 | To update the image, update the Dockerfile .
7 | Then build and tag the image and upload it.
8 |
9 | ```sh
10 | docker build -t modelicaspec/latexml:`date +%Y%m%d` .
11 | docker push modelicaspec/latexml:`date +%Y%m%d`
12 | ```
13 |
14 | If the change is small you can base it on the old image instead of creating a new one from scratch.
15 | Modify Dockerfile.incremental to be based on the image you want to update.
16 | Make sure that the regular Dockerfile is also updated (so future builds incorporates these additions).
17 |
18 | ```sh
19 | docker build -t modelicaspec/latexml:`date +%Y%m%d` - < Dockerfile.incremental
20 | docker push modelicaspec/latexml:`date +%Y%m%d`
21 | ```
22 |
23 | Once the docker image is updated, modify `../Jenkinsfile` to use this image.
24 | Put all of this in the same commit and see if the CI build accepts it.
25 |
--------------------------------------------------------------------------------
/.CI/markdown/Dockerfile:
--------------------------------------------------------------------------------
1 | FROM alpine:3.9
2 |
3 | RUN apk add -U --no-cache py3-pip py3-lxml && pip3 install py-gfm
4 |
--------------------------------------------------------------------------------
/.gitignore:
--------------------------------------------------------------------------------
1 | ## emacs:
2 | auto/
3 | *~
4 |
5 | ## Core latex/pdflatex auxiliary files:
6 | *.aux
7 | *.lof
8 | *.log
9 | *.lot
10 | *.fls
11 | *.out
12 | *.toc
13 |
14 | ## Intermediate documents:
15 | *.dvi
16 | *-converted-to.*
17 | # these rules might exclude image files for figures etc.
18 | # *.ps
19 | # *.eps
20 | # *.pdf
21 |
22 | ## Bibliography auxiliary files (bibtex/biblatex/biber):
23 | *.bbl
24 | *.bcf
25 | *.blg
26 | *-blx.aux
27 | *-blx.bib
28 | *.brf
29 | *.run.xml
30 |
31 | ## Build tool auxiliary files:
32 | *.fdb_latexmk
33 | *.synctex
34 | *.synctex.gz
35 | *.synctex.gz(busy)
36 | *.pdfsync
37 |
38 | ## Auxiliary and intermediate files from other packages:
39 |
40 |
41 | # algorithms
42 | *.alg
43 | *.loa
44 |
45 | # achemso
46 | acs-*.bib
47 |
48 | # amsthm
49 | *.thm
50 |
51 | # beamer
52 | *.nav
53 | *.snm
54 | *.vrb
55 |
56 | #(e)ledmac/(e)ledpar
57 | *.end
58 | *.[1-9]
59 | *.[1-9][0-9]
60 | *.[1-9][0-9][0-9]
61 | *.[1-9]R
62 | *.[1-9][0-9]R
63 | *.[1-9][0-9][0-9]R
64 | *.eledsec[1-9]
65 | *.eledsec[1-9]R
66 | *.eledsec[1-9][0-9]
67 | *.eledsec[1-9][0-9]R
68 | *.eledsec[1-9][0-9][0-9]
69 | *.eledsec[1-9][0-9][0-9]R
70 |
71 | # glossaries
72 | *.acn
73 | *.acr
74 | *.glg
75 | *.glo
76 | *.gls
77 |
78 | # gnuplottex
79 | *-gnuplottex-*
80 |
81 | # hyperref
82 | *.brf
83 |
84 | # knitr
85 | *-concordance.tex
86 | *.tikz
87 | *-tikzDictionary
88 |
89 | # listings
90 | *.lol
91 |
92 | # makeidx
93 | *.idx
94 | *.ilg
95 | *.ind
96 | *.ist
97 |
98 | # minitoc
99 | *.maf
100 | *.mtc
101 | *.mtc[0-9]
102 | *.mtc[1-9][0-9]
103 |
104 | # minted
105 | _minted*
106 | *.pyg
107 |
108 | # morewrites
109 | *.mw
110 |
111 | # mylatexformat
112 | *.fmt
113 |
114 | # nomencl
115 | *.nlo
116 |
117 | # sagetex
118 | *.sagetex.sage
119 | *.sagetex.py
120 | *.sagetex.scmd
121 |
122 | # sympy
123 | *.sout
124 | *.sympy
125 | sympy-plots-for-*.tex/
126 |
127 | # TikZ & PGF
128 | *.dpth
129 | *.md5
130 | *.auxlock
131 |
132 | # todonotes
133 | *.tdo
134 |
135 | # xindy
136 | *.xdy
137 |
138 | # WinEdt
139 | *.bak
140 | *.sav
141 |
142 | *.html
143 |
144 | *.cache
145 |
146 | *.xml
147 |
148 | MLS\.pdf
149 |
150 | LaTeXML.css
151 | ltx-article.css
152 | ltx-listings.css
153 | ltx-report.css
154 | LaTeXML-maybeMathjax.js
155 |
156 | MLS.tar.gz
157 |
158 | # Directories belonging to the LaTeXML build
159 | /annotations/
160 | /connectors-and-connections/
161 | /interface-or-type-relationships/
162 | /modelica-dae-representation/
163 | /overloaded-operators/
164 | /packages/
165 | /preface/
166 | /state-machines/
167 | /stream-connectors/
168 | /synchronous-language-elements/
169 | /the-modelica-standard-library/
170 | /unit-expressions/
171 |
--------------------------------------------------------------------------------
/.scripts/patch-body-ios-hover.sh:
--------------------------------------------------------------------------------
1 | #!/bin/sh -xe
2 |
3 | sed -i.bak 's///' *.html
4 | rm *.html.bak # MacOS sed does not support -i without extension
5 |
--------------------------------------------------------------------------------
/.scripts/patch-viewport.sh:
--------------------------------------------------------------------------------
1 | #!/bin/sh -xe
2 |
3 | sed -i.bak 's;;\
4 | ;' *.html
5 | rm *.html.bak # MacOS sed does not support -i without extension
6 |
--------------------------------------------------------------------------------
/MLS.tex:
--------------------------------------------------------------------------------
1 | \documentclass[10pt,a4paper]{report}
2 | \NeedsTeXFormat{LaTeX2e}
3 | \usepackage{ifpdf}
4 | \ifpdf
5 | % While the cmap.sty README says that the package should be included "at the beginning of your preamble",
6 | % we need to at least load it after ifpdf due to incompatibility with LaTeXML, see:
7 | % - https://github.com/brucemiller/LaTeXML/issues/2035 (marked as fixed as of commit c02643a)
8 | \usepackage{cmap}
9 | \fi
10 | \usepackage[utf8]{inputenc}
11 |
12 | % Define title for use by LaTeXML.
13 | % An extended title is defined separately in the 'titlepage'.
14 | \newcommand{\mlsversion}{3.7-dev}
15 | \newcommand{\mlsdate}{\today}
16 | \title{Modelica\textsuperscript{\textregistered} Language Specification version~\mlsversion}
17 |
18 | \date{\mlsdate}
19 |
20 | \author{Modelica Association}
21 |
22 | \input{preamble.tex}
23 | \ifpdf
24 | \addbibresource{mls.bib}
25 | \fi
26 |
27 | % When debugging the LaTeXML build, it would be good to know the LaTeXML version used.
28 | % The need for this feature has been reported as:
29 | % - https://github.com/brucemiller/LaTeXML/issues/2033 -- fixed on 'master'
30 | % When the fix becomes available in the LaTeXML version we use, try enabling the following:
31 | %\usepackage{latexml}
32 | %\begin{lxFooter}
33 | %Produced by \LaTeXMLfullversion.
34 | %\end{lxFooter}
35 |
36 | \begin{document}
37 |
38 | % Setting pageanchor false for these unnumbered pages
39 | % Changed back after title page.
40 | % The downside is that you cannot go to them in acrobat
41 | % This is from https://tex.stackexchange.com/questions/18924/pdftex-warning-ext4-destination-with-the-same-identifier-nam-epage-1-has
42 | % The accepted solution did not seem to work
43 | \hypersetup{pageanchor=false,bookmarksdepth=2,destlabel=true,bookmarksopenlevel=0}
44 |
45 | \include{chapters/titlepage}
46 |
47 | % Add new Modelica Language logotype
48 | % The header ruler looks odd as Modelica Language define a natural line that is further up
49 | % We also need to fill the vertical space on the right
50 | % Not using page numbers in right-header, since we usually refer to sections.
51 | %
52 | % Using nouppercase since it is seems more normal for the sections, and is also
53 | % needed for over-determined connectors (as it would otherwise overflow)
54 | \cleardoublepage
55 | \setlength{\headheight}{10.5mm} % Make tall enough to fit fancy header.
56 | \pagestyle{fancy}
57 | \rhead{Modelica Language Specification \mlsversion\\ \nouppercase{\rightmark} \vspace{1mm}}
58 | \lhead{\includegraphics[height=6.5mm]{Modelica_Language}}
59 | \renewcommand{\headrulewidth}{0.0pt}
60 |
61 | \hypersetup{pageanchor=true}
62 |
63 | % Copyright
64 | \include{chapters/copyright}
65 |
66 | \cleardoublepage
67 | \tableofcontents
68 |
69 | % Preface
70 | \include{chapters/preface}
71 |
72 | % Introduction
73 | \include{chapters/introduction}
74 |
75 | % Lexical Structure
76 | \include{chapters/lexicalstructure}
77 |
78 | % Operators and Expressions
79 | \include{chapters/operatorsandexpressions}
80 |
81 | % Classes, Predefined Types, and Declarations
82 | \include{chapters/classes}
83 |
84 | % Scoping, Name Lookup, and Flattening
85 | \include{chapters/scoping}
86 |
87 | % Interface or Type Relationships
88 | \include{chapters/interface}
89 |
90 | % Inheritance, Modification, and Redeclaration
91 | \include{chapters/inheritance}
92 |
93 | % Equations
94 | \include{chapters/equations}
95 |
96 | % Connectors and Connections
97 | \include{chapters/connectors}
98 |
99 | % Arrays
100 | \include{chapters/arrays}
101 |
102 | % Statements and Algorithm Chapters
103 | \include{chapters/statements}
104 |
105 | % Functions
106 | \include{chapters/functions}
107 |
108 | % Packages
109 | \include{chapters/packages}
110 |
111 | % Overloaded Operators
112 | \include{chapters/overloaded}
113 |
114 | % Stream Connectors
115 | \include{chapters/stream}
116 |
117 | % Synchronous Language Elements
118 | \include{chapters/synchronous}
119 |
120 | % State Machines
121 | \include{chapters/statemachines}
122 |
123 | % Annotations
124 | \include{chapters/annotations}
125 |
126 | % Unit Expressions
127 | \include{chapters/unitexpressions}
128 |
129 | % The Modelica Standard Library
130 | \include{chapters/library}
131 |
132 | \appendix
133 | % https://tex.stackexchange.com/questions/370384/change-toc-depth-mid-document
134 | \addtocontents{toc}{\setcounter{tocdepth}{0}}
135 |
136 | % Modelica Concrete Syntax
137 | \include{chapters/syntax}
138 |
139 | % Modelica DAE Representation}
140 | \include{chapters/dae}
141 |
142 | % Derivation of Stream Equations
143 | \include{chapters/derivationofstream}
144 |
145 | % Modelica Revision History
146 | \include{chapters/revisions}
147 |
148 | \clearpage% get the \phantomsection below on the correct page
149 | \phantomsection
150 | \addcontentsline{toc}{chapter}{\bibname}%
151 | \ifpdf
152 | \printbibliography
153 | \else
154 | \bibliography{mls}
155 | \fi
156 |
157 | \clearpage% get the \phantomsection below on the correct page
158 | \phantomsection
159 | \addcontentsline{toc}{chapter}{\indexname}%
160 | \label{document-index}
161 | \printindex
162 |
163 | \end{document}
164 |
--------------------------------------------------------------------------------
/Makefile:
--------------------------------------------------------------------------------
1 | # Note: Using latexmk, since it automatically runs pdflatex as many times as needed.
2 | #
3 | # If you have latexml source (preferably with UseLabal patch) set:
4 | # LATEXMLPREFIX=perl
5 | # Otherwise we rely on the default one
6 |
7 | all: MLS.pdf MLS.html
8 |
9 | .PHONY: clean-pdf
10 | clean-pdf:
11 | -rm MLS.pdf MLS.log *.out *.aux chapters/*.aux *.toc *.fls *.bbl *.bcf *.blg *.run.xml *.idx *.ilg *.ind
12 |
13 | .PHONY: clean-html
14 | clean-html:
15 | -rm MLS.xml LaTeXML.cache MLS.fdb_latexmk *.html *.css *.js
16 |
17 | .PHONY: clean
18 | clean: clean-pdf clean-html
19 |
20 | MLS.pdf: *.tex chapters/*.tex
21 | latexmk -pdf MLS.tex
22 |
23 | # Seems to be some issue with graphicpath, so set path here as well
24 | # Not using %.html since nmake does not support it (instead using old-style suffix rules)
25 | index.html: MLS.tex chapters/*.tex
26 | $(LATEXMLPREFIX)latexml MLS.tex --includestyles --path=media --dest MLS.xml
27 | $(LATEXMLPREFIX)latexmlpost MLS.xml -format html -pmml --splitat=chapter --splitnaming=labelrelative --javascript=LaTeXML-maybeMathjax.js --navigationtoc=context --css=css/MLS.css --css=css/MLS-navbar-left.css --dest $@
28 | .scripts/patch-viewport.sh
29 | .scripts/patch-body-ios-hover.sh
30 |
--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
1 |
2 |
3 |
4 | # ModelicaSpecification
5 | This repository contains the Modelica Language Specification, hosted at https://github.com/modelica/ModelicaSpecification.
6 | Development is organized within the [Modelica Association Project Language (MAP-Lang)](https://modelica.org/projects) according to the [project rules](https://github.com/modelica/MAP-Lang_ProjectRules/blob/main/MAP-Lang-ProjectRules.md).
7 |
8 | ## Description
9 |
10 | Modelica® is a language for modeling of cyber-physical systems, supporting acausal connection of components governed by mathematical equations to facilitate modeling from first principles.
11 | It provides object-oriented constructs that facilitate reuse of models, and can be used conveniently for modeling complex systems containing, e.g., mechanical, electrical, electronic, magnetic, hydraulic, thermal, control, electric power or process-oriented subcomponents.
12 |
13 | ## Releases
14 |
15 | Version | Link | Published | Changes |
16 | ------- | ----------------------------------------------------------------- | --------| ---|
17 | 3.7-dev | [Master branch](https://github.com/modelica/ModelicaSpecification/tree/master) [HTML](https://specification.modelica.org/master/) [PDF](https://specification.modelica.org/master/MLS.pdf)| not yet | [Search](https://github.com/modelica/ModelicaSpecification/issues?q=label%3AM37+is%3Aclosed) |
18 | 3.6 | [3.6 branch](https://github.com/modelica/ModelicaSpecification/tree/maint/3.6) [HTML](https://specification.modelica.org/maint/3.6/MLS.html) [PDF](https://specification.modelica.org/maint/3.6/MLS.pdf)| 2023 | [Search](https://github.com/modelica/ModelicaSpecification/issues?q=label%3AM36+is%3Aclosed) [HTML](https://specification.modelica.org/maint/3.6/modelica-revision-history.html#modelica-3-6) |
19 | 3.5 | [3.5 branch](https://github.com/modelica/ModelicaSpecification/tree/maint/3.5) [HTML](https://specification.modelica.org/maint/3.5/MLS.html) [PDF](https://specification.modelica.org/maint/3.5/MLS.pdf)| 2021 | [HTML](https://specification.modelica.org/maint/3.6/modelica-revision-history.html#modelica-3-5) |
20 | 3.4 | [3.4 branch](https://github.com/modelica/ModelicaSpecification/tree/maint/3.4) [HTML](https://specification.modelica.org/maint/3.4/MLS.html) [PDF](https://modelica.org/documents/ModelicaSpec34.pdf) | 2017 | [HTML](https://specification.modelica.org/maint/3.6/modelica-revision-history.html#modelica-3-4) |
21 | 3.3rev1 | [PDF](https://modelica.org/documents/ModelicaSpec33Revision1.pdf) | 2014 | [HTML](https://specification.modelica.org/maint/3.6/modelica-revision-history.html#modelica-3-3-revision-1) |
22 | 3.2rev2 | [PDF](https://modelica.org/documents/ModelicaSpec32Revision2.pdf) | 2013 | [HTML](https://specification.modelica.org/maint/3.6/modelica-revision-history.html#modelica-3-2-revision-2) |
23 | 3.2rev1 | [PDF](https://modelica.org/documents/ModelicaSpec32Revision1.pdf) | 2012 | [HTML](https://specification.modelica.org/maint/3.6/modelica-revision-history.html#modelica-3-2-revision-1) |
24 | 3.3 | [PDF](https://modelica.org/documents/ModelicaSpec33.pdf) | 2012 | [HTML](https://specification.modelica.org/maint/3.6/modelica-revision-history.html#modelica-3-3) |
25 | 3.2 | [PDF](https://modelica.org/documents/ModelicaSpec32.pdf) | 2010 | [HTML](https://specification.modelica.org/maint/3.6/modelica-revision-history.html#modelica-3-2) |
26 | 3.1 | [PDF](https://modelica.org/documents/ModelicaSpec31.pdf) | 2009 | [HTML](https://specification.modelica.org/maint/3.6/modelica-revision-history.html#modelica-3-1) |
27 | 3.0 | [PDF](https://modelica.org/documents/ModelicaSpec30.pdf) | 2007 | [HTML](https://specification.modelica.org/maint/3.6/modelica-revision-history.html#modelica-3-0) |
28 | 2.2 | [PDF](https://modelica.org/documents/ModelicaSpec22.pdf) | 2005 | [HTML](https://specification.modelica.org/maint/3.6/modelica-revision-history.html#modelica-2-2) |
29 | 2.1 | [PDF](https://modelica.org/documents/ModelicaSpec21.pdf) | 2004 | [HTML](https://specification.modelica.org/maint/3.6/modelica-revision-history.html#modelica-2-1) |
30 | 2.0 | [PDF](https://modelica.org/documents/ModelicaSpec20.pdf) | 2002 | [HTML](https://specification.modelica.org/maint/3.6/modelica-revision-history.html#modelica-2-0) |
31 | 1.4 | [PDF](https://modelica.org/documents/ModelicaSpec14.pdf) | 2000 | [HTML](https://specification.modelica.org/maint/3.6/modelica-revision-history.html#modelica-1-4) |
32 | 1.3 | [PDF](https://modelica.org/documents/ModelicaSpec13norev.pdf) | 1999 | [HTML](https://specification.modelica.org/maint/3.6/modelica-revision-history.html#modelica-1-3) |
33 | 1.2 | [PDF](https://modelica.org/documents/modelicaspec12norev.pdf) | 1999 | [HTML](https://specification.modelica.org/maint/3.6/modelica-revision-history.html#modelica-1-2) |
34 | 1.1 | [PDF](https://modelica.org/documents/ModelicaSpec11.pdf) | 1998 | [HTML](https://specification.modelica.org/maint/3.6/modelica-revision-history.html#modelica-1-1) |
35 | 1.0 | [PDF](https://modelica.org/documents/Modelica1.pdf) | 1997 | |
36 |
37 | ## Contribution
38 | 1. If you find an error and are not certain that you can correct it, first check that it is not already reported and then open an [issue](https://github.com/modelica/ModelicaSpecification/issues) describing it in detail - focusing on why it should be changed.
39 | 2. If you are confident that you can correct the issue, fork this repository and create a pull-request and in the pull-request explain the issue and the correction; you will also have to sign a CLA.
40 | 3. Significant extensions are handled as Modelica Change Proposals (MCPs). This can start as a simple description of the proposed extension. It will then be worked on to have a rationale explaining how the change help users, and demonstrating that it can be implemented efficiently; and finally a pull-request with the changes.
41 |
42 | For more details, see the [Development Process](https://github.com/modelica/ModelicaSpecification/blob/master/RationaleMCP/DevelopmentProcess.md).
43 | A list of MCPs can be found here: [RationaleMCP](https://github.com/modelica/ModelicaSpecification/tree/master/RationaleMCP).
44 |
45 | CLA: Contributor's license agreement. (Details to follow.)
46 |
47 | How to edit and generate final documents
48 | * Read the [style guide](styleguide.md).
49 | * For online editing you can use www.overleaf.com (details to follow)
50 | * The pdf-documents are generated with pdflatex, which is part of most LaTeX installations, we used http://miktex.org/download
51 | * The HTML-documents are generated with LaTeXML. That is more complicated to install - and can optionally be skipped:
52 | 1. First you need perl, we used http://strawberryperl.com/
53 | 2. And then the official LaTeXML package (0.8.5 or later): http://dlmf.nist.gov/LaTeXML/get.html#SS4.SSS0.Px1 or https://github.com/brucemiller/LaTeXML
54 | 3. The exact commands are in the Makefile
55 |
56 | It is also possible to get a preview in the pull request.
57 | There will be a link to the [status check](https://test.openmodelica.org/jenkins/job/ModelicaAssociation/job/ModelicaSpecification/view/change-requests/), which checks that the documents can be generated and gives you an option to download them.
58 |
--------------------------------------------------------------------------------
/RationaleMCP/0009/README.md:
--------------------------------------------------------------------------------
1 | Modelica Change Proposal MCP-0009
2 |
3 | Removing Modifications
4 |
5 | Hans Olsson, Gerd Kurzbach, Hilding Elmqvist, Martin Otter, Michael Tiller
6 | (In Development)
7 |
8 |
9 | # Summary
10 | This MCP proposes a possibility to remove existing, in particular inherited, modifications.
11 |
12 | # Revisions
13 | | Date | Description |
14 | | --- | --- |
15 | | 2013-12-07 | Initial Draft under the name MCPI-0009_UndefinedModifications by Gerd Kurzbach (initial idea is from Hilding Elmqvist; contributions from Martin Otter and Michael Tiller to this draft are included).| |
16 | | 2014-06-14 | Update. Added corrections and results from discussions (#1377), clarifications and other proposals|
17 | | 2018-03-23 | Second Version with changed name, simplified and streamlined, no more related to custom annotations MCP-0008|
18 | | 2021-03-17 | Converted to markdown, by Hans Olsson and added new syntax-variant from Gerd Kurzbach |
19 | | 2021-03-18 | Hans Olsson - added experience from Dymola |
20 | | 2021-03-24 | Hans Olsson - feedback on prototype |
21 | | 2021-05-03 | Hans Olsson - additional feedback on prototype |
22 | | 2021-05-05 | Hans Olsson - feedback at language meeting |
23 | | 2021-06-16 | Hans Olsson - removed `` |
24 | | 2022-05-11 | Hans Olsson - explained extended scope |
25 |
26 | # Contributor License Agreement
27 | All authors of this MCP or their organizations have signed the "Modelica Contributor License Agreement".
28 |
29 | # Rationale
30 | To parametrize components of classes modifications can be added.
31 | These modifications are merged with others, when the class is used as component in another class.
32 | Once a modification is placed at a component, currently there is no way to remove this again at the place of usage of the surrounding class.
33 | This prevents a more sophisticated determination of parameter values, e.g., by initial equations.
34 | This MCP proposes a possibility to remove existing, in particular inherited, modifications.
35 | The result are free parameters or variables, which then can be calculated by initial or transient equations or algorithms.
36 | This allows more flexibility when using library elements because it enables a possibility to replace equations.
37 |
38 | # Proposal
39 |
40 | ## Syntax
41 | It is proposed to introduce a new keyword, when used as modification, removes an inherited modification and leaves the modified element as if it was never modified.
42 |
43 | Requirements to this keyword are:
44 | * It needs to be easily disdinguished from a modification expression, therefore it should not be part of the expression non terminal.
45 | * It should be self explaining and not contain only control characters.
46 | * It should not break existing models by leading to unpredictable results.
47 |
48 | Because simple names are expressions and when becoming a keyword that may break existing models it was considered to extend a descriptive name with some special characters.
49 | That lead to the proposal to use the keword `break` (after first considering ``), which fulfills the requirements.
50 |
51 | Syntactically the rule of a modification is extended:
52 |
53 | ```
54 | modification :
55 | class-modification [ "=" modification-expression ]
56 | | "=" modification-expression
57 | | ":=" modification-expression
58 |
59 | modification-expression :
60 | expression
61 | | break
62 | ```
63 |
64 | ## Rules
65 | Modifications containing `break` do not need special handling when they are merged during instantiation of models.
66 | They either override other modifications or will be overridden as usual.
67 | It is also not allowed to override modifications having the final prefix.
68 | Only during flattening of an instantiated model, remaining `break` modifications are seen as not present.
69 | They have no further influence on the model equations.
70 |
71 | ## Impact on balanced models.
72 | The section on balanced model does in some cases have a restrictions on modifiers:
73 | "The binding equations in modifiers for components may in these cases only be for parameters, constants, inputs and variables having a default binding equation."
74 | The latter case interacts with `break`, and the simplest solution seems to be:
75 | "For the latter case of variables having a default binding equation (that are not parameter, constant, or input) the modifier may not remove the binding equation using break."
76 |
77 | Alternatives would be that it is allowed to remove the binding equation, as long as a normal binding equation is added later, or that it is allowed to remove it and replace it with a normal equation. Both variants seem more complicated and with unclear benefits - but might be considered for the future if the need arises.
78 |
79 | # Discussion of effects
80 |
81 | ## In Equations
82 |
83 | Because of the keyword `break` is not an expression, it cannot be used at other places than modifications, neither in equations nor in algorithms.
84 | It is also not possible to use it as sub expression inside modifications, therefore no operators or functions must deal with it.
85 | That eases the implementation in the compiler, because no runtime is needed.
86 | `break` is not a value. It is just a marker to the modification, that it will be ignored.
87 |
88 | A parameter or variable with the `break` modification behaves in the same way as with no modification.
89 | If such a parameter is referenced at places, where the value must be known at compile time (structural parameter), an error is given.
90 | Variables and parameters having ``break` modifications are free variables and must be calculated by an additional equation or algorithm.
91 | Otherwise there would be one missing equation, which leads to an error.
92 | From the point of the equation system they behave the same as variables without modification.
93 |
94 | ## In Annotations
95 |
96 | The use in annotations is not really useful, because they are not merged in current Modelica.
97 | Therefore no modification can be overridden.
98 | Finally, if an annotation has the `break` modification but needs to have a value to work properly, a tool provided default value may be used instead.
99 |
100 | ## In the GUI
101 |
102 | In a dialog, a tool may hide the keyword `break` from the users and present them only an empty input field, not showing the overridden modification.
103 | Then, there needs to be a possibility to remove it again to get back the overridden modification.
104 |
105 | # Use cases
106 |
107 | ## Variables
108 |
109 | If there is an inherited modification from a base class and you want to replace them by a (probably more sophisticated) equation or an algorithm in the `break` can be used in the derived class:
110 | ```
111 | model A
112 | Real x=1;
113 | end A;
114 | model B
115 | extends A(x=break);
116 | algorithm
117 | x:=0;
118 | while(…)
119 | x:= x+ …
120 | end while;
121 | end B;
122 | ```
123 |
124 | ## Parameters
125 |
126 | Another similar use case is to make an initial state from a parameter:
127 | ```
128 | model A
129 | parameter Real diameter = 1;
130 | final parameter radius = diameter/2;
131 | end A;
132 |
133 | model B
134 | extends A(diameter(fixed=false)=break);
135 | parameter Real sqare;
136 | initial equation
137 | // assuming this cannot be solved symbolically for diameter
138 | square =f(diameter);
139 | end B;
140 | ```
141 | ## Removing unwanted defaults
142 | As an practical example consider reusing `Modelica.Fluid.Pipes.StaticPipe` - when you don't like the defaults for `roughness` and `height_ab` and want to ensure that users provide both.
143 |
144 | Previously you would have to create a complete wrapper for this model, since the bad defaults are in a base-class.
145 |
146 | Now you can just write:
147 | ```
148 | model MyPipe
149 | extends Modelica.Fluid.Pipes.StaticPipe(roughness=break, height_ab=break);
150 | end MyPipe;
151 | ```
152 | and use `MyPipe` instead.
153 |
154 | # Backwards Compatibility
155 | The new syntax ensures that it is backwards compatible.
156 | Although the `break`-syntax overlaps with ([MCP/0032](https://github.com/modelica/ModelicaSpecification/tree/MCP/0032/RationaleMCP/0032)) they can be combined without problems.
157 |
158 | # Tool Implementation
159 | Implemented in SimulationX since a long time ago.
160 | Test-implemented in Dymola 2022.
161 |
162 | ## Experience with Prototype
163 | The experience with a simple prototype implementation in Dymola is that it can mostly be implemented in less than a day.
164 | (There might be some rough spots remaining.)
165 | The use cases above are relevant also for large industrial models.
166 |
167 | One additional relevant use case is allowing re-using of models that have unwanted defaults; added above.
168 |
169 | ### Removing more?
170 | From the user perspective there was feedback that it was seen as somewhat problematic that defaults (using `p(start=...)` for parameters) was not removed by a simple modifier `p=break` since that only undefine the value. Based on the proposal that is deliberate and also setting start=break is possible for users, and can be automated in tools.
171 | The other simple option would be that `p=break` removed modifiers for all attributes, but that have the undesired consequence of undefining unit and displayUnit.
172 | Undefining everything that isn't in the type would be counter-intuitive and sometimes fail to remove start-values and sometimes remove displayUnit.
173 | Note that there is no requirement that the undefined modification actually override something.
174 |
175 | # Required Patents
176 | No patents needed.
177 | # References
178 |
--------------------------------------------------------------------------------
/RationaleMCP/0014/MCP-0014_Conversion.pdf:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/modelica/ModelicaSpecification/9ad2a9233cde7cc0a63d993681dc56bdc8f01e56/RationaleMCP/0014/MCP-0014_Conversion.pdf
--------------------------------------------------------------------------------
/RationaleMCP/0014/MCP_0014_Conversion_SpecChanges.pdf:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/modelica/ModelicaSpecification/9ad2a9233cde7cc0a63d993681dc56bdc8f01e56/RationaleMCP/0014/MCP_0014_Conversion_SpecChanges.pdf
--------------------------------------------------------------------------------
/RationaleMCP/0029/ReadMe.md:
--------------------------------------------------------------------------------
1 | # Modelica Change Proposal MCP-0029 License Export
2 | Thomas Beutlich
3 |
4 | **(In Development)**
5 |
6 | ## Summary
7 | The primary goal is to support Modelica simulation tools in providing the correct licenses for exported models that are meant for distribution, e.g. FMUs.
8 | By introduction of additional annotations the exporting Modelica tool can utilize these license information (no matter if open-source license or proprietary license) according to the exported target.
9 | This applies both to the code generated from the utilized top-level Modelica classes as well as for the external function interface (Include or static/shared Library) of Modelica.
10 | This shifts the responsibility of providing the necessary license information from the tool vendors to the Modelica library developers.
11 |
12 | ## Revisions
13 | | Date | Description |
14 | | --- | --- |
15 | | 2017-12-07 | Thomas Beutlich. Based on input from Christian Bertsch at [FMI#417](https://github.com/modelica/fmi-standard/issues/417) |
16 | | 2023-07-07 | Hans Olsson. Added prototype implementation |
17 |
18 | ## Contributor License Agreement
19 | All authors of this MCP or their organizations have signed the "Modelica Contributor License Agreement".
20 |
21 | ## Rationale
22 | Translated and exported Modelica models, which are meant for distribution, need to provide the necessary licenses, i.e., the licenses of third-party software used in external functions and libraries and the license of the top-level Modelica package itself.
23 |
24 | Currently, the license information is neither considered at all (even if available as documentation or resource) for exported models or based on some analysis of tool vendors to create at least some kind of exported license information.
25 | This proposal improves the situation both for tool vendors as well as library developers to create legally correct exported models.
26 | A library developer needs to provide the relevant license information as external resource, which on the other hand can be considered by a Modelica tool during the export process.
27 |
28 | Use-cases:
29 | 1. Export a Modelica model with Modelica.Blocks.Continuous.PID as FMU for ME and distribute this FMU to external customers or partners.
30 | Along with the FMU the distributor needs to provide the information of utilized software components, e.g., the MSL, which as of v4.0.0 is licensed under the 3-Clause BSD license.
31 | 1. Export a Modelica model with Modelica.Blocks.Sources.CombiTable1D as S-Function and distribute this S-Function to external customers or partners.
32 | Along with the S-Function the distributor needs to provide the information of utilized third-party software of the ModelicaStandardTables, zlib, uthash etc.
33 | 1. Export a Modelica model with Modelica.Blocks.Continuous.PID as FMU for CS and distribute this FMU to external customers or partners.
34 | Along with the FMU the distributor needs to provide the information of utilized software components, e.g., the utilized solver.
35 | The license conditions of the solver component need to be respected, e.g., in case of the SUNDIALS CVode solver the relevant license information should be made obvious for the FMU receiver by means of an appropriate license file/text.
36 |
37 | Remark: Compared to the first two aspects, the third aspect solely is a tool issue, but stated here for completeness.
38 |
39 | ## Backwards Compatibility
40 |
41 | This change does not introduce any backwards incompatibilities.
42 |
43 | ## Tool Implementation
44 |
45 | ### Experience with Prototype
46 |
47 | On the library side, the necessary changes have been applied to library _ExternData_.
48 | The following commits at the Git repository at https://github.com/modelica-3rdparty/ExternData demonstrate the necessary steps to update a Modelica libarry.
49 |
50 | 1. https://github.com/modelica-3rdparty/ExternData/commit/7522046dce6d20fe01a85a559b02fd9d8878bdd2
51 | - All license files were added as text files to a new directory ExternData/Resources/Licenses.
52 | The file format is not restricted to Text with a special encoding, but any file format (e.g., Mark-Down, PDF, HTML) basically can be supported.
53 | The license file LICENSE_ExternData.txt is the corresponding license of the copyright holder of the Modelica package, all other license files reflect third-party software components.
54 | - It is recommended to use ModelicaPackage/Resource/Licenses as the directory for the license files.
55 | 1. https://github.com/modelica-3rdparty/ExternData/commit/f38372d825b20eac4de01ce01b95560522b43ad2
56 | - The license file LICENSE_ExternData.txt of the Modelica package is referenced by the Modelica top-level class as new annotation License="modelica://ExternData/Resources/Licenses/LICENSE_ExternData.txt".
57 | To introduce this new annotation on existing Modelica packages in a Modelica-compliant and vendorneutral way, the `__ModelicaAssociation` prefix was added (similar as `__ModelicaAssociation_Impure` in MSL v3.2.2).
58 | This means, that library developers can adopt early to this proposal, for example a new MSL v3.2.3 can already introduce this new annotation and is not needed to be based on a new release of the Modelica language specification.
59 | 1. https://github.com/modelica-3rdparty/ExternData/commit/d6dec789aec1c1333386161147c91cdd49b484d0
60 | - All third-party licenses are listed as new License annotation to the external functions.
61 | There is some redundancy here in specifying the license directory many times in the Modelica URIs, but this is not a serious issue.
62 | Again, the `__ModelicaAssociation` prefix was added for Modelica-compliant tool-neutrality
63 |
64 | Currently, a simple prototype is implemented in Dymola, supporting top-level and function annotation (both variants) and including them in the documentation folder in the FMI.
65 | As previously estimated implementation effort for exporting Modelica models with exported licenses is rather low.
66 | A tool needs to collect the license information of all utilized top-level Modelica packages and all utilized external functions and copy these files to the specified export directory depending on the export target system.
67 |
68 | ## Required Patents
69 |
70 | No patent known that would be required for implementation of this proposal.
71 |
72 | ## References
73 |
74 | FMUs must contain all relevant license information. https://github.com/modelica/fmi-standard/issues/417
75 |
76 | Vendor Neutral Modelica Annotation Prototypes in MSL. https://github.com/modelica/ModelicaStandardLibrary/issues/849
77 |
78 | Analysis of third-party licenses of the MSL C-Sources. https://github.com/modelica/ModelicaStandardLibrary/issues/2253
79 |
80 | Issue with discussions prior to creation of MCP branch. https://github.com/modelica/ModelicaSpecification/issues/2217
81 |
--------------------------------------------------------------------------------
/RationaleMCP/0032/examples/SelectiveExtension_13th_Modelica_Conference 0.1.0.zip:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/modelica/ModelicaSpecification/9ad2a9233cde7cc0a63d993681dc56bdc8f01e56/RationaleMCP/0032/examples/SelectiveExtension_13th_Modelica_Conference 0.1.0.zip
--------------------------------------------------------------------------------
/RationaleMCP/0032/examples/SelectiveExtension_13th_Modelica_Conference 0.2.0.zip:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/modelica/ModelicaSpecification/9ad2a9233cde7cc0a63d993681dc56bdc8f01e56/RationaleMCP/0032/examples/SelectiveExtension_13th_Modelica_Conference 0.2.0.zip
--------------------------------------------------------------------------------
/RationaleMCP/0032/examples/SelectiveExtension_13th_Modelica_Conference 0.3.0.zip:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/modelica/ModelicaSpecification/9ad2a9233cde7cc0a63d993681dc56bdc8f01e56/RationaleMCP/0032/examples/SelectiveExtension_13th_Modelica_Conference 0.3.0.zip
--------------------------------------------------------------------------------
/RationaleMCP/0032/examples/SelectiveExtension_13th_Modelica_Conference 0.4.0.zip:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/modelica/ModelicaSpecification/9ad2a9233cde7cc0a63d993681dc56bdc8f01e56/RationaleMCP/0032/examples/SelectiveExtension_13th_Modelica_Conference 0.4.0.zip
--------------------------------------------------------------------------------
/RationaleMCP/0032/minutes.md:
--------------------------------------------------------------------------------
1 | # Minutes
2 |
3 | The following list compiles minutes of all official events and discussions -- like _Modelica Design Meetings_ -- where selective model extension has been a topic. The list summarizes only the ideas, concerns and final decisions relevant for selective model extension and skips any further topics typically discussed at the listed meetings (such can be found in the official minutes linked to). On the other hand, the following summaries often contain more detailed notes on decision reasons, open problems and the scope of selective model extension than the official meeting minutes.
4 |
5 | ## _98th Modelica Design Meeting_
6 |
7 | - [**Original minutes**](https://svn.modelica.org/projects/ModelicaDesign/trunk/MeetingMinutesMaterial/min98_2019_Regensburg/); Issue #2329
8 | - **Decision (discussion):** Align deselections with `extends`-clauses as part of the modifier.
9 | - No need for `extends`-clause independent, general deselection syntax (`for each extends` ) as used in the Modelica 2019 conference paper ([Modelica language extensions for practical non-monotonic modelling: on the need for selective model extension](https://modelica.org/events/modelica2019/proceedings/html/papers/Modelica2019paper3B1.pdf)).
10 | - Multiple inheritance: Elements inherited multiple times must be deselected at each `extends`-clause introducing them to deselect them completely. Thus, deselection is fine grained, only deselecting the element from the base-class of the respective `extends`-clause the deselection is part of.
11 |
12 | - **Decision (discussion):** Only allow deselections _directly_ inside `extends`-modifier. No support for deselecting nested elements, likewise Modelica has no means to introduce such. To support _both_ is subject for later MCPs.
13 |
14 | - **Decision (discussion):** No support for fine-grained connection deselection (i.e. removing only parts of a connection).
15 |
16 | - **Decision (poll):** Use `break` as keyword like proposed in the Modelica 2019 conference paper; also use the same syntax for component and connection deselections (i.e., `break component-name` and `break connect(first-connector, second-connector)`).
17 | - Other suggestions, instead of `break`, have been `not`, `remove`, `ignore`, `redeclare Type component-name if false` after component, `notPresent`, `deselect`, `without`, `undeclare`, use new character `$ignore component-name` or use some new function syntax.
18 | - Advantage of `break` is that it does not introduce a new keyword; its backward compatibility outweighs gain of readability. `break` is readable enough.
19 |
20 | ## _99th Modelica Design Meeting_
21 |
22 | - [**Original minutes**](https://svn.modelica.org/projects/ModelicaDesign/trunk/MeetingMinutesMaterial/min99_2019_Linkoeping/)
23 |
24 | - **Decision (discussion):** No need to support deselections within `long-class-specifier`. Support deselection only within `extends-clause`.
25 |
26 | - **Decision (poll):** Only allow deselections _directly_ inside `extends-clause`, i.e., only as top-level/non-nested modification. This should be specified in terms of the context-free grammar of the Modelica specification, not as semantic rule. No ordering of modifications should be enforced; ordinary- and inheritance-modifications (deselections) can be in arbitrary order as long as inheritance modifications are top-level modifications.
27 | - **Rationale why only top-level inheritance modifications:** Defining the semantics of nested deselection modifications or supporting such is not a problem. But to be useful, it also has to be possible to add elements in terms of nested modifications; otherwise, deselecting connections of a nested sub-component will, for example, most likely result in non-fixable singular equation systems. In the long run, it therefore would be good to add both, (1) language means for adding elements to nested sub-components within modifications and analogous (2) deselecting nested sub-components.
28 | - **Rationale why modification order doesn't matter:** Modelica is declarative; it is a general objective of the Modelica language design that order doesn't matter.
29 |
30 | - **Decision 99.3 (poll), reverted by decision 101.1:** For connection deselections, the order of the `connect` arguments does not matter; `break connect(a, b)` deselects the connection between `a` and `b` regardless if it is defined as `connect(a, b)` or `connect(b, a)` in the selectively extended base-class.
31 | - **Rationale 99.3.1 why order of `connect` arguments doesn't matter:** Modelica is declarative; it is a general objective of the Modelica language design that order doesn't matter. Also, a base-class refactoring just switching the order of a connection's arguments should not break existing deselections in models selectively extending the base-class.
32 |
33 | - **Decision 99.4 (poll), further restricted by decision 101.1:** Connection deselection is based on syntactic equivalence, i.e., matching of ASTs. Let `a` and `b` be the arguments of a connection deselection _D_ (i.e., _D_ = `break connect(a, b)`). Let _C_ = `connect(c, d)` be a connection defined in the base-class selectively extended by the `extends`-clause _D_ is is a modifier of. _D_ deselects _C_, if, and only if, either, `c` is syntactically equivalent to `a` and `d` is syntactically equivalent to `b` or, vice versa, `c` is syntactically equivalent to `b` and `d` is syntactically equivalent to `a`.
34 | - Two code fragments `a` and `b` are syntactically equivalent, if, and only if, the context-free derivations of `a` and `b` according to the grammar given in Appendix B of the Modelica 3.4 specification are the same.
35 |
36 | - **Discussion:** Is it permitted or prohibited to deselect connections defined inside `for-equation` and `if-equation`, i.e., connections that are conditionally defined?
37 | - Discussion has to be continued at the next _Modelica Design Meeting_, where we should try to achieve a decision.
38 | - **Open question (discussion to continue at the next meeting):** What have been the reasons for prohibiting deselection of conditionally defined connections? Is it just that such typically have no graphical representation such that deselecting them from within the diagram layer/graphically is typically not possible but we like deselections to be understandable in terms of graphical diagram edits? Or are there general conceptional issues?
39 | - **Open question (not discussed so far, but to do so at the next meeting):** What is about conditionally declared components? Are there conceptional or practical problems with deselecting such?
40 |
41 | ## _100th Modelica Design Meeting_
42 |
43 | - [**Original minutes**](https://svn.modelica.org/projects/ModelicaDesign/trunk/MeetingMinutesMaterial/min100_2019_Lund/Slides-and-Documents/Language/)
44 |
45 | - **Decision (poll):** Deselection of conditionally declared components is permitted.
46 | - Deselections of extending classes have a higher priority than conditional declarations of base-classes; deselecting a conditionally declared component excludes it from inheritance irrespective of whether the component is declared or not (i.e., irrespective if the declaration's condition is satisfied).
47 |
48 | - **Decision (poll):** Deselection of connections inside conditional equations is permitted.
49 | - Tight poll: Yes 4, No 2, Abstain 3
50 | - Again, deselections of extending classes have a higher priority than conditional connections of base-classes; deselecting a conditional connection excludes it from inheritance irrespective of whether the connection is established or not (i.e., irrespective if the connections condition is satisfied).
51 |
52 | - **Decision 100.3 (poll):** Deselection of connect equations inside a `for-equation` are permitted.
53 | - Tight poll: Yes 3, No 3, Abstain 3
54 | - Such deselections are based on syntactic matching of ASTs like defined at the _99th Modelica Design Meeting_; deselecting an iterated connect equation therefore deselects all its instances, i.e., all connections it establishes. For example, `break connect(b[i].o, b[i + 1].i)` deselects all connections established by `for i in 1:size(b,1)-1 loop connect(b[i + 1].i, b[i].o); end for;`.
55 |
56 | - **Decision 100.4 (discussion):** Syntactic equivalence as defined by decision 99.4 is the base-paradigm for connection deselections.
57 |
58 | ## _101th Modelica Design Meeting_
59 |
60 | - [**Original minutes**](https://svn.modelica.org/projects/ModelicaDesign/trunk/MeetingMinutesMaterial/min101_2019_Oberpfaffenhofen/)
61 | - **Decision 101.1 (poll), changes decision 99.3, further restricts decision 99.4:** For connection deselections, the order of the `connect` arguments matters. `break connect(a, b)` only deselects the connection between `a` and `b` if it is defined as `connect(a, b)` in the selectively extended base-class; it does not deselect it if it is defined as `connect(b, a)` .
62 | - Clear poll: Yes 7, No 0, Abstain 3
63 | - **Rationale 101.1.1 why order of `connect` arguments matters:** In decision 100.4, syntactic equivalence has been established as base-paradigm for connection deselections; it is strange, if there are relaxing exceptions.
64 | - Rationale 101.1.1 is in conflict with rationale 99.3.1.
65 | - **Open question (discussion to continue at the next meeting):** We forgot to reconsider rationale 99.3.1 when doing this decision. We have to choose either, decision 99.3 or 101.1, weighting rationale 99.3.1 vs. rationale 101.1.1.
66 | - **Discussion:** One result of decisions 100.3 and 100.4 is, that syntactic equivalence deselects _all_ matching base-class connections, regardless in which `for-equation` they are. For example, if the base class has two `for-equation`, each establishing connections `connect(b[i].o, b[i + 1].i)` -- like `for i in 1:3 loop connect(b[i + 1].i, b[i].o); end for;` and `for i in 5:7 loop connect(b[i + 1].i, b[i].o); end for;` -- the single `break connect(b[i].o, b[i + 1].i)` deselects all respective connections.
67 |
68 | ## _Modelica Phone Meeting (2021-09-28, 15:00)_
69 |
70 | * Discussed further roadmap on how to get selective model extension soon into the Modelica Standard:
71 | * Proposal: Only one prototype implementation in Dymola (instead of the usual two) and instead comprehensive examples library and proof reading of the MCP by other tool implementors.
72 | * Open question: Do the MAP-Lang bylaws need to be adapted to support this process?
73 | * In general such a process is desired and should be supported by the bylaws.
74 |
75 |
--------------------------------------------------------------------------------
/RationaleMCP/0033/ReadMe.md:
--------------------------------------------------------------------------------
1 | # Modelica Change Proposal MCP-0033 Annotations for Predefined Plots
2 | Henrik Tidefelt, Otto Tronarp
3 |
4 | **(Under Evaluation)**
5 |
6 | 
7 |
8 | ## Summary
9 | This is not about defining plotting functions to be used in scripting environments. This is about declarative descriptions of predefined plots, stored in the model's class annotation. It makes it completely agnostic to scripting environments, but scripting environments can still take advantage of the predefined plots. For instance, the Wolfram SystemModeler environment allows users to request a predefined plot with a given title in the scripting environment, where it is then possible to apply further customization that is beyond the scope of what is reasonable to include in an MCP.
10 |
11 | The use of predefined plots has been proven to greatly enhance the value of example models for users of a library, since they don't need to read documentation of the examples in one place, and then find the relevant things to plot in another place. To be given a preferred plot immediately after simulation is generally a much faster way of getting an idea of what the example is all about, compared to reading the example's documentation.
12 |
13 | The declarative style makes it straight-forward to extract the signals that are used in plots, so that these can be used as a default selection of comparison signals for regression testing (and this is what we at Wolfram MathCore use for our own libraries).
14 |
15 | ## Revisions
16 | | Date | Description |
17 | | --- | --- |
18 | | 2019-03-27 | Henrik Tidefelt. Filling this document with initial content. |
19 | | 2019-10-01 | Henrik Tidefelt. Updates after demonstration of prototype. |
20 |
21 | ## Contributor License Agreement
22 | All authors of this MCP or their organizations have signed the "Modelica Contributor License Agreement".
23 |
24 | ## Rationale
25 | The structure of the plot annotations is currently being developed in a [separate document](predefined-plots.md), for later incorporation as changesets for the Modelica Specification document.
26 |
27 | ## Backwards Compatibility
28 | By only specifying new standard annotations, this MCP is fully backwards compatible.
29 |
30 | ## Tool Implementation
31 | This MCP is based on an existing solution using vendor specific annoations in Wolfram SystemModeler, and Wolfram MathCore is maintaining a rich collection of predefined plots for the MSL.
32 |
33 | Wolfram MathCore is willing to convert these vendor specific annotations to the form standardized by this MCP, and provide the plots for free to the MSL.
34 |
35 | ### Experience with Prototype
36 | See Summary above. The greatly enhanced user experience was observed even though the existing collection of predefined plots does not make use of captions. The use of captions have been tested with very nice results on a smaller number of plots.
37 |
38 | ## Required Patents
39 | To the best of our knowledge, there are no patents that would conflict with the incorporation of this MCP.
40 |
41 | ## References
42 | - Additional examples are provided in a separate repository: https://github.com/otronarp/MCP033Examples/tree/master/MCP0033
43 |
--------------------------------------------------------------------------------
/RationaleMCP/0033/example-figure.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/modelica/ModelicaSpecification/9ad2a9233cde7cc0a63d993681dc56bdc8f01e56/RationaleMCP/0033/example-figure.png
--------------------------------------------------------------------------------
/RationaleMCP/0033/predefined-plots.md:
--------------------------------------------------------------------------------
1 | # Structure of annotations
2 | The purpose of this document is to facilitate discussion around the actual structure and scope of standardized annotations for predefined plots.
3 |
4 | ## Figures in the class Documentation
5 | A class' `Documentation` annotation might look like this:
6 |
7 | ```
8 | annotation(
9 | Documentation(
10 | figures = {
11 | Figure(title = "Battery Voltage", identifier = "voltage", preferred = true, plots = {Plot(curves = {Curve(x = time, y = battery.p.v, legend = "Battery voltage")}, y=Axis(label = "Voltage"))}),
12 | Figure(title = "Battery Limit Controller", identifier = "limit", caption = "...", plots = {Plot(title = "Battery Limits", curves = {Curve(x = time, y = battery.LimitController.threshold, legend = "Threshold for terminating simulation"), Curve(x = time, y = battery.LimitController.u, legend = "Limit controller input signal"), Curve(x = time, y = battery.LimitController.y, legend = "Limit controller output signal")})}),
13 | Figure(title = "Load Current", identifier = "load", plots = {Plot(curves = {Curve(x = time, y = load.i, legend = "Load current")})})
14 | }
15 | )
16 | )
17 | ```
18 |
19 | Since the use of HTML is not supported in the predefined plots, introduction of `figure` in `Documentation` means that the suport for the `...` construct needs to be restricted to `info` and `revisions`.
20 |
21 | ## A figure
22 | As seen in the example above, the pseudo code type of `figures` is `Figure[:]`. Inserting some line breaks into one of the `Figure` objects, it looks like this:
23 | ```
24 | Figure(
25 | title = "Battery Limit Controller",
26 | caption = "Overshoot when using a PI-controller with anti-windup."
27 | identifier = "limit",
28 | plots = {
29 | Plot(
30 | title = "Battery Limits",
31 | identifier = "battery",
32 | curves = {
33 | Curve(x = time, y = battery.LimitController.threshold, legend = "Threshold for terminating simulation"),
34 | Curve(x = time, y = battery.LimitController.u, legend = "Limit controller input signal"),
35 | Curve(x = time, y = battery.LimitController.y, legend = "Limit controller output signal")
36 | }
37 | )
38 | }
39 | )
40 | ```
41 |
42 | Pseudo code definition of `Figure`:
43 | ```
44 | record Figure
45 | String title "Title meant for display";
46 | String identifier "Identifier meant for programmatic access";
47 | String group = "" "Name of plot group";
48 | Boolean preferred = false "Automatically display figure after simulation";
49 | Plot[:] plots "Plots";
50 | String caption "Figure caption";
51 | end Figure;
52 | ```
53 |
54 | Pseudo code definition of `Plot`:
55 | ```
56 | record Plot
57 | String title "Title meant for display";
58 | String identifier "Identifier meant for programmatic access";
59 | Curve[:] curves "Plot curves";
60 | Axis x "X axis properties";
61 | Axis y "Y axis properties";
62 | end Plot;
63 | ```
64 |
65 | The `title` of a `Figure` shall be non-empty and is mandatory, as every figure needs a title for presentation in contexts such as a list of figures, and as it is generally hard for tools to automatically generate a meaningful title. On the other hand, when the `title` of a `Plot` isn't provided, the tool produces a default, but the default is allowed to be empty. Providing the empty string as `title` of a `Plot` means that no title should be shown. The plot title is not to be confused with the plot _label_ which is never empty, see below.
66 |
67 | The `identifier` in `Figure` and `Plot` is optional, and is intended for programmatic access. An `identifier` must be unique within the class containing the `figures` annotation, without considering whether it belongs to `Figure` or `Plot`. As an example for `Figure`, a small extension to the Modelica URI scheme would make it possible to reference the plot from the class documentation. For `Plot`, this makes it possible to reference the plot in the figure caption, which becomes useful when the `Figure` contains more than one `Plot`.
68 |
69 | Every `Plot` has an automatically generated _label_ which is required to be shown as soon as at least one `Plot` in the `Figure` has an `identifier`. A tool is free to choose both labeling scheme (such as _a_, _b_, …, or _i_, _ii_, …) placement in the plot, and styling in the plot itself as well as in other contexts.
70 |
71 | When a `Figure` defines a non-empty `group`, it is used to organize figures similar to how `group` is used in the `Dialog` annotation. However, leaving `group` at the default of an empty string does not mean that a group will be created automatically, but that the figure resides outside of any group. The `group` is both the key used for grouping, and the name of the group for diaplay purposes.
72 |
73 | ## Plot curves
74 | The actual data to plot is specified in the `curves` of a `Plot`:
75 | ```
76 | record Curve
77 | expression x = time "X coordinate values";
78 | expression y "Y coordinate values";
79 | String legend "Legend";
80 | end Curve;
81 | ```
82 |
83 | The mandatory `x` and `y` expressions are currently restricted to be component references refering to a scalar variable or `time`.
84 |
85 | When `legend` isn't provided, the tool produces a default based on `x` and/or `y`. Providing the empty string as `legend` means that the curve shall be omitted from the plot legend.
86 |
87 | ## Axis properties
88 | Properties may be defined for each `Plot` axis:
89 | ```
90 | record Axis
91 | Real min "Axis lower bound";
92 | Real max "Axis upper bound";
93 | String unit "Unit of min and max";
94 | String label "Axis label";
95 | end Axis;
96 | ```
97 |
98 | When an axis bound isn't provided, the tool computes one automatically.
99 |
100 | The Modelica tool is responsible for showing the unit used for values at the axis tick marks, so the axis `label` shall not be used to convey this information.
101 |
102 | When an axis label isn't provided, the tool produces a default label. Providing the empty string as axis label means that no label should be shown.
103 |
104 | ## Variable replacements
105 | In most places where text is displayed (`title`, `caption`, `legend`, `label`), the final value of a result variable can be embedded by refering to the variable as `%{inertia1.w}`. This is similar to the `Text` graphical in 18.6.5.5 _Text_,.
106 |
107 | Note that expansion to the final value means that expansion is not restricted to parameters and constants, so that values to be shown in a caption can be determined during simulation.
108 |
109 | The percent character is encoded `%%`. Neither `%class` nor `%name` is supported in this context, as this information is expected to already be easily accessible (when applicable) in tool-specific ways. (Titles making use of `%class` or `%name` would then only lead to ugly duplication of this information.)
110 |
111 | ## Text markup in captions
112 | In addition to variable replacements, a very restricted form of text markup is used for the `caption`.
113 |
114 | ### Links
115 | Links take the form `%[]()`, where the `[]` part is optional. The `` can be in either of the following forms:
116 | - A URI, such as `https://github.com/modelica/ModelicaSpecification` or `modelica:///Modelica.Blocks`.
117 | - A `variable:`, where `` is a component reference such as `inertia1.w`.
118 | - A `plot:`, where `` is the identifier of a `Plot` in the current `Figure`.
119 |
120 | When `[]` is omitted, a Modelica tool is free to derive a default based on the ``.
121 |
122 | The styling of the link text and the link action is left for each Modelica tool to decide.
123 |
124 | For example, `%(inertia1.w)` could be displayed as the text `inertia1.w` formatted with upright monospaced font, and have a pop-up menu attached with menu items for plotting the variable, setting its start value, or investigating the equation system from which it is solved. On the other hand, `%[angular velocity](inertia1.w)` could be formatted in the same style as the surrounding text, except some non-intrusive visual clue about it being linked.
125 |
126 | ### Paragraph break
127 | A sequence of one or more newlines (encoded either literally or using the `\n` escape sequence) means a paragraph break. (A line break within a paragraph is not supported.)
128 |
--------------------------------------------------------------------------------
/RationaleMCP/0035/POT_Header.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/modelica/ModelicaSpecification/9ad2a9233cde7cc0a63d993681dc56bdc8f01e56/RationaleMCP/0035/POT_Header.png
--------------------------------------------------------------------------------
/RationaleMCP/0035/Readme.md:
--------------------------------------------------------------------------------
1 | # Modelica Change Proposal MCP-0035
2 | # Multilingual support of Modelica
3 | ## Authors: Anett Kloß, Gerd Kurzbach, Olaf Oelsner, Thomas Beutlich
4 |
5 | --
6 |
7 | # Summary
8 | Modelica currently supports only one language for description texts. This is usually English. In order to better support users from other language areas and to make Modelica libraries more attractive and easier to understand for them, it should be possible to provide translations of the texts in any language in a standardized form, so that tools can find, read and display them to the user in his or her preferred language.
9 | The definition of the interface to the translated texts is the subject of the MCP.
10 |
11 | In the discussion in [#302](https://github.com/modelica/ModelicaSpecification/issues/302) it was decided to provide the translation externally of the Modelica files using the [GNU gettext](https://www.gnu.org/software/gettext/) format. The use of this format in the Modelica context is described in the MCP.
12 |
13 | # Revisions
14 | | Date | Description |
15 | | ------------ | --- |
16 | | 2021-06-14 | Anett Kloß: Prepared document based on ticket #302 |
17 | | 2022-01-07 | Gerd Kurzbach: add SpecificationText.md, some reformulations, discussion of design choices added |
18 |
19 | # Contributor License Agreement
20 | All authors of this MCP or their organizations have signed the "Modelica Contributor License Agreement".
21 |
22 | # Rationale
23 | Why should this feature be included?
24 | * A better understanding of the libraries by users with different language background will make the libraries more attractive.
25 | * Support cases might occur less often, due to better understanding of the description.
26 | * A new translation is additionally a review of the current state and can result in a better quality of both language versions.
27 | * Users can even write their own translation, when having a template *.pot-File for the library.
28 |
29 | The use case for the proposal is the MSL 4.0.
30 | * POT-File of current MSL 4.0 library --> this translation template is provided and filled for the Hydraulics Pump.
31 | (*add pictures*)
32 |
33 | Proposed changes to the specification are described in SpecificationText.md. It consists of a new section **13.6 Multilingual Descriptions** which contains:
34 | * Where the translation files to be stored
35 | * How does a GNU gettext translation template for a library look like and which kind of descriptive texts shall be included?
36 | * Which strings should be translated:
37 |
38 | The precise updated text of the specification is part of this branch/pull-request: Yes.
39 |
40 | # Backwards Compatibility
41 | The proposal is backwards compatible. All multilingual text changes can be applied without effect at existing Modelica code.
42 | After the introduction of translation files for libraries, this files need to be adjusted with every library change which adds new commented parts or changes existing comments.
43 |
44 | # Tool Implementation
45 |
46 | ## Experience with Prototype
47 | ### Implementation steps
48 | #### 1. Read out a translation template file
49 | Create at first a translation template file \*.pot for a Modelica library. Means a (tool dependent) readout of all needed text strings into a *LibraryName*.pot-File. It contains:
50 | - a header which concludes all necessary information
51 | 
52 |
53 | - for all original strings entries with following structure:
54 | ```
55 | msgctxt "Hydraulics.Basics.TankOverflow"
56 | msgid "Volume Flow Port A"
57 | msgstr ""
58 | ```
59 |
60 | Where *msgctxt* contains the name of the Modelica Class and *msgid* contains the textstring which is situated in this name space and shall be translated. Please regard that if a *msgid* string (in this example "Volume Flow Port A") is given more than once in a namespace, all occurrences are translated with the same translation!
61 |
62 | It shall be mandatory to use for *msgctxt* the full name of a class:
63 | - so a specific translation depending on the content in this namespace is possible, as every textstring may differ depending on the context,
64 | - using the class makes it easier for the Modelica tool to copy and re-arrange models and packages without loosing the already existing language information.
65 |
66 | The following Modelica constructs shall be read out / translated:
67 | * description strings
68 | * strings in following annotations:
69 | * Text.string, Text.textString
70 | * missingInnerMessage, obsolete, unassignedMessage
71 | * Dialog.[group|tab]
72 | * Dialog.[load|save]Selector.[caption|filter]
73 | * Documentation.[info|revisions]
74 | * Figure.title, Plot.title, Curve.legend
75 |
76 | Having read out the file it just needs to be changed, if the library is changed (e.g. commented parts are added or changed or when having changed the Modelica name of the text strings containing element).
77 |
78 | #### 2. Translation of the template file into a language file
79 | Starting from the template file create a \*.po file for each needed language (e.g. german: *LibraryName*.de.po-File).
80 |
81 | Edit the *msgstr* with the translation in the wanted language (here for german: `` Hydraulics.de.po``) :
82 | ```
83 | msgctxt "Hydraulics.Basics.TankOverflow"
84 | msgid "Volume Flow Port A"
85 | msgstr "Volumenstrom an Anschluss A"
86 | ```
87 |
88 | Hereby no error shall occur if there is one comment not having a translation. In this case the not translated text (the content of *msgid*) shall be used.
89 | Again the file needs to be adjusted if there are changes at the library (e.g. commented parts are added or changed or when having changed the Modelica name of the text strings containing element).
90 |
91 | ---
92 | **Note:** One may use the tool POedit for the translation, as it can be coupled with commercial translation tools for a faster translation.
93 |
94 | ---
95 | #### 3. File storage
96 | Both files need to be situated in the language directory ``Resources\Language`` of the top-level library e.g.:
97 | ``C:\...\\\Resources\Language``
98 | #### 4. Read in the translation
99 | The tool dependent language setting enables the reading of the current needed *LibraryName*.*Language*.po-file.
100 |
101 | ### Tool implementation effort
102 | 1. Readout of any comment / annotation without loosing content and with handling of exceptions, e.g. ``/"`` in comments. This can e.g. be created by the command:
103 | ``xgettext --language=EmacsLisp --sort-output --extract-all --from-code=UTF-8 --output=TranslationTest.pot TranslationTest.mo``
104 | Certainly, the string extraction based on the EmacsLisp language can only be considered as proof of concept, since there is no Modelica language available in xgettext. It is recommended to create the POT file directly from the Modelica tool.
105 |
106 | 2. When reading in a library read corresponding the *LibraryName*.*Language*.po-file into an internal table and lookup the translated strings just before presenting them to the user.
107 |
108 | ## Discussion of the "One File per Library" design
109 | There is a design choice how to structure the files for translation information either
110 | * one file per library, or
111 | * one file per class.
112 |
113 | In this proposal the design "One file per library" is chosen, because it simplifies the handling of the translation data, the translation process and the generation of the template. The information of the header need to be stored only once.
114 |
115 | If after finishing a library one wants to translate them into another language, he can use the preferred tool and feed the file as a whole into it. After translating the strings, he can then save the file and the work is done.
116 |
117 |
118 | One file per class, possibly stored in a directory structure that corresponds to the class hierarchy, result in a large number of files, with each file having to be translated separately. While this has the advantage of allowing parallel translations, it can also lead to undesirably different translations of the same texts, as different people translate things differently.
119 |
120 | Also a Modelica tool only has to take care of one file per library. Normally, for performance reasons, the information from the files is stored internally in one big table anyway, so there is no need to split the information.
121 |
122 | Multiple files have an advantage when renaming or moving classes, then the files only need to be renamed. The keyword msgctxt can then be omitted. In the case of only one file this can be realized by a search and replace of the msgctext information, which is not too complicated. The use case of moving classes in a finished library does not occur so often, because then also the models which use them must be adapted.
123 |
124 |
125 | # Required Patents
126 | None.
127 | # References
128 | [GNU gettext](https://www.gnu.org/software/gettext/)
129 |
130 | [Poedit](https://poedit.net/) - useful editor
131 |
--------------------------------------------------------------------------------
/RationaleMCP/0035/SpecificationText.md:
--------------------------------------------------------------------------------
1 | # 13.6 Multilingual Descriptions
2 |
3 | [*Descriptive texts in a model or library are usually formulated in English. To support users who are not so familiar with this, a Modelica tool can support the translation of these texts into any language. This should be done using external files, so that no modification of the actual Modelica text is required.*]
4 |
5 | The files to support translation must be provided by the developer of the library. They must be stored in a subdirectory of the Resources directory of the library with the name `Language`.
6 |
7 | Two kind of files have to be provided:
8 | * a template file `.pot` (Portable Object Template).
9 | It contains all necessary information to translate all descriptions, but no translations. The pattern `` denotes the toplevel class name of the library.
10 | * one file for each supported language with the name `..po` (Portable Object). This file is a copy of the associated template file, but extended with the translations in the specified language. The pattern `` stands for the ISO 639-1 language code, e.g., de or sv.
11 |
12 | The files consist of a header and a body. All text strings are in double quotes and encoded with UTF-8 characters. Comments start with an `#` and are continued until the end of line. Spaces outside strings are ignored and used as separators. The detailed format of these files is described in [GNU gettext](https://www.gnu.org/software/gettext/manual/gettext.pdf).
13 |
14 | The header is marked with an empty msgid entry and looks like this:
15 | ```
16 | # SOME DESCRIPTIVE TITLE.
17 | # Copyright (C) YEAR THE PACKAGE'S COPYRIGHT HOLDER
18 | # This file is distributed under the same license as the PACKAGE package.
19 | # FIRST AUTHOR , YEAR.
20 | #
21 | #, fuzzy
22 | msgid ""
23 | msgstr ""
24 | "Project-Id-Version: PACKAGE VERSION\n"
25 | "Report-Msgid-Bugs-To: \n"
26 | "POT-Creation-Date: 2019-03-15 10:52+0100\n"
27 | "PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
28 | "Last-Translator: FULL NAME \n"
29 | "Language-Team: LANGUAGE \n"
30 | "Language: \n"
31 | "MIME-Version: 1.0\n"
32 | "Content-Type: text/plain; charset=UTF-8\n"
33 | "Content-Transfer-Encoding: 8bit\n"
34 | ```
35 | All general terms in the header should be replaced by specific information.
36 |
37 | In the body, directly following the header, for each descriptive text there is an entry of the form
38 | ```
39 | #: :
40 | msgctxt ""
41 | msgid ""
42 | msgstr ""
43 | ```
44 | Only the keywords `msgctxt`, `msgid` and `msgstr` are used.
45 |
46 | At first there can be an optional comment describing the location (file name and line number) of the text to translate. Multiple occurences of the same string can be listed here, separated by space.
47 |
48 | Then, the `` behind the keyword `msgctxt` is the full name of the Modelica class (e.g. `Modelica.Blocks.Math.Sin` ) where the text appears in. Short class definitions do not appear here. Texts in such classes (including their description string) belong to the enclosing full class definition.
49 |
50 | After the `msgid` keyword the text string which shall be translated follows. It should contain the original string from the Modelica text representation.
51 | Since in Modelica control sequences also start with a backslash and another backslash is used to use sequences literally or to hide double quotes, no change is required here.
52 | But Modelica allows strings to go over more than one line, gettext does not.
53 | Therefore, line breaks in Modelica must be encoded with "\n" for gettext.
54 |
55 | In order to avoid long lines Modelica strings may be split into consecutive strings at the line breaks, and the line breaks encoded with a "\n" at the end of each string, e.g.
56 | ```
57 | "A
58 | B"
59 | ```
60 | is converted to
61 | ```
62 | "A\n"
63 | "B"
64 | ```
65 | These strings are concatenated when read.
66 | [*Please regard that if a `msgid` string is given more than once in the same context, all occurrences are translated with the same (last) translation!*]
67 |
68 | The keyword `msgstr` is followed by the translation of `msgid`. With regard to control characters and line breaks, the same rules apply as for msgid.
69 | In the template file this string is empty by definition. If this is empty in a language specific file the contents of `msgid` may be used instead.
70 |
71 | The texts in following Modelica constructs should be translated:
72 | * description strings of component declarations and classes
73 | * strings in following annotations:
74 | * Text.string, Text.textString
75 | * missingInnerMessage, obsolete, unassignedMessage
76 | * Dialog.[group|tab]
77 | * Dialog.[load|save]Selector.[caption|filter]
78 | * Documentation.[info|revisions]
79 | * Figure.title, Plot.title, Curve.legend
80 |
81 | C-style and line comments are not translated.
82 |
83 | [*To support the translation of these strings a number of free and commercial tools exist in context of GNU gettext.
84 | A Modelica tool should provide a function to create the initial template file from an existing Modelica library.*]
85 |
--------------------------------------------------------------------------------
/RationaleMCP/DevelopmentProcess.md:
--------------------------------------------------------------------------------
1 | # Development process for Modelica Language
2 |
3 | The following describes the steps in the development process; who is involved and the expected decisions and results.
4 | The Modelica Association Project Modelica Language (MAP-Lang) decides on changing this process and in exceptional cases to deviate from it.
5 | The guiding principles of the development are [guiding principles](GuidingPrinciples.MD).
6 |
7 | This document document describes version 2.0.0 of the development process for the Modelica Language.
8 |
9 | # Changes of the specification document
10 |
11 | Anyone (not only MAP-Lang members) can create an issue for the Modelica Specification document, indicating that something is unclear,
12 | can be improved, or propose some extension.
13 |
14 | Based on the discussion that may lead to a proposed change of the specification document or the issue may be closed without any changes.
15 |
16 | It is also possible to directly propose the change (as a Pull Request) – unless the change is so major that it will require an MCP.
17 | Proposed changes will only be considered if the Contributor License Agreement is signed
18 | (existing Contributors that are MAP-Lang members are grandfathered in for the time being);
19 | by the proposer’s organization – or in some cases the proposer.
20 |
21 | Any changes of the specification document needs to be approved; the changes are handled as reviewed Pull Request on GitHub.
22 |
23 | The details for handling them depend on the category of the changes as described below:
24 | * Typos and similarly trivial changes, or incorporation of already decided changes:
25 | They should be documented and reviewed, by at least one trusted reviewer.
26 | If the change and/or the consequence of the change are considered by the reviewer to be non-trivial,
27 | the reviewer should escalate it to the next level.
28 | The case “already decided changes” indicate that sometimes a decision has been made without having the
29 | proposed exact change of the document; that actual (possibly non-trivial) change of the document then only requires a single reviewer.
30 | * Straightforward but non-trivial changes:
31 | These require a normal vote among MAP-Lang; either at a meeting or electronically during at least one working week.
32 | If the change is not straightforward, it should be escalated to the next level.
33 | * Larger changes (in terms of impact):
34 | Require a Modelica Change Proposal (MCP) with voting at various stages, as given below.
35 |
36 | 
37 |
38 | # MCP
39 |
40 | ## What is an MCP?
41 |
42 | An MCP is a Modelica Change Proposal.
43 |
44 | The final MCP is comprised of a proposed change of the specification text and an additional rationale-document,
45 | which needs to be ready for the MCP to enter the “Under Evaluation” stage as described below.
46 | "MCP" can refer both to the final MCP and the work on this proposal including drafts.
47 |
48 | The rationale-document should provide the following information:
49 | * Business case: why should this feature be included?
50 | What problems can be solved (in a better way) that cannot be solved (as easily) now?
51 | * A prototype implementation, simple test cases to profoundly illustrate the solution of the problem
52 | and to show that the language element scales well.
53 | * At least one description of an industry-relevant example to show that this MCP is able to solve a problem from industry,
54 | if relevant for the MCP.
55 |
56 | ## MCP Process
57 | The stages of the MCP process are:
58 | 1. In Preparation.
59 | In this stage, an initial idea is described in an informal way to interested potential collaborators (tool vendors and end-users) and to identify potential technical issues and their solutions.
60 | 1. In Development.
61 | Entering this stage requires a normal vote by MAP-Lang to assign a number and an initial working group,
62 | and the working group then works out the details in a correspondingly named branch of the specification.
63 | At the end of this process 3 reviewers, who are not part of the working group, and not all from the same organization
64 | shall go through the entire proposal.
65 | 1. Under Evaluation.
66 | The working group decides when to enter this stage, and must provide the 3 reviews.
67 | The MAP-leader will announce the date for the actual vote
68 | when entering this stage and it must start no sooner than 2 weeks after entering this stage,
69 | and the voting must last at least 4 weeks. No actual development on the MCP takes place during this stage.
70 | Typos and similar trivial changes can still be corrected during this stage – other issues can
71 | be noted and handled after the MCP is potentially accepted.
72 | 1. Accepted.
73 | If the vote accepts the MCP, the MCP can then be merged into the main document.
74 | The MCP is normally included in the specification as soon as possible,
75 | but if an MCP is evaluated close to a release of the specification document, the vote can be to include the MCP after that release.
76 | 1. The MCP has been fully incorporated into the specification and the MCP process itself terminated.
77 |
78 | 
79 |
80 | If the MCP is not accepted by the vote or has been inactive for at least one year; it can be closed.
81 |
82 | # Defining a new Modelica Language Release
83 |
84 | ## Ongoing development
85 |
86 | The current development of the Modelica Language specification is available online
87 | and tool vendors are encouraged to implement features when they are added to the development version of the language specification;
88 | it is recommended that tool vendors do not wait until the beta release but incorporate changes as early as possible.
89 | Tool vendors and others are also encouraged to report issues at the earliest possible time, noting
90 | that the development version is not yet released.
91 |
92 | ## Decision on scheduling a release
93 |
94 | A Modelica Language Specification release needs to be announced in advance, after a normal vote. That should include:
95 | * A version number.
96 | * A preliminary release schedule.
97 | * A preliminary list of features; possibly including MCPs that are not yet accepted.
98 | Only the version number and preliminary list of features is publicly announced.
99 |
100 | ## Release schedule
101 |
102 | The release schedule should include:
103 | * Time for beta release/feature-freeze; i.e. the last date for adding features (including MCPs).
104 | There might still be planned changes, but limited to clarifications and corrections.
105 | The vote for the beta-release will require a normal vote.
106 | * Time for publicly available release candidate(s).
107 | There should be no planned changes after this point, but if any flaws are found, they should ideally be corrected.
108 | The vote for accepting the release candidate will be a vote with a qualified majority.
109 | * Release date (assuming no major issue with release candidates).
110 | It may also include deadlines when issues must be reported to be considered for the release; such can be different for different changes.
111 |
112 | ## Release procedure
113 |
114 | The release procedure should ideally follow the schedule.
115 | All features have to be ready in time for beta-release, and all issues must be corrected before the release candidate is released.
116 | If an MCP is not accepted in accordance with the release schedule
117 | (because it is not completed in time or the vote for proposal “Under Evaluation” results in rejection),
118 | then the feature list or possibly the release schedule is updated.
119 | If not all known flaws are corrected before the planned release candidate then the release schedule should be updated.
120 | In exceptional cases, it may be necessary to plan to release a version with a known flaw
121 | (in case correcting that flaw turns out to be too complicated).
122 |
123 | ## Maintenance of released versions.
124 |
125 | After a version is released development will continue on the next version (possibly not yet named).
126 | The issue tracking system will include a list of found issues –
127 | and MAP-Lang may decide to release a maintenance version to correct these in the previous version;
128 | according to the same procedure – except that the beta release should be absent (as no features should be added).
129 |
130 | ## Version numbering
131 | Minor versions should (ideally) be backwards compatible (in the sense that previously legal models keep their behavior),
132 | and any cases of non-backward compatible changes listed.
133 |
134 | Historically in most cases, non-backwards compatibility have been due to new keywords and functions – but in some cases,
135 | the specified behavior changed to correct flaws.
136 |
137 | Maintenance releases (i.e., revised versions like 3.3r1, 3.2r1, 3.2r2) should only be for correcting flaws
138 | and clarifying behavior, and should thus neither contain MCPs nor introduce other non-backwards compatible changes except bugfixes.
139 |
140 | There are proposals for a stricter numbering of language specification versions giving a semantic meaning
141 | to "major", "minor", and "revisions" (and possibly changing the numbering systems and including pre-release versions as well);
142 | if accepted such proposals should be followed for future releases.
143 | Note that there are also proposals for stricter version numbering of libraries.
144 |
145 | ### Use of unreleased versions
146 |
147 | Pre-release and development versions are not formally released,
148 | and should in general not be used even if they follow some released version.
149 |
150 | However, if the trunk version of the Modelica Language Specification has accepted changes that clarify behavior
151 | or correct flaws, a tool may use the updated semantics.
152 |
153 | In general, tools should not use versions of the Modelica Language Specification that are not yet accepted by MAP-Lang;
154 | except when using them for clearly marked prototypes.
155 |
156 | # Forms of voting
157 |
158 | * Trusted review: Currently any member of MAP-Lang on GitHub, may review a change.
159 | We might restrict this to project leader and some specified persons in the future. The proposer must not self-review.
160 | * Normal vote: A vote at a meeting, where the issue is listed on the agenda;
161 | or an online vote announced and held during at least one week where members can e.g. use thumbs up/down to vote on GitHub.
162 | These require a simple majority of the votes (i.e. more than 50%), abstaining votes are not considered.
163 | * MCP acceptance vote: A special kind of normal online vote, that must be announced at least 2 weeks in advance
164 | and be open for at least 4 weeks.
165 | * Vote with qualified majority: A vote at a meeting or electronically as described in the project bylaws;
166 | that has a stricter requirement for the number of votes in favor as described in the project bylaws.
167 | * Poll: Any voting – in particular informal votes to indicate interest in different topics.
168 |
169 |
170 |
--------------------------------------------------------------------------------
/RationaleMCP/GuidingPrinciples.MD:
--------------------------------------------------------------------------------
1 | Guiding Principles of the Modelica Language Development
2 | --
3 |
4 | The overall goal of the development process is guided by the following fundamental tenets that all aim to
5 | facilitate widespread adoption of the standard and promoting modeling of cyber-physical systems:
6 |
7 | 1. Compatibility: The Modelica Language Standard shall be internally consistent and complete.
8 | The Standard documents shall be an enabler for convenient and precise definition of cyber-physical systems.
9 |
10 | 2. Simplicity: The Modelica Language Standard shall stay as simple as possible.
11 |
12 | 3. Stability: Backwards compatibility of future versions of the Modelica Language Standard shall be maintained whenever possible.
13 |
14 | 4. Neutrality: The Modelica Language shall be neutral with respect to tools, technologies (e.g. processors, compilers, OS,
15 | file system access, solvers, real-time capability, ...) and languages.
16 |
17 | 5. Transparency: End users and tool vendors shall be informed about the progress of standardization as early as possible.
18 |
--------------------------------------------------------------------------------
/RationaleMCP/Hints.md:
--------------------------------------------------------------------------------
1 | Hints for generating a release.
2 |
3 | Currently there are no automated procedures for generating the revision-history.
4 |
5 | For the MCPs it is good to list additional pull requests considered, they can be found in GitHub's Pull Request list by searching for:
6 | ```
7 | -base:master -base:maint/ is:merged
8 | ```
9 | This can either be combined with limiting it to one MCP `label:MCP0035` or excluding some (earlier and later) MCPs `-label:MCP0031 -label:MCP0033`.
10 | Additionally it is good to list all pull request merged into the main branch after the latest release:
11 | ```
12 | base:master merged:>=2020-12-31
13 | ```
14 |
--------------------------------------------------------------------------------
/RationaleMCP/MCP-StateMachine-Figure.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/modelica/ModelicaSpecification/9ad2a9233cde7cc0a63d993681dc56bdc8f01e56/RationaleMCP/MCP-StateMachine-Figure.png
--------------------------------------------------------------------------------
/RationaleMCP/MCPTemplate.MD:
--------------------------------------------------------------------------------
1 | Modelica Change Proposal MCP-00XX
2 | Short Description
3 | Authors
4 | (In Development)
5 | --
6 |
7 | # Summary
8 | Short description of the motivation and central idea of the proposal in 5 to 10 lines.
9 |
10 | # Revisions
11 | | Date | Description |
12 | | --- | --- |
13 | | 2015-Dec-01 | Stefan Vorkoetter. Prepared document based on ticket #1234 |
14 | | 2018-12-13 | Hans Olsson. Converted from HTML to GFM and removed spec-change document. |
15 |
16 | # Contributor License Agreement
17 | All authors of this MCP or their organizations have signed the "Modelica Contributor License Agreement".
18 |
19 | # Rationale
20 | Sketch of the proposal (especially with examples) and an explanation of the business case: Why should this feature be included? What problems can be solved (better) that cannot be solved (as easily) now?
21 | Provide at minimum two use cases for your proposal that show how it is applied. For each use case state how it could be implemented by current Modelica at best and why the current Modelica does not suffice for this application.
22 | Proposed Changes in Specification
23 |
24 | The precise updated text of the specification is part of this branch/pull-request.
25 |
26 | # Backwards Compatibility
27 | It has to be analyzed whether the proposal is backwards compatibile. If any possible, this should be the case. Even if it is backwards compatible, issues should be listed and analyzed that may cause problems.
28 |
29 | List (preferably existing) examples that would be corrupted by proposed changes in specification.
30 |
31 | Show what can be done about these cases. Provide a concept for a conversion script or any other solution.
32 |
33 | # Tool Implementation
34 |
35 | ## Experience with Prototype
36 | The prototype implementation has to be sketched and the experience gained with the prototype, especially the implementation effort. Furthermore, simple test cases have to be provided to profoundly illustrate the solution of the problem, and at least one description of an industry-size example to prove scalability of the solution.
37 |
38 | # Required Patents
39 | At best of your knowledge state any patents that would be required for implementation of this proposal.
40 | # References
41 |
--------------------------------------------------------------------------------
/RationaleMCP/MCP_Template_Overview.dotx:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/modelica/ModelicaSpecification/9ad2a9233cde7cc0a63d993681dc56bdc8f01e56/RationaleMCP/MCP_Template_Overview.dotx
--------------------------------------------------------------------------------
/RationaleMCP/NewRelease.md:
--------------------------------------------------------------------------------
1 | After a new release is accepted the following steps are currently suggested.
2 |
3 | 1. Update https://github.com/modelica/ModelicaSpecification/blob/master/README.md with new date. This should automatically update specification.modelica.org
4 | 1. Update modelica.org/documents and modelica.org/modelicalanguage
5 | 1. Announce in Modelica-design mailing list and similar channels.
6 |
--------------------------------------------------------------------------------
/RationaleMCP/ReadMe.md:
--------------------------------------------------------------------------------
1 | # MCP Rationale
2 | This directory should contain the rationale behind Modelica Change Proposals, MCPs,
3 | (and possibly rationale behind other decisions as well).
4 |
5 | Each MCP should use a separate sub-directory based on the MCP-number.
6 |
7 | ## Template for MCPs
8 |
9 | A template for the rationale of the MCP is found as either [Markdown](MCPTemplate.MD) or [Word](MCP_Template_Overview.dotx).
10 |
11 | ## Workflow
12 |
13 | The workflow for all changes (including MCPs), and releases is described as part of the [Development Process](DevelopmentProcess.md).
14 | After a release is accepted, follow the [check-list for a new release](NewRelease.md).
15 |
16 | New MCP should be added to the following list - on the main branch to keep track of them,
17 | but the rest of the development on a branch/pull-request before being accepted.
18 |
19 | ## List of existing MCPs
20 |
21 | |Status|Number|Name|Branch|Issue|
22 | |------|------|----|----|-|
23 | |Active|0039|Licensing and encryption|[MCP/0039](https://github.com/modelica/ModelicaSpecification/tree/MCP/0039/RationaleMCP/0039)|https://github.com/modelica/ModelicaSpecification/pull/2931|
24 | |Active|0038|Initialization of Clocked Partitions|[MCP/0038](https://github.com/modelica/ModelicaSpecification/tree/MCP/0038/RationaleMCP/0038)||
25 | |Active|0037|Generalized Modelica URIs|[MCP/0037](https://github.com/modelica/ModelicaSpecification/tree/MCP/0037/RationaleMCP/0037)|https://github.com/modelica/ModelicaSpecification/pull/2663|
26 | |Active|0036|Setting states|[MCP/0036](https://github.com/modelica/ModelicaSpecification/tree/MCP/0036/RationaleMCP/0036)|https://github.com/modelica/ModelicaSpecification/pull/3164|
27 | |Accepted in [3.6](https://github.com/modelica/ModelicaSpecification/releases/tag/v3.6)|0035|Multilingual support of Modelica|[MCP/0035](https://github.com/modelica/ModelicaSpecification/tree/MCP/0035/RationaleMCP/0035)|https://github.com/modelica/ModelicaSpecification/pull/2956|
28 | |Active|0034|Ternary|[MCP/0034](https://github.com/modelica/ModelicaSpecification/tree/MCP/0034/RationaleMCP/0034)|https://github.com/modelica/ModelicaSpecification/pull/2477|
29 | |Added in [3.5](https://github.com/modelica/ModelicaSpecification/releases/tag/v3.5)|0033|Annotations for Predefined Plots|[MCP/0033](https://github.com/modelica/ModelicaSpecification/tree/MCP/0033/RationaleMCP/0033)||
30 | |Accepted in [3.6](https://github.com/modelica/ModelicaSpecification/releases/tag/v3.6)|0032|Selective Model Extension|[MCP/0032](https://github.com/modelica/ModelicaSpecification/tree/MCP/0032/RationaleMCP/0032)|https://github.com/modelica/ModelicaSpecification/pull/3166|
31 | |Active|0031|Base Modelica and MLS modularization|[MCP/0031](https://github.com/modelica/ModelicaSpecification/tree/MCP/0031/RationaleMCP/0031)|
32 | |On hold|0030|IsClocked Operator||[#2238](https://github.com/modelica/ModelicaSpecification/issues/2238)|
33 | |Active|0029|License Export|[MCP/0029](https://github.com/modelica/ModelicaSpecification/tree/MCP/0029/RationaleMCP/0029)|https://github.com/modelica/ModelicaSpecification/pull/2900|
34 | |Added in [3.4](https://github.com/modelica/ModelicaSpecification/releases/tag/v3.4)|0028|Record Derivatives mixing Real and non-Real||[#2137](https://github.com/modelica/ModelicaSpecification/issues/2137)|
35 | |Active|0027|Unit checking|[MCP/0027](https://github.com/modelica/ModelicaSpecification/tree/MCP/0027/RationaleMCP/0027)|[#3255](https://github.com/modelica/ModelicaSpecification/issues/3255) ([#2127](https://github.com/modelica/ModelicaSpecification/issues/2127))|
36 | |Added in [3.4](https://github.com/modelica/ModelicaSpecification/releases/tag/v3.4)|0026|Arc-only Ellipse||[#2045](https://github.com/modelica/ModelicaSpecification/issues/2045)|
37 | |On hold|0025|Functions with input output||[#2012](https://github.com/modelica/ModelicaSpecification/issues/2012)|
38 | |Added in [3.4](https://github.com/modelica/ModelicaSpecification/releases/tag/v3.4)|0024|Initialization of Clocked States||[#2007](https://github.com/modelica/ModelicaSpecification/issues/2007)|
39 | |Added in [3.4](https://github.com/modelica/ModelicaSpecification/releases/tag/v3.4)|0023|Model to Record||[#1953](https://github.com/modelica/ModelicaSpecification/issues/1953)|
40 | |Added in [3.4](https://github.com/modelica/ModelicaSpecification/releases/tag/v3.4)|0022|Integer to Enumeration||[#1842](https://github.com/modelica/ModelicaSpecification/issues/1842)|
41 | |Active|0021|Component iterators|[MCP/0021](https://github.com/modelica/ModelicaSpecification/tree/MCP/0021/RationaleMCP/0021)||
42 | |Added in [3.4](https://github.com/modelica/ModelicaSpecification/releases/tag/v3.4)|0020|Model as Arguments to Functions|||
43 | |Added in [3.4](https://github.com/modelica/ModelicaSpecification/releases/tag/v3.4)|0019|Improvement of Flattening Description||[#1829](https://github.com/modelica/ModelicaSpecification/issues/1829)|
44 | |Added for [3.5](https://github.com/modelica/ModelicaSpecification/releases/tag/v3.5)|0018|Change specification format|||
45 | |Active|0017|Portable import of FMUs|||
46 | |Active|0016|Semantic Versions|||
47 | |Active|0015|Language Version Header|[MCP/0015](https://github.com/modelica/ModelicaSpecification/tree/MCP/0015/RationaleMCP/0015)||
48 | |Added in [3.4](https://github.com/modelica/ModelicaSpecification/releases/tag/v3.4)|0014|Conversion||[#1622](https://github.com/modelica/ModelicaSpecification/issues/1622)|
49 | |On hold|0013|Introducing polymorphic functions||
50 | |Active|0012|Calling blocks as functions|[MCP/0012](https://github.com/modelica/ModelicaSpecification/tree/MCP/0012/RationaleMCP/0012)||
51 | |On hold|0011|Allow user-defined functions in reductions|||
52 | |On hold|0010|Adding guards to reductions|||
53 | |Accepted in [3.6](https://github.com/modelica/ModelicaSpecification/releases/tag/v3.6)|0009|Undefined modification|[MCP/0009](https://github.com/modelica/ModelicaSpecification/tree/MCP/0009/RationaleMCP/0009)|https://github.com/modelica/ModelicaSpecification/pull/3167|
54 | |On hold|0008|Custom annotations|||
55 | |On hold|0007|Match expressions|||
56 | |On hold|0006|Atomic blocks|||
57 | |On hold|0005|Equivalent parameters|||
58 | |On hold|0004|Handling uncertainties (need to consider MCP0008)|||
59 | |On hold|0003|User defined annotations (superseded by MCP0008)|||
60 | |On hold|0002|Improved class generation|||
61 | |On hold|0001|Improved parametrization|||
62 |
63 | Note that the documents for older issues (especially the ones on hold) have not been transferred to GitHub, but are found on an older svn-server.
64 |
--------------------------------------------------------------------------------
/RationaleMCP/Workflow1.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/modelica/ModelicaSpecification/9ad2a9233cde7cc0a63d993681dc56bdc8f01e56/RationaleMCP/Workflow1.png
--------------------------------------------------------------------------------
/RationaleMCP/Workflow1.pptx:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/modelica/ModelicaSpecification/9ad2a9233cde7cc0a63d993681dc56bdc8f01e56/RationaleMCP/Workflow1.pptx
--------------------------------------------------------------------------------
/RationaleMCP/Workflow2.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/modelica/ModelicaSpecification/9ad2a9233cde7cc0a63d993681dc56bdc8f01e56/RationaleMCP/Workflow2.png
--------------------------------------------------------------------------------
/chapters/abstract.tex:
--------------------------------------------------------------------------------
1 | % Can't use the 'abstract' environment as long as LaTeXML puts the abstract before the title page, see LaTeXML issue:
2 | % - https://github.com/brucemiller/LaTeXML/issues/1395 (fixed on master 2022-12-10)
3 | \begin{center}
4 | \large\bfseries\sffamily
5 | \abstractname
6 | \end{center}
7 |
8 | This document defines the Modelica\footnote{%
9 | \firstuse{Modelica} is a registered trademark of the Modelica Association.
10 | }
11 | language, version~\mlsversion, which is developed by the Modelica Association, a non-profit organization with seat in Linköping, Sweden.
12 | Modelica is a freely available, object-oriented language for modeling of large, complex, and heterogeneous systems.
13 | It is suited for multi-domain modeling, for example, mechatronic models in robotics, automotive and aerospace applications involving mechanical, electrical, hydraulic control and state machine subsystems, process oriented applications and generation and distribution of electric power.
14 | Models in Modelica are mathematically described by differential, algebraic and discrete equations.
15 | No particular variable needs to be solved for manually.
16 | A Modelica tool will have enough information to decide that automatically.
17 | Modelica is designed such that available, specialized algorithms can be utilized to enable efficient handling of large models having more than one hundred thousand equations.
18 | Modelica is suited and used for hardware-in-the-loop simulations and for embedded control systems.
19 | More information is available at \url{https://modelica.org}.
20 |
--------------------------------------------------------------------------------
/chapters/copyright.tex:
--------------------------------------------------------------------------------
1 | Copyright \textcopyright{} 1998-2023, Modelica Association (\url{https://modelica.org})
2 |
3 | All rights reserved.
4 | Reproduction or use of editorial or pictorial content is permitted, i.e., this document can be freely distributed especially electronically, provided the copyright notice and these conditions are retained.
5 | No patent liability is assumed with respect to the use of information contained herein.
6 | While every precaution has been taken in the preparation of this document no responsibility for errors or omissions is assumed.
7 |
8 | The contributors to this and to previous versions of this document are listed in \cref{modelica-revision-history}.
9 |
--------------------------------------------------------------------------------
/chapters/dae.tex:
--------------------------------------------------------------------------------
1 | \chapter{Modelica DAE Representation}\label{modelica-dae-representation}
2 |
3 | In this appendix, the mapping of a Modelica model into an appropriate mathematical description form is discussed.
4 |
5 | In a first step, a Modelica translator transforms a hierarchical Modelica simulation model into a ``flat'' set of Modelica ``statements'', consisting of the equation and algorithm sections of all used components by:
6 | \begin{itemize}
7 | \item
8 | Expanding all class definitions (flattening the inheritance tree) and adding the equations and assignment statements of the expanded classes for every instance of the model.
9 | \item
10 | Replacing all \lstinline!connect!-equations by the corresponding equations of the connection set (see \cref{generation-of-connection-equations}).
11 | \item
12 | Mapping all algorithm sections to equation sets.
13 | \item
14 | Mapping all \lstinline!when!-clauses to equation sets (see \cref{when-equations}).
15 | \end{itemize}
16 |
17 | As a result of this transformation process, a set of equations is obtained consisting of differential, algebraic and discrete equations of the following form where ($v := \lbrack p; t; \dot{x}; x; y; z; m; \text{\lstinline!pre!}(z); \text{\lstinline!pre!}(m)\rbrack$):
18 | \begin{subequations}
19 | \label{eq:hydrid-dae}
20 | \begin{equation}\label{eq:dae}
21 | 0 = f_{\mathrm{x}}(v, c)
22 | \end{equation}
23 | \begin{equation}\label{eq:dae-discrete-real}
24 | z =
25 | \begin{cases}
26 | f_{\mathrm{z}}(v, c) & \text{at events} \\
27 | \text{\lstinline!pre!}(z) & \text{otherwise}
28 | \end{cases}
29 | \end{equation}
30 | \begin{equation}\label{eq:dae-discrete-valued}
31 | m := f_{\mathrm{m}}(v, c)
32 | \end{equation}
33 | \begin{equation}\label{eq:crossing}
34 | c := f_{\mathrm{c}}(\mathit{relation}(v))
35 | \end{equation}
36 | \end{subequations}
37 | and where
38 | \begin{itemize}
39 | \item
40 | $p$:
41 | Modelica variables declared as \lstinline!parameter! or \lstinline!constant!, i.e., variables without any time-dependency.
42 |
43 | \item
44 | $t$:
45 | Modelica variable \lstinline!time!, the independent (real) variable.
46 |
47 | \item
48 | $x(t)$:
49 | Modelica variables of type \lstinline!Real!, appearing differentiated.
50 |
51 | \item
52 | $y(t)$:
53 | Continuous-time modelica variables of type \lstinline!Real! that do not appear differentiated (= algebraic variables).
54 |
55 | \item
56 | $z(t_{\mathrm{e}})$:
57 | Discrete-time modelica variables of type \lstinline!Real!.
58 | These variables change their value only at event instants $t_{\mathrm{e}}$.
59 | \lstinline!pre(z)! are the values of $z$ immediately before the current event occurred.
60 |
61 | \item
62 | $m(t_{\mathrm{e}})$:
63 | Modelica variables of discrete-valued types (\lstinline!Boolean!, \lstinline!Integer!, etc) which are unknown.
64 | These variables change their value only at event instants $t_{\mathrm{e}}$.
65 | \lstinline!pre(m)! are the values of $m$ immediately before the current event occurred.
66 |
67 | \begin{nonnormative}
68 | For equations in \lstinline!when!-clauses with discrete-valued variables on the left-hand side, the form \eqref{eq:dae-discrete-valued} relies upon the conceptual rewriting of equations described in \cref{defining-when-equations-by-if-expressions-in-equality-equations}.
69 | \end{nonnormative}
70 |
71 | \item
72 | $c(t_{\mathrm{e}})$:
73 | The conditions of all \lstinline!if!-expressions generated including \lstinline!when!-clauses after conversion, see \cref{when-equations}).
74 |
75 | \item
76 | $\mathit{relation}(v)$:
77 | A relation containing variables $v_{i}$, e.g., $v_{1} > v_{2}$, $v_{3} \geq 0$.
78 | \end{itemize}
79 |
80 | For simplicity, the special cases of \lstinline!noEvent! and \lstinline!reinit! are not contained in the equations above and are not discussed below.
81 |
82 | The key difference between the two groups of discrete-time variables $z$ and and $m$ here is how they are determined.
83 | The interpretation of the solved form of \eqref{eq:dae-discrete-valued} is that given values for everything else, there is a closed-form solution for $m$ in the form of a sequence of assignments to each of the variables of $m$ in turn -- there must be no cyclic dependencies between the equations used to solve for $m$.
84 | Further, each of the original model equations behind \eqref{eq:dae-discrete-valued} must be given in almost solved form:
85 | \begin{itemize}
86 | \item
87 | Non-\lstinline!Integer! equations at most requiring flipping sides of the equation to obtain the used assignment form.
88 | \item
89 | For \lstinline!Integer! equations the solved variable must appear uniquely as a term (without any multiplicative factor) on either side of the equation, at most requiring addition or subtraction of other terms in the equation to obtain the used assignment form.
90 | \end{itemize}
91 | The interpretation of the non-solved form of \eqref{eq:dae-discrete-real} at events, on the other hand, is that at events, the discrete-time \lstinline!Real! variables $z$ are solved together with the continuous-time variables using \eqref{eq:dae} and \eqref{eq:dae-discrete-real}.
92 |
93 | \begin{example}
94 | The following model demonstrates that \cref{eq:dae-discrete-real} does not imply that all discrete-time \lstinline!Real! variables are given by equations in solved form, as also the discrete-time \lstinline!Real! variables are included in $z$:
95 | \begin{lstlisting}[language=modelica]
96 | model M
97 | discrete Real x(start = 1.0, fixed = true);
98 | equation
99 | when sample(1.0, 1.0) then
100 | x = 3 * pre(x) - x^2; // Valid equation for discrete-time Real variable x.
101 | end when;
102 | end M;
103 | \end{lstlisting}
104 |
105 | Another way that a discrete-time \lstinline!Real! variable can end up becoming determined by a nonlinear equation is through coupling with other variables.
106 | \begin{lstlisting}[language=modelica]
107 | model M
108 | discrete Real x(start = 1.0, fixed = true);
109 | discrete Real y(start = 0.0, fixed = true);
110 | equation
111 | when sample(1.0, 1.0) then
112 | y = x ^ 2 + 2 * exp(-time);
113 | x = 3 * pre(x) - y; // OK, forming nonlinear equation system with y.
114 | end when;
115 | end M;
116 | \end{lstlisting}
117 | \end{example}
118 |
119 | \begin{example}
120 | The following model is illegal since there is no equation in solved form that can be used in \eqref{eq:dae-discrete-valued} to solve for the discrete-valued variable \lstinline!y!:
121 | \begin{lstlisting}[language=modelica]
122 | model M
123 | Boolean x;
124 | Boolean y;
125 | equation
126 | x = time >= 1.0;
127 | not y = x; /* Equation in solved form, but not with respect to y. */
128 | end M;
129 | \end{lstlisting}
130 | \end{example}
131 |
132 | The generated set of equations is used for simulation and other analysis activities.
133 | Simulation proceeds as follows.
134 | First, initialization takes place, during which initial values for the states $x$ are found, \cref{initialization-initial-equation-and-initial-algorithm}.
135 | Given those initial values the equations are simulated forward in time; this is the transient analysis.
136 | The equations define a DAE\index{DAE} (Differential Algebraic Equations) which may have discontinuities, a variable structure and/or which are controlled by a discrete-event system.
137 | Such types of systems are called \firstuse[hybrid DAE]{hybrid DAEs}.
138 | After initialization, simulation proceeds with transient analysis in the following way:
139 | \begin{enumerate}
140 | \item\label{perform-simulation-integrate}
141 | The DAE \eqref{eq:dae} is solved by a numerical integration method.
142 | In this phase the conditions $c$ of the \lstinline!if!- and \lstinline!when!-clauses, as well as the discrete-time variables $z$ and $m$ are kept constant.
143 | Therefore, \eqref{eq:dae} is a continuous function of continuous variables and the most basic requirement of numerical integrators is fulfilled.
144 | \item
145 | During integration, all relations from \eqref{eq:crossing} are monitored.
146 | If one of the relations changes its value an event is triggered, i.e., the exact time instant of the change is determined and the integration is halted.
147 | As discussed in \cref{events-and-synchronization}, relations which depend only on time are usually treated in a special way, because this allows determining the time instant of the next event in advance.
148 | \item
149 | At an event instant, \eqref{eq:hydrid-dae} is a mixed set of algebraic equations which is solved for the \lstinline!Real!, \lstinline!Boolean! and \lstinline!Integer! unknowns.
150 | \item
151 | After an event is processed, the integration is restarted at phase~\ref{perform-simulation-integrate}.
152 | \end{enumerate}
153 |
154 | Note, that both the values of the conditions $c$ as well as the values of $z$ and $m$ (all discrete-time \lstinline!Real!, \lstinline!Boolean! and \lstinline!Integer! variables) are only changed at an event instant and that these variables remain constant during continuous integration.
155 | At every event instant, new values of the discrete-time variables $z$ and $m$, as well as of new initial values for the states $x$, are determined.
156 | The change of discrete-time variables may characterize a new structure of a DAE where elements of the state vector $x$ are \emph{disabled}.
157 | In other words, the number of state variables, algebraic variables and residue equations of a DAE may change at event instants by disabling the appropriate part of the DAE.
158 | For clarity of the equations, this is not explicitly shown by an additional index in \eqref{eq:hydrid-dae}.
159 |
160 | At an event instant, including the initial event, the model equations are reinitialized according to the following iteration procedure:
161 | \begin{lstlisting}[language=modelica]
162 | known variables: x, t, p
163 | unkown variables: dx/dt, y, z, m, pre(z), pre(m), c
164 |
165 | // pre(z) = value of z before event occured
166 | // pre(m) = value of m before event occured
167 | loop
168 | solve (1) for the unknowns, with pre(z) and pre(m) fixed
169 | if z == pre(z) and m == pre(m) then break
170 | pre(z) := z
171 | pre(m) := m
172 | end loop
173 | \end{lstlisting}
174 |
175 | Clocked variables are handled similarly as $z$ and $m$ (depending on type), but using \lstinline!previous! instead of \lstinline!pre! and only solved in the first event iteration.
176 |
177 | Solving \eqref{eq:hydrid-dae} for the unknowns is non-trivial, because this set of equations contains not only \lstinline!Real!, but also discrete-valued unknowns.
178 | Usually, in a first step these equations are sorted and in many cases the discrete-valued unknowns $m$ can be just computed by a forward evaluation sequence.
179 | In some cases, there remain systems of equations involving $m$ due to cyclic dependencies with $y$ and $z$ (e.g., for ideal diodes, Coulomb friction elements), and specialized algorithms have to be used to solve them.
180 |
181 | Due to the construction of the equations by \emph{flattening} a Modelica model, the hybrid DAE \eqref{eq:hydrid-dae} contains a huge number of sparse equations.
182 | Therefore, direct simulation of \eqref{eq:hydrid-dae} requires sparse matrix methods.
183 | However, solving this initial set of equations directly with a numerical method is both unreliable and inefficient.
184 | One reason is that many Modelica models, like the mechanical ones, have a DAE index of 2 or 3, i.e., the overall number of states of the model is less than the sum of the states of the sub-components.
185 | In such a case, every direct numerical method has the difficulty that the numerical condition becomes worse, if the integrator step size is reduced and that a step size of zero leads to a singularity.
186 | Another problem is the handling of idealized elements, such as ideal diodes or Coulomb friction.
187 | These elements lead to mixed systems of equations having both \lstinline!Real! and \lstinline!Boolean! unknowns.
188 | Specialized algorithms are needed to solve such systems.
189 |
190 | To summarize, symbolic transformation techniques are needed to transform \eqref{eq:hydrid-dae} into a set of equations which can be numerically solved reliably.
191 | Most important, the algorithm of Pantelides should to be applied to differentiate certain parts of the equations in order to reduce the index.
192 | Note, that also explicit integration methods, such as Runge-Kutta algorithms, can be used to solve \eqref{eq:dae}, after the index of \eqref{eq:dae} has been reduced by the Pantelides algorithm: During continuous integration, the integrator provides $x$ and $t$.
193 | Then, \eqref{eq:dae} is a linear or nonlinear system of equations to compute the algebraic variables $y$ and the state derivatives $\udfrac{x}{t}$ and the model returns $\udfrac{x}{t}$ to the integrator by solving these systems of equations.
194 | Often, \eqref{eq:dae} is just a linear system of equations in these unknowns, so that the solution is straightforward.
195 | This procedure is especially useful for real-time simulation where usually explicit one-step methods are used.
196 |
--------------------------------------------------------------------------------
/chapters/introduction.tex:
--------------------------------------------------------------------------------
1 | \chapter{Introduction}\label{introduction1}
2 |
3 | \section{Overview of Modelica}\label{overview-of-modelica}
4 |
5 | Modelica is a language for modeling of cyber-physical systems, supporting acausal connection of components governed by mathematical equations to facilitate modeling from first principles.
6 | It provides object-oriented constructs that facilitate reuse of models, and can be used conveniently for modeling complex systems containing, e.g., mechanical, electrical, electronic, magnetic, hydraulic, thermal, control, electric power or process-oriented subcomponents.
7 |
8 | \section{Scope of the Specification}\label{scope-of-the-specification}
9 |
10 | The semantics of the Modelica language is specified by means of a set of rules for translating any class described in the Modelica language to a flat Modelica structure.
11 | The semantic specification should be read together with the Modelica grammar.
12 |
13 | A class (of specialized class \lstinline!model! or \lstinline!block!) intended to be simulated on its own is called a \firstuse{simulation model}.
14 |
15 | The flat Modelica structure is also defined for other cases than simulation models; including functions (can be used to provide algorithmic contents), packages (used as a structuring mechanism), and partial models (used as base-models).
16 | This allows correctness to be verified for those classes, before using them to build the simulation model.
17 |
18 | There are specific semantic restrictions for a simulation model to ensure that the model is complete; they allow its flat Modelica structure to be further transformed into a set of differential, algebraic and discrete equations (= flat hybrid DAE).
19 | Note that satisfying the semantic restrictions does not guarantee that the model can be initialized from the initial conditions and simulated.
20 |
21 | Modelica was designed to facilitate symbolic transformations of models, especially by mapping basically every Modelica language construct to equations in the flat Modelica structure.
22 | Many Modelica models, especially in the associated Modelica Standard Library, are higher index systems, and can only be reasonably simulated if symbolic index reduction is performed, i.e., equations are differentiated and appropriate variables are selected as states, so that the resulting system of equations can be transformed to state space form (at least locally numerically), i.e., a hybrid DAE of index zero.
23 | In order to allow this structural analysis, a tool may reject simulating a model if parameters cannot be evaluated during translation -- due to calls of external functions or initial equations/initial algorithms for \lstinline!fixed = false! parameters.
24 | Accepting such models is a quality of implementation issue.
25 | The Modelica specification does not define how to simulate a model.
26 | However, it defines a set of equations that the simulation result should satisfy as well as possible.
27 |
28 | The key issues of the translation (or flattening) are:
29 | \begin{itemize}
30 | \item
31 | Expansion of inherited base classes.
32 | \item
33 | Parameterization of base classes, local classes and components.
34 | \item
35 | Generation of connection equations from \lstinline!connect!-equations.
36 | \end{itemize}
37 |
38 | The flat hybrid DAE form consists of:
39 | \begin{itemize}
40 | \item
41 | Declarations of variables with the appropriate basic types, prefixes and attributes, such as \lstinline!parameter Real v = 5!.
42 | \item
43 | Equations from equation sections.
44 | \item
45 | Function invocations where an invocation is treated as a set of equations which involves all input and all result variables (number of equations = number of basic result variables).
46 | \item
47 | Algorithm sections where every section is treated as a set of equations which involves the variables occurring in the algorithm section (number of equations = number of different assigned variables).
48 | \item
49 | The \lstinline!when!-clauses where every \lstinline!when!-clause is treated as a set of conditionally evaluated equations, which are functions of the variables occurring in the clause (number of equations = number of different assigned variables).
50 | \end{itemize}
51 |
52 | Therefore, a flat hybrid DAE is seen as a set of equations where some of the equations are only conditionally evaluated.
53 | Initial setup of the model is specified using \lstinline!start!-attributes and equations that hold only during initialization.
54 |
55 | A Modelica class may also contain annotations, i.e., formal comments, which specify graphical representations of the class (icon and diagram), documentation text for the class, and version information.
56 |
57 | \section{Some Definitions}\label{some-definitions}
58 |
59 | Explanations of many terms can be found using the document index in \cref{document-index}.
60 | Some important terms are defined below.
61 |
62 | \begin{definition}[Component]\index{component}
63 | An element defined by the production \lstinline[language=grammar]!component-clause! in the Modelica grammar (basically a variable or an instance of a class)
64 | \end{definition}
65 |
66 | \begin{definition}[Element]\index{element}
67 | Class definition, \lstinline!extends!-clause, or \lstinline[language=grammar]!component-clause! declared in a class (basically a class reference or a component in a declaration).
68 | \end{definition}
69 |
70 | \begin{definition}[Flattening]\index{flattening}
71 | The translation of a model described in Modelica to the corresponding model described as a hybrid DAE (see \cref{modelica-dae-representation}), involving expansion of inherited base classes, parameterization of base classes, local classes and components, and generation of connection equations from \lstinline!connect!-equations.
72 | In other words, mapping the hierarchical structure of a model into a set of differential, algebraic and discrete equations together with the corresponding variable declarations and function definitions from the model.
73 | \end{definition}
74 |
75 | \begin{definition}[Initialization]\index{initialization}
76 | Simulation starts with solving the initialization problem at the starting time, resulting in values for all variables that are consistent with the result of the flattening.
77 | \end{definition}
78 |
79 | \begin{definition}[Transient analysis]\index{transient analysis}\index{initial value problem!see{transient analysis}}
80 | Starting from the result of the initialization problem, the model is simulated forward in time.
81 | This uses numerical methods for handling the hybrid DAE, resulting in solution trajectories for the model's variables, i.e., the value of the variables as a function of time.
82 | \end{definition}
83 |
84 | \begin{nonnormative}
85 | In the numerical literature transient analysis is often called solving the \firstuse{initial value problem}, but that term is not used here to avoid confusion with the initialization problem.
86 | \end{nonnormative}
87 |
88 | \begin{definition}[Simulation]\index{simulation}
89 | Simulation is the combination of initialization followed by transient analysis.
90 | \end{definition}
91 |
92 | \begin{nonnormative}
93 | The model can be analyzed in ways other than simulation, e.g., linearization, and parameter estimation, but they are not described in the specification.
94 | \end{nonnormative}
95 |
96 | \begin{definition}[Translation]\index{translation!of simulation model}
97 | Translation is the process of preparing a Modelica simulation model for simulation, starting with flattening but not including the simulation itself.
98 | \end{definition}
99 |
100 | \begin{nonnormative}
101 | Typically, in addition to flattening, translation involves symbolic manipulation of the hybrid DAE and transforming the result into computer code that can simulate the model.
102 | \end{nonnormative}
103 |
104 |
105 | % More terms that would be useful to define here:
106 | % - deprecated
107 | % - quality of implementation
108 |
109 | \section{Notation}\label{notation}
110 |
111 | The remainder of this section shows examples of the presentation used in this document.
112 |
113 | Syntax highlighting of Modelica code is illustrated by the code listing below.
114 | Things to note include keywords that define code structure such as \lstinline!equation!, keywords that do not define code structure such as \lstinline!connect!, and recognized identifiers with meaning defined by the specification such as \lstinline!semiLinear!:
115 | \begin{lstlisting}[language=modelica]
116 | model Example "Example used to illustrate syntax highlighting"
117 | /* The string above is a class description string, this is a comment. */
118 | /* Invalid code is typically presented like this: */
119 | String s = 1.0; // Error: No conversion form Real to String.
120 | Real x;
121 | equation
122 | 2 * x = semiLinear(time - 0.5, 2, 3);
123 | /* The annotation below has omitted details represented by an ellipsis: */
124 | connect(resistor.n, conductor.p) annotation($\ldots$);
125 | end Example;
126 | \end{lstlisting}
127 |
128 | Relying on implicit conversion of \lstinline!Integer! literals to \lstinline!Real! is common, as seen in the equation above (note use of Modelica code appearing inline in the text).
129 |
130 | It is common to mix Modelica code with mathematical notation.
131 | For example, \lstinline!average($x$, $y$)! could be defined as $\frac{x + y}{2}$.
132 |
133 | Inline code fragments are sometimes surrounded by quotes to clearly mark their beginning and end, or to emphasize separation from the surrounding text.
134 | For example, `\lstinline!,!' is used to separate the arguments of a function call.
135 |
136 | \begin{definition}[Something]% Do not add this one to the index!
137 | Text defining the meaning of \emph{something}.
138 | \end{definition}
139 |
140 | In addition to the style of definition above, new terminology can be introduced in the running text.
141 | % TODO: Switch to \firstuse[---]{dummy} below. For now, using \willintroduce to avoid risk of accidentally
142 | % creating index entry in the future.
143 | For example, a \willintroduce{dummy} is something that\ldots
144 |
145 | \begin{nonnormative}
146 | This is non-normative content that provides some explanation, motivation, and/or additional things to keep in mind.
147 | It has no defining power and may be skipped by readers strictly interested in just the definition of the Modelica language.
148 | \end{nonnormative}
149 |
150 | \begin{example}
151 | This is an example, which is a special kind of non-normative content.
152 | Examples often contain a mix of code listings and explanatory text, and this is no exception:
153 | \begin{lstlisting}[language=modelica]
154 | String s = 1.0; // Error: No conversion form Real to String.
155 | \end{lstlisting}
156 | To fix the type mismatch above, the number has to be replaced by a \lstinline!String! expression, such as \lstinline!"1.0"!.
157 | \end{example}
158 |
159 | Other code listings in the document include specification of lexical units and grammatical structure, both using metasymbols of the extended BNF-grammar defined in~\cref{lexical-conventions}.
160 | Lexical units are named with all upper-case letters and introduced with the `\lstinline[language=grammar]!=!' sign:
161 | \begin{lstlisting}[language=grammar]
162 | SOME-TOKEN = NON-DIGIT { DIGIT | NON-DIGIT }
163 | \end{lstlisting}
164 | Grammatical structure is recognized by production rules being named with lower-case letters and introduced with the `\lstinline[language=grammar]!:!' sign (also note appearance of the Modelica keyword \lstinline!der!):
165 | \begin{lstlisting}[language=grammar]
166 | differentiated-expression :
167 | der "(" SOME-TOKEN ")"
168 | | "(" differentiated-expression "+" differentiated-expression ")"
169 | \end{lstlisting}
170 |
171 | Annotations are defined using the syntactic forms of Modelica record definitions and component declarations, but with special semantics given in \cref{notation-for-annotation-definitions}.
172 |
--------------------------------------------------------------------------------
/chapters/library.tex:
--------------------------------------------------------------------------------
1 | \chapter{The Modelica Standard Library}\label{the-modelica-standard-library}
2 |
3 | In order that a modeler can quickly build up system models, it is important that libraries of the most commonly used components are available, ready to use, and sharable between applications.
4 | For this reason, the Modelica Association develops and maintains a growing \emph{Modelica Standard Library} called \lstinline!package Modelica!.
5 | For an overview of the current version see \url{https://github.com/modelica/ModelicaStandardLibrary}.
6 | This is a free library that can be used without essential restrictions, e.g., in commercial Modelica simulation environments.
7 | The Modelica Standard Library is tool-neutral, and relies on a small library, ModelicaServices, that each conformant tool must implement to handle tool-specific couplings, e.g., for animation.
8 | Furthermore, other people and organizations are developing free and commercial Modelica libraries.
9 | For information about these libraries and for downloading the free libraries see \url{https://modelica.org/libraries/}.
10 |
--------------------------------------------------------------------------------
/chapters/preface.tex:
--------------------------------------------------------------------------------
1 | \chapter*{Preface}\label{preface}
2 | % https://tex.stackexchange.com/questions/45672/adding-numberless-chapters-to-the-table-of-contents
3 | \addcontentsline{toc}{chapter}{\protect\numberline{}Preface}
4 |
5 | Modelica is a freely available, object-oriented language for modeling of large, complex, and heterogeneous physical systems.
6 | From a user's point of view, models are described by schematics, also called object diagrams.
7 | Examples are shown below:
8 | \begin{center}
9 | \includegraphics[width=0.95\textwidth]{diagram_examples}
10 | \end{center}
11 |
12 | A schematic consists of connected components, like a resistor, or a hydraulic cylinder.
13 | A component has \emph{connectors} (often also called \emph{ports}) that describe the interaction possibilities, e.g., an electrical pin, a mechanical flange, or an input signal.
14 | By drawing connection lines between connectors a physical system or block diagram model is constructed.
15 | Internally a component is defined by another schematic, or on ``bottom'' level, by an equation-based description of the model in Modelica syntax.
16 |
17 | The Modelica language is a textual description to define all parts of a model and to structure model components in libraries, called packages.
18 | An appropriate Modelica simulation environment is needed to graphically edit and browse a Modelica model (by interpreting the information defining a Modelica model) and to perform model simulations and other analysis.
19 | Information about such environments is available at \url{https://modelica.org/tools}.
20 | Basically, all Modelica language elements are mapped to differential, algebraic and discrete equations.
21 | There are no language elements to describe directly partial differential equations, although some types of discretized partial differential equations can be reasonably defined, e.g., based on the finite volume method and there are Modelica libraries to import results of finite-element programs.
22 |
23 | This document defines the details of the Modelica language.
24 | It is not intended to learn the Modelica language with this text.
25 | There are better alternatives, such as the Modelica books referenced at \url{https://modelica.org/publications}.
26 | This specification is used by computer scientist to implement a Modelica translator and by modelers who want to understand the exact details of a particular language element.
27 |
28 | The text directly under the chapter headings are non-normative introductions to the chapters.
29 |
30 | The Modelica language has been developed since 1996.
31 | This document describes version \mlsversion{} of the Modelica language.
32 | The revision history is available in \cref{modelica-revision-history}.
33 |
--------------------------------------------------------------------------------
/chapters/revisions.tex:
--------------------------------------------------------------------------------
1 | \chapter{Modelica Revision History}\label{modelica-revision-history}
2 |
3 | This appendix described the history of the Modelica Language Design, and its contributors.
4 | This appendix is just present for historical reasons and is not normative.
5 | The current version, as well as all previous versions of this document, and the list of changes are available at \url{https://specification.modelica.org}.
6 |
7 | The members of the Modelica Association project \emph{Modelica Language} (MAP-Lang) contributed to the Modelica specification.
8 |
9 | % Alternatives:
10 | % Keep short list all revisions as on specification.modelica.org
11 | % Only (major revisions, 1.0, 2.0, 3.0)
12 | % keep nothing
13 | % or just start.
14 | % Keeping just the start to have a historic perspective
15 | Modelica 1, the first version of Modelica, was released in September 1997, and had the language specification as a short appendix to the rationale.
16 |
--------------------------------------------------------------------------------
/chapters/titlepage.tex:
--------------------------------------------------------------------------------
1 | \begin{titlepage}
2 | % Note that things like \vspace and linebreaks with height (\\[2\baselineskip]) are lost in generated HTML;
3 | % only line breaks and paragraph breaks survive.
4 | \addtolength{\parskip}{\baselineskip}% Lots of space between paragraphs on the PDF title page.
5 | \vspace*{\fill}
6 | \begin{center}
7 | \ifpdf
8 | \includegraphics[width=8cm]{Modelica_Language}
9 | \else
10 | \includegraphics[width=15cm]{Modelica_Language}
11 | \fi
12 | \vspace{1cm}
13 |
14 | \huge
15 | Modelica\textsuperscript{\textregistered} -- A Unified Object-Oriented Language for~Systems Modeling
16 |
17 | Language Specification
18 |
19 | Version \mlsversion
20 |
21 | \vspace{1cm}% This has no effect in the generated HTML.
22 |
23 | \Large
24 | \makeatletter
25 | \@date
26 |
27 | \@author
28 | \makeatother
29 | \end{center}
30 |
31 | \ifpdf
32 | \vfill
33 | \else
34 | \newpage % In the HTML, this will appear as some extra vertical space.
35 | \fi
36 | \input{chapters/abstract}
37 | \end{titlepage}
38 |
--------------------------------------------------------------------------------
/chapters/unitexpressions.tex:
--------------------------------------------------------------------------------
1 | \chapter{Unit Expressions}\label{unit-expressions}
2 |
3 | Unless otherwise stated, the syntax and semantics of unit expressions in Modelica (for example, \cref{real-type} or \cref{axis-properties}) conform with the international standards \emph{International System of Units (SI)} by BIPM superseding parts of ISO 31/0-1992 \emph{General principles concerning quantities, units and symbols} and ISO 1000-1992 \emph{SI units and recommendations for the use of their multiples and of certain other units}.
4 | Unfortunately, these standards do not define a formal syntax for unit expressions.
5 | There are recommendations and Modelica exploits them.
6 |
7 | Note that this document uses the American spelling \emph{meter}, whereas the SI specification from BIPM uses the British spelling \emph{metre}.
8 |
9 | Examples for the syntax of unit expressions used in Modelica: \lstinline!"N.m"!, \lstinline!"kg.m/s2"!, \lstinline!"kg.m.s-2"!, \lstinline!"1/rad"!, \lstinline!"mm/s"!.
10 |
11 | \section{The Syntax of Unit Expressions}\label{the-syntax-of-unit-expressions}
12 |
13 | The Modelica unit string syntax allows neither comments nor white-space, and a unit string shall match the \lstinline[language=grammar]!unit-expression! rule:
14 | \begin{lstlisting}[language=grammar]
15 | unit-expression :
16 | unit-numerator [ "/" unit-denominator ]
17 |
18 | unit-numerator :
19 | "1" | unit-factors | "(" unit-expression ")"
20 |
21 | unit-denominator:
22 | unit-factor | "(" unit-expression ")"
23 | \end{lstlisting}
24 |
25 | The unit of measure of a dimension free quantity is denoted by \lstinline!"1"!.
26 | The SI standard does not define any precedence between multiplications and divisions.
27 | The SI standard does not allow multiple units to the right of the division-symbol (\lstinline!/!) since the result is ambiguous; either the divisor shall be enclosed in parentheses, or negative exponents used instead of division, for example, \lstinline!"J/(kg.K)"! may be written as \lstinline!"J.kg-1.K-1"!.
28 |
29 | \begin{lstlisting}[language=grammar]
30 | unit-factors :
31 | unit-factor [ "." unit-factors ]
32 | \end{lstlisting}
33 |
34 | The SI standard specifies that a multiplication operator symbol is written as space or as a dot.
35 | The SI standard requires that this \emph{dot} is a bit above the base line: `·', which is not part of ASCII.
36 | The ISO standard also prefers `·', but Modelica supports the ISO alternative `.', which is an ordinary \emph{dot} on the base line.
37 |
38 | For example, Modelica does not support \lstinline!"Nm"! for newton-meter, but requires it to be written as \lstinline!"N.m"!.
39 |
40 | \begin{lstlisting}[language=grammar]
41 | unit-factor :
42 | unit-operand [ unit-exponent ]
43 |
44 | unit-exponent :
45 | [ "+" | "-" ] ( UNSIGNED-INTEGER | "(" UNSIGNED-INTEGER "/" UNSIGNED-INTEGER ")" )
46 | \end{lstlisting}
47 |
48 | The SI standard uses super-script for the exponentation, and does thus not define any operator symbol for exponentiation.
49 | A \lstinline[language=grammar]!unit-factor! consists of a \lstinline[language=grammar]!unit-operand! possibly suffixed by a possibly signed integer or rational number, which is interpreted as an exponent.
50 | There must be no spacing between the \lstinline[language=grammar]!unit-operand! and a possible \lstinline[language=grammar]!unit-exponent!.
51 | It is recommended to use the simplest representation of exponents, meaning that the explicit \lstinline!+! sign should be avoided, that leading zeros should be avoided, that rational exponents are reduced to not have common factors in the numerator and denominator, that rational exponents with denominator 1 should be avoided in favor of plain integer exponents, that the exponent 1 is omitted, and that entire factors with exponent 0 are omitted.
52 |
53 | \begin{lstlisting}[language=grammar]
54 | unit-operand :
55 | unit-symbol | unit-prefix unit-symbol
56 |
57 | unit-prefix :
58 | "Q" | "R" | "Y" | "Z" | "E" | "P" | "T" | "G" | "M" | "k" | "h" | "da"
59 | | "d" | "c" | "m" | "u" | "n" | "p" | "f" | "a" | "z" | "y" | "r" | "q"
60 |
61 | unit-symbol :
62 | unit-char { unit-char }
63 |
64 | unit-char :
65 | NON-DIGIT
66 | \end{lstlisting}
67 |
68 | The units required to be recognized are the basic and derived units of the SI system, as well as some units compatible with the SI system listed below, but tools are allowed to additionally support user-defined unit symbols.
69 | The required unit symbols do not make use of Greek letters, but a unit such as $\Omega$ is spelled out as \lstinline!"Ohm"!.
70 | Similarly degree is spelled out as \lstinline!"deg"!, both on its own (for angles) and as part of \lstinline!"degC"!, \lstinline!"degF"! and \lstinline!"degRk"! for temperatures (Celsius, Fahrenheit and Rankine).
71 |
72 | It is recommended that non-SI units are only used for the \lstinline!displayUnit!-attribute in order to reduce impact of unrecognized unit symbols when using another Modelica tool.
73 |
74 | The following are the units required to be recognized in addition to the SI system:
75 | \begin{itemize}
76 | \item minute \lstinline!"min"! (1 minute = 60 s)
77 | \item hour \lstinline!"h"! (1 hour = 3600 s)
78 | \item day \lstinline!"d"! (1 day = 86400 s)
79 | \item liter \lstinline!"l"! and \lstinline!"L"! (1 liter = 1 $\text{dm}^{3}$)
80 | \item electronvolt \lstinline!"eV"! (1 electronvolt = 1.602176634e-19 J)
81 | \item degree \lstinline!"deg"! (1 degree = $\pi/180$ rad)
82 | \item debye \lstinline!"debye"! (1 debye = 1e-21 / 299792458 Cm)
83 | \end{itemize}
84 | The first 7 are listed in the SI standard as non-SI units that are acceptable to use with the SI system.
85 |
86 | A \lstinline[language=grammar]!unit-operand! should first be interpreted as a \lstinline[language=grammar]!unit-symbol! and only if not successful the second alternative assuming a prefixed operand should be exploited.
87 | There must be no spacing between the \lstinline[language=grammar]!unit-symbol! and a possible \lstinline[language=grammar]!unit-prefix!.
88 | The values of the prefixes are according to the ISO standard.
89 | The letter \lstinline!u! is used as a symbol for the prefix \emph{micro}.
90 |
91 | \begin{nonnormative}
92 | A tool may present \lstinline!"Ohm"! as $\Omega$ and the prefix \lstinline!"u"! as $\mu$.
93 | Exponents such as \lstinline!"m2"! may be presented as m\textsuperscript{2}.
94 | Degrees may be presented as $^{\circ}$, both for \lstinline!"deg"! on its own (for angles) and for temperatures -- e.g., \lstinline!"degC"! can be presented as $^{\circ}$C.
95 | Note that BIPM have specific recommendations for formatting using these symbols.
96 | \end{nonnormative}
97 |
98 | \begin{example}
99 | The unit expression \lstinline!"m"! means meter and not milli (10\textsuperscript{-3}), since prefixes cannot be used in isolation.
100 | For millimeter use \lstinline!"mm"! and for square meter, m\textsuperscript{2}, write \lstinline!"m2"!.
101 |
102 | The expression \lstinline!"mm2"! means (10\textsuperscript{-3}m)\textsuperscript{2} = 10\textsuperscript{-6}m\textsuperscript{2}.
103 | Note that exponentiation includes the prefix.
104 |
105 | The unit expression \lstinline!"T"! means tesla, but note that the letter \lstinline!T! is also the symbol for the prefix tera which has a multiplier value of 10\textsuperscript{12}.
106 | \end{example}
107 |
--------------------------------------------------------------------------------
/css/MLS-navbar-left.css:
--------------------------------------------------------------------------------
1 | /*
2 | * CSS for left navigation bar.
3 | * Developed from LaTeXML-navbar-left.css as starting point.
4 | */
5 |
6 | body {
7 | margin: 0px;
8 | background: #F6F6F6;
9 | }
10 |
11 | nav > div.ltx_TOC {
12 | margin-left: 1em;
13 | }
14 |
15 | .ltx_page_navbar {
16 | display: block!important;
17 | position: fixed;
18 | z-index: 2;
19 | top: 0px;
20 | margin: 0px;
21 | padding: 0px;
22 | font-size: 14px; /* Less than what is inherited from .body, to reduce need for scrolling. */
23 | line-height: 1.3; /* Less than what is inherited from .body, to reduce need for scrolling. */
24 | color: black;
25 | border-style: solid;
26 | border-color: #707A85; /* "Bouncing ball trace gray" */
27 | border-width: 0px;
28 | border-right-width: 8px;
29 | background: #F6F6F6;
30 | height: 100%; /* Provide fixed height for .ltx_TOC to refer to. */
31 | }
32 |
33 | .ltx_page_navbar:before {
34 | position: fixed;
35 | z-index: 4;
36 | left: 0px;
37 | top: 0px;
38 | margin: 0px;
39 | padding: 0px;
40 | font-size: 25px;
41 | color: #DE1D31; /* "Bouncing ball red" */
42 | height: 30px;
43 | width: calc(3rem - 8px);
44 | background: #F6F6F6;
45 | text-align: center;
46 | content: "☰"; /* Chinese character that looks like hamburger. */
47 | }
48 |
49 | .ltx_page_navbar a[rel=start] {
50 | display: none; /* Don't show sidebar title, as it is too long to look good, and seem to lack structure for adequate layout. */
51 | }
52 |
53 | .ltx_page_navbar .ltx_tocentry_document > .ltx_ref_self {
54 | display: none; /* Similar to sidebar title, but for the top page. */
55 | }
56 |
57 | .ltx_page_header a[rel=prev] {
58 | display: none; /* Don't show link to previous chapter. */
59 | }
60 |
61 | .ltx_page_header a[rel=next] {
62 | display: none; /* Don't show link to previous chapter. */
63 | }
64 |
65 | .ltx_page_footer a[rel=bibliography] {
66 | display: none; /* Don't show link to bibliography. */
67 | }
68 |
69 | .ltx_page_footer a[rel=index]:before {
70 | display: inline-block;
71 | content: "";
72 | height: 1.5rem; /* Same as .ltx_page_header. */
73 | width: 1.5rem;
74 | padding: 0.5rem; /* Same as y-direction in .ltx_page_header. */
75 | margin: 0px;
76 | border-style: solid;
77 | border-color: #707A85; /* "Bouncing ball trace gray" */
78 | border-width: 0px;
79 | border-left-width: 8px;
80 | background-image: url("Magnifying_glass_icon.svg");
81 | background-position: center;
82 | background-repeat: no-repeat;
83 | background-size: 25px 25px;
84 | }
85 |
86 | .ltx_page_footer a[rel=index] {
87 | position: fixed;
88 | z-index: 4;
89 | top: 0px;
90 | right: 0px;
91 | }
92 |
93 | .ltx_page_footer a[rel=index] span {
94 | display: none; /* Don't display the "Index" text; we have added a magnifying glass instead. */
95 | }
96 |
97 | .ltx_TOC {
98 | padding-right: 1em;
99 | overflow-y: auto;
100 | }
101 |
102 | .ltx_TOC > ul.ltx_toclist {
103 | padding: 0em;
104 | }
105 |
106 | .ltx_tocentry_document > ul.ltx_toclist {
107 | padding: 0em;
108 | }
109 |
110 | .ltx_toclist ul {
111 | padding-left: 1em; /* Indentation of each table of contents level below the top. */
112 | }
113 |
114 | /* How to deal with the long section titles in the table of contents (overriding styling from LaTeXML.css).
115 | * The right boundary for these titles is the .ltx_page_navbar padding-right.
116 | */
117 | .ltx_page_navbar li {
118 | white-space: nowrap;
119 | overflow: hidden;
120 | text-overflow: ellipsis;
121 | }
122 |
123 | .ltx_ref_title .ltx_tag_ref {
124 | font-size: 75%; /* Compress navbar even more by shrinking the numbering. */
125 | }
126 |
127 | .ltx_page_main {
128 | position: absolute;
129 | z-index: 1;
130 | margin-top: 0px;
131 | margin-bottom: 0px;
132 | border-width: 0px;
133 | max-width: 80em;
134 | padding: 0px;
135 | }
136 |
137 | .ltx_page_header {
138 | position: fixed;
139 | z-index: 3;
140 | top: 0px;
141 | height: 1.5rem;
142 | padding-top: 0.5rem;
143 | padding-bottom: 0.5rem;
144 | padding-left: 0rem;
145 | /* Add right padding corresponding to part being covered by magnifying glass.
146 | */
147 | padding-right: calc(1.5rem + 2 * 0.5rem + 8px);
148 | background: #F6F6F6; /* Same as body. */
149 | color: black; /* Same as side bar. */
150 | border-bottom-color: #DE1D31; /* "Bouncing ball red" */
151 | border-bottom-width: 2px;
152 | white-space: nowrap;
153 | text-overflow: ellipsis;
154 | }
155 |
156 | /* Make current jump target appear below the page header instead of behind it.
157 | */
158 | :target:before {
159 | visibility: hidden;
160 | content: "X"; /* Hidden, but needs to be non-empty to work in Chrome. */
161 | display: block;
162 | position: relative;
163 | top: calc(-(2.5rem + 2px)); /* Offset by total height of .ltx_page_header. */
164 | }
165 |
166 | .ltx_item :target:before {
167 | display: inline-block;
168 | padding-top: calc((2.5rem + 2px)); /* Pad with total height of .ltx_page_header. */
169 | }
170 |
171 | .ltx_page_content {
172 | padding-top: 2rem;
173 | padding-bottom: 1rem;
174 | padding-left: 1rem;
175 | padding-right: 1rem;
176 | background: white;
177 | }
178 |
179 | .ltx_page_footer {
180 | padding: 1rem;
181 | background: white;
182 | }
183 |
184 | /* Layout for wide screens, with navbar always expanded.
185 | * The threshold for being considered wide is set so that it should be possible to get a collapsable
186 | * navbar at the same time as extending .ltx_page_main to its max-width (currently 80em).
187 | * This max-width is added to the .ltx_page_main margin-left in the collapsable layout, currently
188 | * resulting in 1306px if 1em is converted to 16px:
189 | * 80em * 16px/em + 2px + 16px + 8px = 1306px
190 | * Add 4px of slack, and the threshold becomes 1310.
191 | */
192 | @media screen and (min-width: 1310px) {
193 | .ltx_page_main {
194 | margin-left: 350px;
195 | }
196 | .ltx_page_navbar {
197 | left: 0px;
198 | width: calc(350px - 8px); /* Width of .ltx_page_main, minus .ltx_page_navbar border-right-width. */
199 | }
200 | .ltx_TOC {
201 | height: 100%;
202 | }
203 | .ltx_page_header {
204 | width: calc(100% - 350px - (1.5rem + 2 * 0.5rem + 8px)); /* Subtract total horizontal padding on this element. */
205 | }
206 | .ltx_page_navbar:before {
207 | display: none;
208 | }
209 | }
210 |
211 | /* Layout for smaller screens or other media where navbar is only expanded when hovered.
212 | */
213 | @media screen and (max-width: 1310px) {
214 | .ltx_page_main {
215 | /* Leave just enough space to fit the hamburger plus the right border of the .ltx_page_navbar.
216 | * Don't define this in em units, since the em is not the same below in .ltx_page_navbar.
217 | */
218 | margin-left: 0px;
219 | }
220 | .ltx_page_navbar {
221 | width: 500px;
222 | height: 2.5rem;
223 | left: calc(3rem - (500px + 8px));
224 | transition: 0.3s;
225 | }
226 | .ltx_TOC {
227 | margin-top: 20px; /* Reserve space for hamburger. */
228 | height: calc(100% - 20px);
229 | }
230 | .ltx_page_header {
231 | padding-left: 3rem;
232 | width: calc(100% - 3rem - (1.5rem + 2 * 0.5rem + 8px)); /* Subtract horizontal padding on this element. */
233 | }
234 | .ltx_page_navbar:hover {
235 | left: 0px;
236 | height: 100%;
237 | }
238 | .ltx_page_navbar:before {
239 | display: block;
240 | }
241 | }
242 |
--------------------------------------------------------------------------------
/css/MLS.css:
--------------------------------------------------------------------------------
1 | /* This CSS makes adjustments for the MLS on top of the style sheets that come with LaTeXML.
2 | * By not editing copies of the ones from LaTeXML, we can take advantage of upstream improvements to the LaTeXML files.
3 | */
4 |
5 | /* Changes by Martin
6 | */
7 | body {
8 | font-family: Verdana, Arial, Helvetica, sans-serif;
9 | font-size: 16px;
10 | line-height: 1.5;
11 | color: #333;
12 | background-color: #fff;
13 | }
14 |
15 | a { text-decoration: none; color: inherit; }
16 | a:hover { text-decoration: underline; }
17 |
18 | .ltx_titlepage {
19 | padding-top: 2rem; /* The big Modelica Language logo doesn't look good too close to page header. */
20 | }
21 |
22 | .ltx_tocentry_subsection { display: none; }
23 |
24 | /* Undo bold here to remove the browser's native
styling,
25 | */
26 | .ltx_th { font-weight: normal; }
27 |
28 | /* NOT ACTIVE: Compensate for default font size ratio 13:16 for monospace to normal.
29 | * 16/13 = 1.2307...
30 | * When inline code is displayed side by side with MathJax math, even this is on the small side, but when the
31 | * MathJax math is inside the inline code (using mathescape), the math is scaled down with the text.
32 | * Hence, rather than scaling up the monospace font, it seems better to scale down the math that isn't doesn't have
33 | * font set to monospace (the font probably only matters for font size selection in the case of math content).
34 | * TODO: Needs more tweaking in order to do more good than harm.
35 | */
36 | /* .ltx_Math { font-size:120%; } */
37 | /* .MathJax .ltx_Math { font-size: 100%; } */
38 | /* .ltx_font_typewriter { font-size:110%; } */
39 | /* .ltx_font_typewriter .ltx_Math { font-size: 120%; } */
40 | /* .ltx_font_typewriter .MathJax .ltx_Math { font-size: 110%; } */
41 |
42 | /* Undo the ltx-report.css setting that destroys parskip.sty style paragraphs.
43 | */
44 | .ltx_para > .ltx_p:first-child { text-indent: 0; }
45 |
46 | /* Treat heading for table of contents on front page as if it were a chapter title,
47 | * by copying the style of .ltx_title_chapter in ltx-report.css.
48 | */
49 | .ltx_document .ltx_TOC h6 {
50 | font-size: 200%;
51 | font-weight: bold;
52 | margin-bottom: 1em;
53 | }
54 |
55 | .ltx_dates {
56 | display: none;
57 | }
58 |
59 | .ltx_biblist {
60 | padding-inline-start: 0px;
61 | }
62 |
63 | .ltx_bibitem {
64 | padding: 0.5rem 0px;
65 | }
66 |
67 | .ltx_bibitem .ltx_tag {
68 | margin-left: 0px;
69 | }
70 |
71 | /* Treat heading for document index as if it were a chapter title,
72 | * by copying the style of .ltx_title_chapter in ltx-report.css.
73 | */
74 | .ltx_page_content .ltx_index h1 {
75 | font-size: 200%;
76 | font-weight: bold;
77 | margin-bottom: 1em;
78 | }
79 |
80 | /* Remove indentation of index terms at the top level.
81 | */
82 | .ltx_index > .ltx_indexlist {
83 | margin-left: 0px;
84 | padding-left: 0px;
85 | }
86 |
87 | /* Change space between term and links into a dash in order to get better separation.
88 | * This is needed since LaTeXML produces many links that begin with words that makes it hard to see where the
89 | * term ends and the links begin.
90 | */
91 | .ltx_indexrefs > .ltx_text:first-child:before {
92 | content: " –";
93 | }
94 |
95 | .ltx_page_header *[rel~="up"],
96 | .ltx_page_footer *[rel~="up"] { display: table; margin: 0 auto; text-align: center; }
97 |
--------------------------------------------------------------------------------
/css/Magnifying_glass_icon.svg:
--------------------------------------------------------------------------------
1 |
2 |
3 |
4 |
12 |
--------------------------------------------------------------------------------
/edit/Sublime/.gitignore:
--------------------------------------------------------------------------------
1 | *.sublime-workspace
2 |
--------------------------------------------------------------------------------
/edit/Sublime/config.sublime-project:
--------------------------------------------------------------------------------
1 | {
2 | "folders":
3 | [
4 | {
5 | "file_exclude_patterns":
6 | [
7 | "*.aux",
8 | "*.lof",
9 | "*.log",
10 | "*.lot",
11 | "*.fls",
12 | "*.out",
13 | "*.toc",
14 | "*.cache",
15 | "*.xml",
16 | "*.html",
17 | "MLS.pdf",
18 | "LaTeXML.css",
19 | "MLS.tar.gz",
20 | "ltx-article.css",
21 | "ltx-listings.css",
22 | "ltx-report.css",
23 | "LaTeXML-maybeMathjax.js",
24 | "MLS.fdb_latexmk",
25 | "MLS.synctex.gz",
26 | ],
27 | "folder_exclude_patterns":
28 | [
29 | "media",
30 | ],
31 | "path": "../.."
32 | }
33 | ],
34 | "settings": {
35 | "TEXroot": "../../MLS.tex",
36 | },
37 | }
38 |
--------------------------------------------------------------------------------
/media/Modelica_Language.pdf:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/modelica/ModelicaSpecification/9ad2a9233cde7cc0a63d993681dc56bdc8f01e56/media/Modelica_Language.pdf
--------------------------------------------------------------------------------
/media/Modelica_Language.svg:
--------------------------------------------------------------------------------
1 |
2 |
--------------------------------------------------------------------------------
/media/Modelica_Language_dark.svg:
--------------------------------------------------------------------------------
1 |
2 |
--------------------------------------------------------------------------------
/media/bezierpoints.pdf:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/modelica/ModelicaSpecification/9ad2a9233cde7cc0a63d993681dc56bdc8f01e56/media/bezierpoints.pdf
--------------------------------------------------------------------------------
/media/clock.pdf:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/modelica/ModelicaSpecification/9ad2a9233cde7cc0a63d993681dc56bdc8f01e56/media/clock.pdf
--------------------------------------------------------------------------------
/media/clocked.pdf:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/modelica/ModelicaSpecification/9ad2a9233cde7cc0a63d993681dc56bdc8f01e56/media/clocked.pdf
--------------------------------------------------------------------------------
/media/diagram_examples.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/modelica/ModelicaSpecification/9ad2a9233cde7cc0a63d993681dc56bdc8f01e56/media/diagram_examples.png
--------------------------------------------------------------------------------
/media/disabledparameter.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/modelica/ModelicaSpecification/9ad2a9233cde7cc0a63d993681dc56bdc8f01e56/media/disabledparameter.png
--------------------------------------------------------------------------------
/media/fluidmix.pdf:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/modelica/ModelicaSpecification/9ad2a9233cde7cc0a63d993681dc56bdc8f01e56/media/fluidmix.pdf
--------------------------------------------------------------------------------
/media/fluidmix3.pdf:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/modelica/ModelicaSpecification/9ad2a9233cde7cc0a63d993681dc56bdc8f01e56/media/fluidmix3.pdf
--------------------------------------------------------------------------------
/media/fluidmix4.pdf:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/modelica/ModelicaSpecification/9ad2a9233cde7cc0a63d993681dc56bdc8f01e56/media/fluidmix4.pdf
--------------------------------------------------------------------------------
/media/fluidsystem.pdf:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/modelica/ModelicaSpecification/9ad2a9233cde7cc0a63d993681dc56bdc8f01e56/media/fluidsystem.pdf
--------------------------------------------------------------------------------
/media/hierarchical-statemachine.pdf:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/modelica/ModelicaSpecification/9ad2a9233cde7cc0a63d993681dc56bdc8f01e56/media/hierarchical-statemachine.pdf
--------------------------------------------------------------------------------
/media/innerouterconnector.pdf:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/modelica/ModelicaSpecification/9ad2a9233cde7cc0a63d993681dc56bdc8f01e56/media/innerouterconnector.pdf
--------------------------------------------------------------------------------
/media/modelicapath.pdf:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/modelica/ModelicaSpecification/9ad2a9233cde7cc0a63d993681dc56bdc8f01e56/media/modelicapath.pdf
--------------------------------------------------------------------------------
/media/overdetermined.pdf:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/modelica/ModelicaSpecification/9ad2a9233cde7cc0a63d993681dc56bdc8f01e56/media/overdetermined.pdf
--------------------------------------------------------------------------------
/media/piecewise-constant.pdf:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/modelica/ModelicaSpecification/9ad2a9233cde7cc0a63d993681dc56bdc8f01e56/media/piecewise-constant.pdf
--------------------------------------------------------------------------------
/media/plantmodel.pdf:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/modelica/ModelicaSpecification/9ad2a9233cde7cc0a63d993681dc56bdc8f01e56/media/plantmodel.pdf
--------------------------------------------------------------------------------
/media/statemachine.pdf:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/modelica/ModelicaSpecification/9ad2a9233cde7cc0a63d993681dc56bdc8f01e56/media/statemachine.pdf
--------------------------------------------------------------------------------
/media/statemachineplot.pdf:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/modelica/ModelicaSpecification/9ad2a9233cde7cc0a63d993681dc56bdc8f01e56/media/statemachineplot.pdf
--------------------------------------------------------------------------------
/media/subtype.pdf:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/modelica/ModelicaSpecification/9ad2a9233cde7cc0a63d993681dc56bdc8f01e56/media/subtype.pdf
--------------------------------------------------------------------------------
/media/tabparameter.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/modelica/ModelicaSpecification/9ad2a9233cde7cc0a63d993681dc56bdc8f01e56/media/tabparameter.png
--------------------------------------------------------------------------------
/mls.bib:
--------------------------------------------------------------------------------
1 | @Article{Pantelides1988ConsistentInitialization,
2 | author = {Pantelides, Constantinos C.},
3 | title = {The Consistent Initialization of Differential-Algebraic Systems},
4 | year = {1988},
5 | month = mar,
6 | journal = {{SIAM} Journal on Scientific and Statistical Computing},
7 | volume = {9},
8 | number = {2},
9 | pages = {213–-231},
10 | doi = {10.1137/0909014},
11 | }
12 |
13 | @Article{BenvenisteEtAl2003SynchronousTwelveYearsLater,
14 | author = {Benveniste, Albert and Caspi, Paul and Edwards, Stephen A. and Halbwachs, Nicolas and Le Guernic, Paul and Simone, Robert de},
15 | title = {The Synchronous Languages Twelve Years Later},
16 | year = {2003},
17 | journal = {Proceedings of the {IEEE}},
18 | volume = {91},
19 | number = {1},
20 | doi = {10.1109/JPROC.2002.805826},
21 | }
22 |
23 | @InProceedings{ColacoPouzet2003ClocksFirstClass,
24 | author = {Colaço, Jean-Louis and Pouzet, Marc},
25 | title = {Clocks as First Class Abstract Types},
26 | year = {2003},
27 | month = oct,
28 | booktitle = {Third International Workshop on Embedded Software, {EMSOFT} 2003},
29 | address = {Philadelphia, Pennsylvania, {USA}},
30 | url = {http://www.di.ens.fr/~pouzet/lucid-synchrone/papers/emsoft03.ps.gz},
31 | doi = {10.1007/978-3-540-45212-6_10},
32 | }
33 |
34 | @InProceedings{ElmqvistOtterCellier1995InlineIntegration,
35 | author = {Elmqvist, Hilding and Otter, Martin and Cellier, Francois E.},
36 | title = {Inline Integration: A New Mixed Symbolic/Numeric Approach for Solving Differential-Algebraic Equation Systems},
37 | year = {1995},
38 | month = jun,
39 | day = {5--8},
40 | booktitle = {Proceedings of {ESM}’95, European Simulation Multiconference},
41 | pages = {xxiii--xxxiv},
42 | address = {Prague, Czech Republic},
43 | url = {https://www.semanticscholar.org/paper/Inline-Integration%3A-A-New-Mixed-Symbolic%2FNumeric-Elmqvist-Otter/b696154cbfb9c82dd4983abbd45ed639a4d5c32c},
44 | }
45 |
46 | @InProceedings{ForgetEtAl2008MultiPeriodic,
47 | author = {Forget, Julien and Boniol, Frédéric and Lesens, David and Pagetti, Claire},
48 | title = {A Multi-Periodic Synchronous Data-Flow Language},
49 | year = {2008},
50 | month = dec,
51 | day = {3--5},
52 | booktitle = {11\textsuperscript{th} {IEEE} High Assurance Systems Engineering Symposium ({HASE}'08)},
53 | pages = {251--260},
54 | address = {Nanjing, China},
55 | doi = {10.1109/HASE.2008.47},
56 | }
57 |
58 | @Article{Harel1987Statecharts,
59 | author = {Harel, David},
60 | organization = {Department of Applied Mathematics, The Weizmann Institute of Science, Rehovot, Israel},
61 | title = {Statecharts: A Visual Formalism for Complex Systems},
62 | journal = {Science of Computer Programming},
63 | year = {1987},
64 | volume = {8},
65 | pages = {231--274},
66 | doi = {10.1016/0167-6423(87)90035-9},
67 | }
68 |
69 | @InProceedings{ThummelEtAl2005InverseModels,
70 | author = {Thümmel, Michael and Looye, Gertjan and Kurze, Matthias and Otter, Martin and Bals, Johann},
71 | title = {Nonlinear Inverse Models for Control},
72 | year = {2005},
73 | month = mar,
74 | day = {7--8},
75 | booktitle = {Proceedings of 4\textsuperscript{th} International Modelica Conference, ed. G. Schmitz},
76 | address = {Hamburg, Germany},
77 | url = {https://modelica.org/events/Conference2005/online_proceedings/Session3/Session3c3.pdf},
78 | }
79 |
80 | @Manual{Pouzet2006LucidSynchrone30,
81 | author = {Pouzet, Marc},
82 | title = {Lucid Synchrone, Version 3.0, Tutorial and Reference Manual},
83 | year = {2006},
84 | url = {http://www.di.ens.fr/~pouzet/lucid-synchrone/},
85 | }
86 |
87 | @Manual{GettextManual,
88 | author = {Drepper, Ulrich and Meyering, Jim and Pinard, François and Haible, Bruno},
89 | title = {GNU gettext tools, version 0.21},
90 | year = {2020},
91 | url = {https://www.gnu.org/software/gettext/manual/},
92 | }
93 |
94 | @InProceedings{Buerger2019SelectiveModel,
95 | author = {Bürger, Christoff},
96 | title = {Modelica language extensions for practical non-monotonic modelling: on the need for \emph{selective} model extension},
97 | year = {2019},
98 | month = mar,
99 | day = {4--6},
100 | booktitle = {Proceedings of the 13\textsuperscript{th} International Modelica Conference},
101 | pages = {277--288},
102 | address = {Regensburg, Germany},
103 | doi = {10.3384/ecp19157277},
104 | }
105 |
--------------------------------------------------------------------------------
/mlsshared.sty:
--------------------------------------------------------------------------------
1 | % Package with preamble content to be shared by the main document and its figures.
2 |
3 | % Formatting for filenames, URIs, etc.
4 | % For now, the content is wrapped in \mbox to avoid hyphenation to inject
5 | % hyphens. A better solution could be to change the directory separator
6 | % characters to also produce an \allowbreak{} following the directory separator.
7 | \newcommand{\filename}[1]{\mbox{\textsf{#1}}}
8 |
9 | % Pick a tt font that meets all of the following requirements:
10 | % - Not too wide (to reduce need for manual breaking of long lines)
11 | % - Has boldface variant that is distinctively heavier than its medium weight variant.
12 | % - Medium weight variant is heavy enough to not make non-black colors blend too much with the
13 | % white background due to anti-aliasing and similar effects.
14 | % Warning: Note that changing to a font with different width -- especially a wider one -- means
15 | % that existing manual line breaks are potentially becoming out of place.
16 | % Finally, don't use newtexttt in listings in the LaTeXML build, see:
17 | % - https://github.com/brucemiller/LaTeXML/issues/1713
18 | \ifpdf
19 | \usepackage{newtxtt}
20 | \fi
21 |
22 | \usepackage{textcomp}
23 | \usepackage{listings}
24 | \usepackage{color}
25 | \usepackage[table]{xcolor}
26 |
27 | \definecolor{keywordcolor1} {rgb}{0.00, 0.20, 0.47}
28 | \definecolor{keywordcolor3} {rgb}{0.33, 0.24, 0.03}
29 | \definecolor{commentcolor} {rgb}{0.07, 0.46, 0.00}
30 |
31 | % It would be nice to have comments set in normal variable-width font without any sort of
32 | % column alignment by the listsings.sty package, just like the comments look in the LaTeXML build.
33 | % Adding the following \commentfullflexible to the 'commentstyle'
34 | % makes words look good, but the words are still aligned in mysterious ways.
35 | %\let\commentfullflexible\lst@column@fullflexible
36 |
37 | % See https://github.com/modelica-tools/listings-modelica/blob/master/listings-modelica.cfg
38 | % Note: Changed comment color from green to [rgb]{0,0.4,0} - since the other variant was too distracting
39 | % And added pure,impure,stream as keywords
40 | % Remove cross as red
41 | % Note: have basicstyle=\upshape\small\ttfamily in all languages,
42 | % except the dialect [short]modelica - which is used for inline listings.
43 | % Apart from that change that dialect should be identical to modelica
44 |
45 | % The morekeywords=[3] part is a bit unclear.
46 | % The current logic is that "operators" are marked specially, but not normal functions.
47 | %
48 | % Note that Integer is both a predefined type and a function; we cannot treat them differently.
49 | % Another solution would be to remove this completely.
50 | \lstdefinelanguage{modelica}{% Language for use with the lstlisting environment.
51 | basicstyle=\upshape\ttfamily\smallifpdf, % Font size for displayed code listings.
52 | alsoletter={},
53 | % otherkeywords={-, =, +, [, ], (, ), \{, \}, :, *, !},%
54 | morekeywords=[1]{% Keywords not used to define code structure
55 | der,connect,assert,terminate,break,return,%
56 | false,true,and,not,or,%
57 | final,each,%
58 | flow,stream,%
59 | input,output,%
60 | discrete,parameter,constant,%
61 | },
62 | morekeywords=[2]{% Keywords used to define code structure
63 | annotation,block,class,connector,constrainedby,%
64 | encapsulated,enumeration,else,elseif,elsewhen,end,%
65 | expandable,extends,external,for,%
66 | function,if,in,inner,initial,import,loop,model,operator,outer,%
67 | package,partial,record,redeclare,replaceable,%
68 | then,type,when,while,within,algorithm,equation,%
69 | protected,public,pure,impure,%
70 | },%
71 | % Note: initial is in both variants - depending on context, use first variant
72 | morekeywords=[3]{% Selected recognized names that are not actual keywords, including:
73 | % 3.7.2 #derivative-and-special-purpose-operators-with-function-syntax
74 | delay,cardinality,homotopy,semiLinear,inStream,actualStream,spatialDistribution,getInstanceName,%
75 | terminal,noEvent,smooth,sample,pre,edge,change,reinit,%
76 | % 3.7.3 #event-related-operators-with-function-syntax (except initial)
77 | previous,hold,subSample,superSample,shiftSample,backSample,noClock,firstTick,interval,%
78 | % 4.8 #predefined-types-and-classes
79 | Real,Integer,Boolean,String,%
80 | % Highlights from #built-in-array-functions
81 | promote,ndims,size,%
82 | % Assorted things from #state-machines -- what about all the other operators in this chapter?
83 | transition,initialState,%
84 | },%
85 | sensitive=true, % just in case
86 | comment=[l]{//}, % comment lines
87 | morecomment=[s]{/*}{*/}, % comment blocs
88 | morestring=[b]{'},
89 | morestring=[b]{"},
90 | }[keywords,comments,strings]
91 |
92 | \lstdefinelanguage[short]{modelica}[]{modelica}{% Language for use with the \lstinline command.
93 | basicstyle=\upshape\ttfamily, % Font size for inline code snippets.
94 | }
95 |
96 | % Special dialect of Modelica to use when there are URLs appearing outside string literals, to avoid the part
97 | % starting with '//' being treated as comment.
98 | \lstdefinelanguage[nocomment]{modelica}[short]{modelica}{%
99 | commentstyle=\upshape\ttfamily, % Camouflage comments as workaround for not being able to remove rest-of-line comment recognition.
100 | }
101 |
102 | % Note: within only a keyword in grammar
103 | \lstdefinelanguage{grammar}{%
104 | basicstyle=\upshape\ttfamily\smallifpdf, % size of fonts used for the code
105 | identifierstyle=\itshape,
106 | alsodigit={-},
107 | breaklines=true,
108 | breakatwhitespace=true,
109 | morekeywords=[1]{%
110 | % Keywords corresponding to morekeywords=[1] for language=modelica
111 | der,connect,assert,terminate,break,return,%
112 | false,true,and,not,or,%
113 | final,each,%
114 | flow,stream,%
115 | input,output,%
116 | discrete,parameter,constant,%
117 | % Keywords corresponding to morekeywords=[2] for language=modelica
118 | annotation,block,class,connector,constrainedby,%
119 | encapsulated,enumeration,else,elseif,elsewhen,end,%
120 | expandable,extends,external,for,%
121 | function,if,in,inner,initial,import,loop,model,operator,outer,%
122 | package,partial,record,redeclare,replaceable,%
123 | then,type,when,while,within,algorithm,equation,%
124 | protected,public,pure,impure,%
125 | },
126 | % Instead of using color to highlight BNF syntactical constructs as below, the production rule names
127 | % are set in italics, so that the syntactical constructs stand out by having upright shape.
128 | % alsoletter={|,\{,\},[,],(,)},
129 | % morekeywords=[2]{|,\{,\},[,],(,)},
130 | morekeywords=[3]{%
131 | letters,%
132 | },
133 | morestring=[b]{"},
134 | stringstyle=\color{keywordcolor1}, % For the grammar, fixed strings and keywords are the same kind of token.
135 | }[keywords,comments,strings]
136 |
137 | % Duplicate this definition here to avoid issue
138 | \lstdefinelanguage{FORTRAN77}{% Define custom language to avoid collision with predefined [77]Fortran.
139 | basicstyle=\upshape\ttfamily\smallifpdf, % size of fonts used for the code
140 | morekeywords=[1]{%
141 | ASSIGN,BACKSPACE,CALL,CHARACTER,%
142 | CLOSE,COMMON,COMPLEX,CONTINUE,DATA,DIMENSION,DO,DOUBLE,%
143 | ELSE,ELSEIF,END,ENDIF,ENDDO,ENTRY,EQUIVALENCE,EXTERNAL,%
144 | FILE,FORMAT,FUNCTION,GO,TO,GOTO,IF,IMPLICIT,%
145 | INQUIRE,INTEGER,INTRINSIC,LOGICAL,%
146 | OPEN,PARAMETER,PAUSE,PRECISION,PRINT,PROGRAM,READ,REAL,%
147 | RETURN,REWIND,STOP,SUBROUTINE,THEN,%
148 | WRITE,SAVE},
149 | morekeywords=[2]{%
150 | ACCESS,BLANK,BLOCK,DIRECT,EOF,ERR,EXIST,%
151 | FMT,FORM,FORMATTED,IOSTAT,NAMED,NEXTREC,NUMBER,OPENED,%
152 | REC,RECL,SEQUENTIAL,STATUS,TYPE,UNFORMATTED,UNIT},
153 | morekeywords=[3]{%
154 | INT,DBLE,CMPLX,ICHAR,CHAR,AINT,ANINT,% left out real
155 | NINT,ABS,MOD,SIGN,DIM,DPROD,MAX,MIN,AIMAG,CONJG,SQRT,EXP,LOG,%
156 | LOG10,SIN,COS,TAN,ASIN,ACOS,ATAN,ATAN2,SINH,COSH,TANH,LGE,LLE,LLT,%
157 | LEN,INDEX},
158 | morekeywords=[4]{AND,EQ,EQV,FALSE,GE,GT,OR,LE,LT,NE,NEQV,NOT,TRUE},%
159 | sensitive=true,
160 | morecomment=[f]*,
161 | morecomment=[f]C,
162 | morecomment=[f]c,
163 | morestring=[d]", % not Fortran-77 standard, but allowed in Fortran-95 %%
164 | morestring=[d]'
165 | }[keywords,comments,strings]
166 |
167 | \lstdefinelanguage[MLS]{C}{% Define new dialect to avoid collision with predefined dialects of C.
168 | basicstyle=\upshape\ttfamily\smallifpdf, % size of fonts used for the code
169 | morekeywords=[1]{%
170 | auto,break,case,char,const,continue,default,do,double,%
171 | else,enum,extern,float,for,goto,if,int,long,register,return,%
172 | short,signed,sizeof,static,struct,switch,typedef,union,unsigned,%
173 | void,volatile,while},
174 | morekeywords=[3]{%
175 | size_t},
176 | sensitive=true,
177 | morecomment=[s]{/*}{*/},
178 | morecomment=[l]//, % nonstandard
179 | morestring=[b]",
180 | morestring=[b]',
181 | moredelim=*[directive]\#,
182 | moredirectives={%
183 | define,elif,else,endif,error,if,ifdef,ifndef,line,%
184 | include,pragma,undef,warning}
185 | }[keywords,comments,strings,directives]
186 |
187 | \lstdefinelanguage{CSS}{
188 | keywords={},
189 | sensitive=true,
190 | morecomment=[l]{//},
191 | morecomment=[s]{/*}{*/},
192 | morestring=[b]',
193 | morestring=[b]",
194 | alsoletter={:},
195 | alsodigit={-}
196 | }
197 |
198 | \lstset{%
199 | backgroundcolor=\color{white}, % choose the background color
200 | mathescape=true,
201 | breaklines=true, % automatic line breaking only at white-space
202 | keepspaces, % don't remove space such as those after closing parenthesis
203 | upquote=true, % Don't turn apostrophe/backtick into single quotation marks.
204 | captionpos=b, % sets the caption-position to bottom
205 | commentstyle=\color{commentcolor}\sffamilyifhtml,
206 | keywordstyle=\color{red}, % Unused keyword style in bright red to make it easy to detect and fix.
207 | keywordstyle=[1]\color{keywordcolor1},
208 | keywordstyle=[2]\color{keywordcolor1}\bfseries,
209 | keywordstyle=[3]\color{keywordcolor3},
210 | stringstyle=\color{black}, % string literal style
211 | language=[short]modelica, % Language that will be used by default, in particluar by plain \lstinline.
212 | showstringspaces=false,
213 | frame=lrtb,
214 | belowskip=0pt,
215 | defaultdialect=[MLS]C,
216 | }
217 |
218 | % Misc math
219 | \newcommand{\ud}{\mathrm{d}}
220 | \newcommand{\udfrac}[3][\@nil]{%
221 | \def\tmp{#1}%
222 | \ifx\tmp\@nnil
223 | \frac{\ud#2}{\ud#3}%
224 | \else
225 | \frac{\ud^{#1}#2}{\ud#3^{#1}}%
226 | \fi%
227 | }
228 | \newcommand{\pdfrac}[3][\@nil]{%
229 | \def\tmp{#1}%
230 | \ifx\tmp\@nnil
231 | \frac{\partial#2}{\partial#3}%
232 | \else
233 | \frac{\partial^{#1}#2}{\partial#3^{#1}}%
234 | \fi%
235 | }
236 | \newcommand{\abs}[1]{\left\lvert #1{} \right\rvert}
237 |
238 | % Text mode additions
239 | \newcommand{\textgreatereq}{$\geq$}
240 | \newcommand{\textlesseq}{$\leq$}
241 | % For simpler links:
242 | \newcommand{\specpull}[1]{\href{https://github.com/modelica/ModelicaSpecification/pull/#1}{\#{#1}}}
243 | \newcommand{\specissue}[1]{\href{https://github.com/modelica/ModelicaSpecification/issue/#1}{\#{#1}}}
244 |
--------------------------------------------------------------------------------
/styleguide.md:
--------------------------------------------------------------------------------
1 | # Modelica Specification style guide
2 |
3 | This is the style guide for the Modelica Specification document.
4 |
5 |
6 | ## Document format and tool chain
7 |
8 | The source format of the document is LaTeX, and the source is processed by both pdfLaTeX and LaTeXML.
9 | It is good to be aware of the LaTeXML implications, but for most contributors and contributions it is considered sufficient to only check that the pdfLaTeX output looks good, the idea being that potential problems should be spotted in the pull request review process.
10 |
11 | The MSL-specific LaTeX macros and environments described in this style guide are defined in either of these two files:
12 | - [preamble.tex](preamble.tex) – Preamble contents for the main document.
13 | - [mlsshared.sty](mlsshared.sty) – Extracted parts of the styling to be shared with other documents that should follow the same style, such as many of the figures.
14 |
15 |
16 | ## Source code formatting
17 |
18 | ### Trailing spaces and empty lines
19 |
20 | There shall be no trailing spaces, and each line (in particular, the last one in the file) shall be terminated by a newline.
21 | There shall be no empty lines at the beginning or end of a file, and there shall never be more than two empty lines in a row.
22 | Use one or two empty lines before sectioning commands such as `\section` or `\subsubsection`, except at the start of a file.
23 | An empty line is recommended also after the non-paragraph sectioning commands.
24 |
25 | Be careful about adding empty lines, as they actually are significant in places such as before list environments (`itemize`, etc).
26 | For example, if the text before a list acts as an introduction, it should be kept tight with the list:
27 | ```
28 | The following holds for slice operations:
29 | \begin{itemize}
30 | \item
31 | …
32 | ```
33 |
34 | ### Hard line breaks within paragraphs
35 |
36 | The document is in ongoing transition to _one sentence per line_ source code formatting.
37 | This means that any modified or new text should have each sentence alone on a single physical line in the source file.
38 |
39 | When a sentence doesn't fit in one screen line, one may take that as a reminder that long sentences can reduce readability of the specification document, and consider breaking the long sentence into shorter ones.
40 | Just keep in mind that the purpose of doing this shall be to improve readability of the specification text, not improve readability of the _one sentence per line_ formatted source code.
41 |
42 | Once we have the physical line breaks in the correct places, the diffs of future changes will become clean and easy to grasp, and merge conflicts much more easily resolved.
43 |
44 | ### Indentation
45 |
46 | When indenting the contents of a LaTeX environment, an indentation of 2 spaces is used.
47 | It is recommended to not add indentation before `\item`:
48 | ```
49 | \begin{itemize}
50 | \item
51 | First are all inputs to the original function, and after all them we will in order append one derivative for each input containing reals.
52 | These common inputs must have the same name, type, and declaration order for the function and its derivative.
53 | \item
54 | The outputs are constructed by starting with an empty list and then in order appending one derivative for each output containing reals.
55 | The outputs must have the same type and declaration order for the function and its derivative.
56 | \end{itemize}
57 | ```
58 |
59 | Many environments are used without indenting the contents, including `nonnormative` and `example`:
60 | ```
61 | \begin{nonnormative}
62 | This means that the most restrictive derivatives should be written first.
63 | \end{nonnormative}
64 | ```
65 |
66 | ## Formatting of language terminology
67 |
68 | ### Things with name/keyword in the language
69 |
70 | As a general rule, when a concept is directly related to a construct in the Modelica language with a certain name/keyword, then the language concept is referred to using a hyphenated combination of the language name/keyword in code style, with a qualifying natural language word written as normal text.
71 | Annotations are an exception to this rule.
72 | Examples:
73 |
74 | Appearance | LaTeX source | Comment
75 | --- | --- | ---
76 | `connect`-equation | `\lstinline!connect!-equation` |
77 | `inverse` annotation | `\lstinline!inverse! annotation` |
78 | `if`-equation | `\lstinline!if!-equation` |
79 | `if`-expression | `\lstinline!if!-expression` |
80 | `when`-clause | `\lstinline!when!-clause` | A branch of a `when`-equation or `when`-statement
81 | `import`-clause | `\lstinline!import!-clause` |
82 | `for`-equation | `\lstinline!for!-equation` |
83 | `for`-statement | `\lstinline!for!-statement` |
84 | `for`-loop | `\lstinline!for!-loop` | A `for`-equation or `for`-statement
85 | `start`-attribute | `\lstinline!start!-attribute` |
86 |
87 | Note that there's often an associated rule in the Modelica grammar, which should only be used in the text on the rare occasions when it is the actual grammar rule – not the entire language concept – that is being referenced:
88 |
89 | Appearance | LaTeX source
90 | --- | ---
91 | `if-equation` | `\lstinline[language=grammar]!if-equation!`
92 |
93 | Note: The hyphenation may sometimes appear grammatically incorrect, but the consistent use of hyphenation helps readability, and in some contexts the hyphen gives extra safety against reading the language name/keyword as part of the sentence structure.
94 | For example, compare:
95 | - If equations are possible to simplify if their condition can be evaluated during translation.
96 | - `if`-equations are possible to simplify if their condition can be evaluated during translation.
97 |
98 | ### Expressions
99 |
100 | Different constructs with _expression_ and _call_:
101 |
102 | Appearance | LaTeX source | Comment
103 | --- | --- | ---
104 | `if`-expression | `\lstinline!if!-expression` | Generic language concept
105 | parameter-expression | `parameter-expression` | Expression with parameter variability
106 | `Real` expression | `\lstinline!Real! expression` | Expression of type `Real`
107 | array expression | `array expression` | Expression of array type
108 | record expression | `record expression` | Expression of record type
109 | `y` expression | `\lstinline!y! expression` | Expression for something named `y`
110 | `convertElement` call | `\lstinline!convertElement! call` | A call expression with callee `convertElement`
111 |
112 | In particular, avoid other combinations of inline code and _expression_ than the variants above.
113 | For other needs, try to find a formulation not based on _expression_ to avoid misinterpretations according to the variants above.
114 | For example, instead of saying "… can be dependent on class variables using the `DynamicSelect` expression", just say "… can be dependent on class variables using `DynamicSelect`".
115 |
116 | Note: There is no need for hyphenation of "`convertElement` call" since we don't say "`Real` call" for a call expression of type `Real` (we have "`Real` expression" for this purpose).
117 |
118 | ### The keywords themselves
119 |
120 | When referencing a keyword itself, hyphenation is not used, and when possible, a better describing word than _keyword_ is used:
121 |
122 | Appearance | LaTeX source | Comment
123 | --- | --- | ---
124 | the `input` prefix | `\lstinline!prefix! prefix` | For more prefixes, see `class-prefixes`, `base-prefix`, and `type-prefix` in the grammar.
125 | the `final` modifier | `the \lstinline!final! modifier` |
126 | the `each` keyword | `the \lstinline!each! keyword` |
127 |
128 | Depending on context, one can also swap the order, or drop the describing word completely:
129 |
130 | Appearance | LaTeX source
131 | --- | ---
132 | the keyword `each` | `the keyword \lstinline!each!`
133 | declared as `final` | `declared as \lstinline!final!`
134 |
135 | ### Named functions and operators
136 |
137 | When referencing a named function of operator, hyphenation is not used, and it is common to not combine with any describing word:
138 |
139 | Appearance | LaTeX source
140 | --- | ---
141 | the `smooth` operator | `the \lstinline!smooth! operator`
142 | where `pre` is not explicitly used | `where \lstinline!pre! is not explicitly used`
143 |
144 | ### Other things, special cases
145 |
146 | Incomplete list of various terminology with special formatting rules:
147 |
148 | Appearance | LaTeX source | Comment
149 | --- | --- | ---
150 | start value | `start value` | Value of the `start`-attribute (there could be exceptions!)
151 | connection equation | `connection equation` | Equation generated from analysis of `connect`-equations
152 | reduction expression | `reduction expression` |
153 | base class | `base class` | Similarly: derived class
154 | base-clock | `base-clock` | Similarly: sub-cock
155 |
156 | ## Definitions
157 |
158 | New terminology is either introduced with a `definition` environment, or as part of the running text.
159 | When part of the running text, the introduced terminology should be marked with `\firstuse` at the point of the definition.
160 | As a general rule, terminology introduced with `\firstuse` should appear in the document index, and by default the mandatory argument to `\firstuse` is automatically passed to `\index`.
161 | To change the appearance of the index entry, the default may be overridden using an optional argument to `\firstuse`, for example, `\firstuse[array!variable]{array variable}`.
162 | This is also useful when capitalization or plural/singular differs; except for things like names, lower case should be used in the index, and terms should typically appear in the singular, for example, `\firstuse[vector]{Vectors}`.
163 | On rare occasions, one just wants the standardized typesetting of `\firstuse` but no entry in the index, which can be achieved by passing an em-dash for the optional argument, for example, \firstuse[---]{constant}.
164 | When suppressing the appearnce in the index, it is recommended to add a comment in the source explaining why.
165 | It is common that the use of `\firstuse` is directly followed by additional calls to `\index` for adding the terminology in more variants to the document index.
166 |
167 | If the new terminology is used before being introduced, it should be marked with `\willintroduce` (instead of `\firstuse`) to alert the reader that this is not a term that is expected to be known yet by a first-time reader.
168 |
169 | ## Miscellaneous
170 |
171 | ### Use of `\emph` and italics
172 |
173 | To put emphasis on a word or small piece of text, use `\emph`.
174 |
175 | Italics is used via the semantic macros `\firstuse` and `\willintroduce` when new terminology is introduced in the running text instead of the bulkier `definition` environment.
176 |
177 | Refrain from using non-semantical font switching commands for producing italics (`\textit`, `\textsl`, `\itshape`).
178 |
179 | Note that the document is full of text set in italics, since this is used for both non-normative text and examples, through the `nonnormative` and `example` environments.
180 |
181 | ### Use of boldface
182 |
183 | Non-semantical font switching commands for producing boldface (`\textbf`, `\bfseries`) may only be used for styling as part of higher level semantic constructs such as the _amsthm.sty_ `\newtheoremstyle` definitions.
184 | For purposes of marking emphasis, see use of `\emph` instead.
185 |
186 | ### Ordinals
187 |
188 | Ordinals are written with _th_ in normal font, possibly combined with a math styled expression for the number:
189 | ```
190 | Fixed ordinals: 1st, 2nd, 3rd.
191 | Symbolic ordinals: $n$th, $(n+1)$th.
192 | ```
193 |
194 | ## Inline code
195 |
196 | Inline code is typically formatted using just the `\lstinline` macro.
197 |
198 | Since the change of type face can be very hard to notice for small code fragments, single quotes may sometimes be used to emphasize the distinction from the surrounding text, unless the code fragment consists of a single identifier (consistent presentation of identifiers is given higher priority than clarity of presentation in this case).
199 | For example:
200 | ```
201 | … and prepending the reduction expression with ``\lstinline!functionName(!''.
202 | ```
203 |
204 | Avoid overusing quotes around code fragments, especially for multi-letter fragments.
205 |
206 | ## Code listings
207 |
208 | ### Modelica listings
209 |
210 | Modelica listings are written with indentation in steps of 2 spaces.
211 |
212 | A space is typically added on each side of a binary operator, and after comma.
213 |
214 | Code snippets may start with an indented line as long as there's some line in the listing with zero indentation, like this:
215 | ```
216 | Real x(start = 1.0, fixed = true);
217 | equation
218 | der(x) = -x;
219 | ```
220 |
221 | Each line should fit within the width of the page.
222 | Use hard line breaks and manual additional indentation of continued lines to meet this requirement.
223 | A semicolon in a matrix should either be followed by a line break or by a space.
224 |
225 | ### Grammar (extended BNF) listings
226 |
227 | Grammar listings use the `language=grammar`, and are written with indentation in steps of 3 spaces:
228 | ```
229 | \begin{lstlisting}[language=grammar]
230 | stored-definition :
231 | [ within [ name ] ";" ]
232 | { [ final ] class-definition ";" }
233 | \end{lstlisting}
234 | ```
235 |
236 | When a grammar rule is mentioned in the text, the rule shall be formatted with the _grammar_ language:
237 | ```
238 | The node shall contain a \lstinline[language=grammar]!stored-definition! that…
239 | ```
240 |
241 | ## English natural language text
242 |
243 | This section gives guidelines for how the natural language text in English should be written.
244 |
245 | The text is written in American English.
246 |
247 | ### Contractions
248 |
249 | Avoid contractions such as _isn't_ or _won't_; write _is not_ or _will/would not_ instead.
250 |
251 | ### Inline code at beginning of sentence
252 |
253 | When a sentence starts with inline code,
254 | > `import`-clauses are not inherited.
255 |
256 | this may be rewritten using _The_ inserted before the inline code to avoid a lower case letter at the beginning of the sentence:
257 |
258 | > The `import`-clauses are not inherited.
259 |
260 | ### Wrap punctuations around some abbreviations
261 |
262 | Always use comma (or colon if the following text starts on new line) _after_ "e.g." and "i.e."; and use comma or some other punctuation such as "(", "--", or "." before them.
263 | This also avoids the need to guard the space after the dot.
264 |
--------------------------------------------------------------------------------
2 | 
3 |
4 | # ModelicaSpecification
5 | This repository contains the Modelica Language Specification, hosted at https://github.com/modelica/ModelicaSpecification.
6 | Development is organized within the [Modelica Association Project Language (MAP-Lang)](https://modelica.org/projects) according to the [project rules](https://github.com/modelica/MAP-Lang_ProjectRules/blob/main/MAP-Lang-ProjectRules.md).
7 |
8 | ## Description
9 |
10 | Modelica® is a language for modeling of cyber-physical systems, supporting acausal connection of components governed by mathematical equations to facilitate modeling from first principles.
11 | It provides object-oriented constructs that facilitate reuse of models, and can be used conveniently for modeling complex systems containing, e.g., mechanical, electrical, electronic, magnetic, hydraulic, thermal, control, electric power or process-oriented subcomponents.
12 |
13 | ## Releases
14 |
15 | Version | Link | Published | Changes |
16 | ------- | ----------------------------------------------------------------- | --------| ---|
17 | 3.7-dev | [Master branch](https://github.com/modelica/ModelicaSpecification/tree/master) [HTML](https://specification.modelica.org/master/) [PDF](https://specification.modelica.org/master/MLS.pdf)| not yet | [Search](https://github.com/modelica/ModelicaSpecification/issues?q=label%3AM37+is%3Aclosed) |
18 | 3.6 | [3.6 branch](https://github.com/modelica/ModelicaSpecification/tree/maint/3.6) [HTML](https://specification.modelica.org/maint/3.6/MLS.html) [PDF](https://specification.modelica.org/maint/3.6/MLS.pdf)| 2023 | [Search](https://github.com/modelica/ModelicaSpecification/issues?q=label%3AM36+is%3Aclosed) [HTML](https://specification.modelica.org/maint/3.6/modelica-revision-history.html#modelica-3-6) |
19 | 3.5 | [3.5 branch](https://github.com/modelica/ModelicaSpecification/tree/maint/3.5) [HTML](https://specification.modelica.org/maint/3.5/MLS.html) [PDF](https://specification.modelica.org/maint/3.5/MLS.pdf)| 2021 | [HTML](https://specification.modelica.org/maint/3.6/modelica-revision-history.html#modelica-3-5) |
20 | 3.4 | [3.4 branch](https://github.com/modelica/ModelicaSpecification/tree/maint/3.4) [HTML](https://specification.modelica.org/maint/3.4/MLS.html) [PDF](https://modelica.org/documents/ModelicaSpec34.pdf) | 2017 | [HTML](https://specification.modelica.org/maint/3.6/modelica-revision-history.html#modelica-3-4) |
21 | 3.3rev1 | [PDF](https://modelica.org/documents/ModelicaSpec33Revision1.pdf) | 2014 | [HTML](https://specification.modelica.org/maint/3.6/modelica-revision-history.html#modelica-3-3-revision-1) |
22 | 3.2rev2 | [PDF](https://modelica.org/documents/ModelicaSpec32Revision2.pdf) | 2013 | [HTML](https://specification.modelica.org/maint/3.6/modelica-revision-history.html#modelica-3-2-revision-2) |
23 | 3.2rev1 | [PDF](https://modelica.org/documents/ModelicaSpec32Revision1.pdf) | 2012 | [HTML](https://specification.modelica.org/maint/3.6/modelica-revision-history.html#modelica-3-2-revision-1) |
24 | 3.3 | [PDF](https://modelica.org/documents/ModelicaSpec33.pdf) | 2012 | [HTML](https://specification.modelica.org/maint/3.6/modelica-revision-history.html#modelica-3-3) |
25 | 3.2 | [PDF](https://modelica.org/documents/ModelicaSpec32.pdf) | 2010 | [HTML](https://specification.modelica.org/maint/3.6/modelica-revision-history.html#modelica-3-2) |
26 | 3.1 | [PDF](https://modelica.org/documents/ModelicaSpec31.pdf) | 2009 | [HTML](https://specification.modelica.org/maint/3.6/modelica-revision-history.html#modelica-3-1) |
27 | 3.0 | [PDF](https://modelica.org/documents/ModelicaSpec30.pdf) | 2007 | [HTML](https://specification.modelica.org/maint/3.6/modelica-revision-history.html#modelica-3-0) |
28 | 2.2 | [PDF](https://modelica.org/documents/ModelicaSpec22.pdf) | 2005 | [HTML](https://specification.modelica.org/maint/3.6/modelica-revision-history.html#modelica-2-2) |
29 | 2.1 | [PDF](https://modelica.org/documents/ModelicaSpec21.pdf) | 2004 | [HTML](https://specification.modelica.org/maint/3.6/modelica-revision-history.html#modelica-2-1) |
30 | 2.0 | [PDF](https://modelica.org/documents/ModelicaSpec20.pdf) | 2002 | [HTML](https://specification.modelica.org/maint/3.6/modelica-revision-history.html#modelica-2-0) |
31 | 1.4 | [PDF](https://modelica.org/documents/ModelicaSpec14.pdf) | 2000 | [HTML](https://specification.modelica.org/maint/3.6/modelica-revision-history.html#modelica-1-4) |
32 | 1.3 | [PDF](https://modelica.org/documents/ModelicaSpec13norev.pdf) | 1999 | [HTML](https://specification.modelica.org/maint/3.6/modelica-revision-history.html#modelica-1-3) |
33 | 1.2 | [PDF](https://modelica.org/documents/modelicaspec12norev.pdf) | 1999 | [HTML](https://specification.modelica.org/maint/3.6/modelica-revision-history.html#modelica-1-2) |
34 | 1.1 | [PDF](https://modelica.org/documents/ModelicaSpec11.pdf) | 1998 | [HTML](https://specification.modelica.org/maint/3.6/modelica-revision-history.html#modelica-1-1) |
35 | 1.0 | [PDF](https://modelica.org/documents/Modelica1.pdf) | 1997 | |
36 |
37 | ## Contribution
38 | 1. If you find an error and are not certain that you can correct it, first check that it is not already reported and then open an [issue](https://github.com/modelica/ModelicaSpecification/issues) describing it in detail - focusing on why it should be changed.
39 | 2. If you are confident that you can correct the issue, fork this repository and create a pull-request and in the pull-request explain the issue and the correction; you will also have to sign a CLA.
40 | 3. Significant extensions are handled as Modelica Change Proposals (MCPs). This can start as a simple description of the proposed extension. It will then be worked on to have a rationale explaining how the change help users, and demonstrating that it can be implemented efficiently; and finally a pull-request with the changes.
41 |
42 | For more details, see the [Development Process](https://github.com/modelica/ModelicaSpecification/blob/master/RationaleMCP/DevelopmentProcess.md).
43 | A list of MCPs can be found here: [RationaleMCP](https://github.com/modelica/ModelicaSpecification/tree/master/RationaleMCP).
44 |
45 | CLA: Contributor's license agreement. (Details to follow.)
46 |
47 | How to edit and generate final documents
48 | * Read the [style guide](styleguide.md).
49 | * For online editing you can use www.overleaf.com (details to follow)
50 | * The pdf-documents are generated with pdflatex, which is part of most LaTeX installations, we used http://miktex.org/download
51 | * The HTML-documents are generated with LaTeXML. That is more complicated to install - and can optionally be skipped:
52 | 1. First you need perl, we used http://strawberryperl.com/
53 | 2. And then the official LaTeXML package (0.8.5 or later): http://dlmf.nist.gov/LaTeXML/get.html#SS4.SSS0.Px1 or https://github.com/brucemiller/LaTeXML
54 | 3. The exact commands are in the Makefile
55 |
56 | It is also possible to get a preview in the pull request.
57 | There will be a link to the [status check](https://test.openmodelica.org/jenkins/job/ModelicaAssociation/job/ModelicaSpecification/view/change-requests/), which checks that the documents can be generated and gives you an option to download them.
58 |
--------------------------------------------------------------------------------
/RationaleMCP/0009/README.md:
--------------------------------------------------------------------------------
1 | Modelica Change Proposal MCP-0009
2 |
3 | Removing Modifications
4 |
5 | Hans Olsson, Gerd Kurzbach, Hilding Elmqvist, Martin Otter, Michael Tiller
6 | (In Development)
7 |
8 |
9 | # Summary
10 | This MCP proposes a possibility to remove existing, in particular inherited, modifications.
11 |
12 | # Revisions
13 | | Date | Description |
14 | | --- | --- |
15 | | 2013-12-07 | Initial Draft under the name MCPI-0009_UndefinedModifications by Gerd Kurzbach (initial idea is from Hilding Elmqvist; contributions from Martin Otter and Michael Tiller to this draft are included).| |
16 | | 2014-06-14 | Update. Added corrections and results from discussions (#1377), clarifications and other proposals|
17 | | 2018-03-23 | Second Version with changed name, simplified and streamlined, no more related to custom annotations MCP-0008|
18 | | 2021-03-17 | Converted to markdown, by Hans Olsson and added new syntax-variant from Gerd Kurzbach |
19 | | 2021-03-18 | Hans Olsson - added experience from Dymola |
20 | | 2021-03-24 | Hans Olsson - feedback on prototype |
21 | | 2021-05-03 | Hans Olsson - additional feedback on prototype |
22 | | 2021-05-05 | Hans Olsson - feedback at language meeting |
23 | | 2021-06-16 | Hans Olsson - removed `