Skip to content

Commit cdd9d03

Browse files
AnHeuermannAnHeuermann
authored
Formatted README.md (#236)
- Less warnings from my Markdown linter - Updating a few links
1 parent 85977ba commit cdd9d03

File tree

1 file changed

+163
-109
lines changed

1 file changed

+163
-109
lines changed

‎README.md‎

Lines changed: 163 additions & 109 deletions
Original file line numberDiff line numberDiff line change
@@ -3,129 +3,180 @@
33
[![Continuous Integration](https://github.com/OpenModelica/OpenModelicaLibraryTesting/actions/workflows/test.yml/badge.svg)](https://github.com/OpenModelica/OpenModelicaLibraryTesting/actions/workflows/test.yml)
44
[![License: OSMC-PL](https://img.shields.io/badge/license-OSMC--PL-lightgrey.svg)](OSMC-License.txt)
55

6-
This repository provides scripts and documentation to run the nightly Modelica library tests for OpenModelica.
6+
This repository provides scripts and documentation to run the nightly Modelica
7+
library tests for OpenModelica.
78

89
## OpenModelica nightly testsuite
910

10-
Some of the open-source Modelica libraries managed by the [Open Modelica Package Manager](https://github.com/OpenModelica/OMPackageManager) are tested on a daily basis on the OSMC servers.
11-
12-
[Test results reports](testresults.md#open-source-modelica-library-testing-using-openmodelica) are publicly available.
13-
14-
The configuration file for the regular library nightly testsuite is [conf.json](configs/conf.json). Additional old and non-standard libraries are listed in [conf-old.json](configs/conf-old.json) and [conf-nonstandard.json](configs/conf-nonstandard.json), note that failures in those libraries may be due to the fact that they are not fully complying with the Modelica standard, rather than to OpenModelica issues. The setup of the configuration files is discussed in [conf-howto.md](conf-howto.md).
15-
16-
Test results reports are collected in the https://libraries.openmodelica.org/branches/ directory. The [overview.html](https://libraries.openmodelica.org/branches/overview.html) report gives the results of the regular testsuite with the default C runtime and solvers. Other reports contain the results using the C++ runtime, FMI, daeMode, and the old frontend. Combined reports also include results from the old and nonstandard libraries. The https://libraries.openmodelica.org/branches/history/ directory contains regression reports and plots using different versions (including master) and simulation runtime configurations (C++, daeMode, FMI, old frontend) of OpenModelica.
17-
18-
If you want to include your open-source library in the testsuite, please open a pull request on [conf.json](configs/conf.json), or open an issue on the [OpenModelica issue tracker](https://github.com/OpenModelica/OpenModelica/issues/new/choose) and ask us to do it for you.
11+
Some of the open-source Modelica libraries managed by the
12+
[Open Modelica Package Manager](https://github.com/OpenModelica/OMPackageManager)
13+
are tested on a daily basis on the OSMC servers.
14+
15+
[Test results reports](testresults.md#open-source-modelica-library-testing-using-openmodelica)
16+
are publicly available.
17+
18+
The configuration file for the regular library nightly testsuite is
19+
[conf.json](configs/conf.json). Additional old and non-standard libraries are
20+
listed in [conf-old.json](configs/conf-old.json) and
21+
[conf-nonstandard.json](configs/conf-nonstandard.json), note that failures in
22+
those libraries may be due to the fact that they are not fully complying with
23+
the Modelica standard, rather than to OpenModelica issues. The setup of the
24+
configuration files is discussed in [conf-howto.md](conf-howto.md).
25+
26+
Test results reports are collected in the
27+
[https://libraries.openmodelica.org/branches/](libraries.openmodelica.org/branches)
28+
directory. The
29+
[overview.html](https://libraries.openmodelica.org/branches/overview.html)
30+
report gives the results of the regular testsuite with the default C runtime and
31+
solvers. Other reports contain the results using the C++ runtime, FMI, daeMode,
32+
and the old frontend. Combined reports also include results from the old and
33+
nonstandard libraries. The
34+
[https://libraries.openmodelica.org/branches/history/](libraries.openmodelica.org/branches/history)
35+
directory contains regression reports and plots using different versions
36+
(including master) and simulation runtime configurations (C++, daeMode, FMI, old
37+
frontend) of OpenModelica.
38+
39+
If you want to include your open-source library in the testsuite, please open a
40+
pull request on [conf.json](configs/conf.json), or open an issue on the
41+
OpenModelica
42+
[issue tracker](https://github.com/OpenModelica/OpenModelica/issues/new/choose)
43+
and ask us to do it for you.
1944

2045
## Running the library testing infrastructure on your own server
2146

22-
The scripts from this repository can be used to run regression tests for public, private, and commercial Modelica libraries to keep track of coverage with different OpenModelica versions, according to the conditions of the [OSMC-PL license](OSMC-License.txt).
47+
The scripts from this repository can be used to run regression tests for public,
48+
private, and commercial Modelica libraries to keep track of coverage with
49+
different OpenModelica versions, according to the conditions of the
50+
[OSMC-PL license](OSMC-License.txt).
2351

2452
### Dependencies
2553

26-
- [OpenModelica](https://openmodelica.org)
27-
- [Python](https://www.python.org/)
28-
- (Optional) Reference simulation result files
54+
- [OpenModelica](https://openmodelica.org)
55+
- [Python](https://www.python.org/)
56+
- (Optional) Reference simulation result files
2957

3058
### Set-Up
3159

32-
- Install or build OpenModelica
33-
- [Install instructions](https://openmodelica.org/download/download-linux)
34-
- [Build instructions](https://github.com/OpenModelica/OpenModelica#readme)
35-
- Make sure `omc` is in your `PATH`
36-
- Install Python requirements
37-
```bash
38-
pip install -r requirements.txt
39-
```
40-
- OMC will search for libraries in the location provided with test.py argument `--libraries`.
41-
The default value is `/home/username/.openmodelica/libraries/` (Linux) or `%APPDATA%/.openmodelica/libraries` (Windows).
42-
- Install your libraries into the location specified with `--libraries`
43-
or use `loadFile` command inside `loadFileCommands` in the config JSON:
44-
```yml
45-
"loadFileCommands": [
46-
"loadFile(\"/path/to/package.mo\")"
47-
]
48-
```
49-
- Create configs/myConf.json to specify what libraries to test.
50-
```json
51-
[
52-
{
53-
"library":"MyModelicaLibrary",
54-
"libraryVersion":"main",
55-
"libraryVersionExactMatch":true, // to be sure that the exact version is loaded, not the latest compatible
56-
"libraryVersionLatestInPackageManager":true, // load the latest from the package manager
57-
"referenceFileExtension":"mat",
58-
"referenceFileNameDelimiter":"/",
59-
"referenceFileNameExtraName":"$ClassName",
60-
"referenceFiles": "/path/to/some/SomeDirectory", // specifies a directory with the files
61-
"referenceFiles": "$ENV_VAR/SomeDirectory", // specifies a directory with the files via an env var
62-
"referenceFiles":{ // specified as an URL, directory destination, git branch and git directory
63-
"giturl":"https://github.com/myName/MyModelicaLibrary-ref",
64-
"destination":"ReferenceFiles/MyModelicaLibrary",
65-
"git-ref": "main",
66-
"git-directory": "ReferenceFiles"
67-
},
68-
"defaultTolerance": 1e-6, // tolerance for tests if not specified by the model, defaults to 1e-6
69-
"defaultNumberOfIntervals": 2500, // number of intervals for tests if not specified by the model, defaults to 2500
70-
"ulimitOmc":800, // specify a max timeout for a model build
71-
"ulimitExe":300, // specify a max timeout for a model simulation
72-
"ulimitMemory":62000000, // specify a max for the virtual memory of the running process when building a model
73-
"procOMC":0, // [if procOMC = 0 use max procs, use procOMC = 1 if not defined, else use the given value] how many CPU cores should be used to run omc (load Modelica libraries in parallel and generate the C code in parallel)
74-
"procCCompile":0, // [if procCCompile = 0 use max procs, use procCCompile = 1 if not defined, else use the given value] how many CPU cores should be used to compile the generated code
75-
"optlevel":"-Os -march=native" // what optimizations should be used by the C compiler
76-
}
60+
- Install or build OpenModelica
61+
- [Install instructions](https://openmodelica.org/download/download-linux)
62+
- [Build instructions](https://github.com/OpenModelica/OpenModelica#readme)
63+
- Make sure `omc` is in your `PATH`
64+
- Install Python requirements
65+
66+
```bash
67+
pip install -r requirements.txt
68+
```
69+
70+
- OMC will search for libraries in the location provided with test.py argument
71+
`--libraries`. The default value is `/home/username/.openmodelica/libraries/`
72+
(Linux) or `%APPDATA%/.openmodelica/libraries` (Windows).
73+
- Install your libraries into the location specified with `--libraries`
74+
or use `loadFile` command inside `loadFileCommands` in the config JSON:
75+
76+
```yml
77+
"loadFileCommands": [
78+
"loadFile(\"/path/to/package.mo\")"
7779
]
7880
```
7981

80-
You can add extra compiler settings
81-
82-
```json
83-
"extraCustomCommands":["setCommandLineOptions(\"--std=3.2\");"]
84-
```
85-
and extra simulation flags
86-
87-
```json
88-
"extraSimFlags": "-s=ida -nls=kinsol"
89-
```
82+
- Create configs/myConf.json to specify what libraries to test.
83+
84+
```json
85+
[
86+
{
87+
"library":"MyModelicaLibrary",
88+
"libraryVersion":"main",
89+
"libraryVersionExactMatch":true, // to be sure that the exact version is loaded, not the latest compatible
90+
"libraryVersionLatestInPackageManager":true, // load the latest from the package manager
91+
"referenceFileExtension":"mat",
92+
"referenceFileNameDelimiter":"/",
93+
"referenceFileNameExtraName":"$ClassName",
94+
"referenceFiles": "/path/to/some/SomeDirectory", // specifies a directory with the files
95+
"referenceFiles": "$ENV_VAR/SomeDirectory", // specifies a directory with the files via an env var
96+
"referenceFiles":{ // specified as an URL, directory destination, git branch and git directory
97+
"giturl":"https://github.com/myName/MyModelicaLibrary-ref",
98+
"destination":"ReferenceFiles/MyModelicaLibrary",
99+
"git-ref": "main",
100+
"git-directory": "ReferenceFiles"
101+
},
102+
"defaultTolerance": 1e-6, // tolerance for tests if not specified by the model, defaults to 1e-6
103+
"defaultNumberOfIntervals": 2500, // number of intervals for tests if not specified by the model, defaults to 2500
104+
"ulimitOmc":800, // specify a max timeout for a model build
105+
"ulimitExe":300, // specify a max timeout for a model simulation
106+
"ulimitMemory":62000000, // specify a max for the virtual memory of the running process when building a model
107+
"procOMC":0, // [if procOMC = 0 use max procs, use procOMC = 1 if not defined, else use the given value] how many CPU cores should be used to run omc (load Modelica libraries in parallel and generate the C code in parallel)
108+
"procCCompile":0, // [if procCCompile = 0 use max procs, use procCCompile = 1 if not defined, else use the given value] how many CPU cores should be used to compile the generated code
109+
"optlevel":"-Os -march=native" // what optimizations should be used by the C compiler
110+
}
111+
]
112+
```
113+
114+
You can add extra compiler settings
115+
116+
```json
117+
"extraCustomCommands":["setCommandLineOptions(\"--std=3.2\");"]
118+
```
119+
120+
and extra simulation flags
121+
122+
```json
123+
"extraSimFlags": "-s=ida -nls=kinsol"
124+
```
125+
126+
Check [configs/conf.json](./configs/conf.json) for more.
127+
- If you used [.CI/installLibraries.mos](./.CI/installLibraries.mos) to test all
128+
libraries you'll need to install reference results and set environment
129+
variables, see [Reference Results](#reference-results).
130+
131+
```bash
132+
export MSLREFERENCE="/path/to/ReferenceFiles/"
133+
export REFERENCEFILES="/path/to/OpenModelica/testsuite/ReferenceFiles"
134+
export PNLIBREFS="/path/to/ReferenceFiles/PNlib/ReferenceFiles"
135+
export THERMOFLUIDSTREAMREFS="/path/to/ReferenceFiles/ThermofluidStream-main-regression/ReferenceData"
136+
export THERMOFLUIDSTREAMREFSOM="/path/to/ReferenceFiles/ThermofluidStream-OM-regression/ReferenceData"
137+
```
138+
139+
### Library Test
140+
141+
Run the library test:
90142

91-
Check `config/conf.json` for more.
92-
- If you used `.CI/installLibraries.mos` to test all libraries you'll need to install reference results and set environment variables, see [Reference Results](#reference-results).
93-
```bash
94-
export MSLREFERENCE="/path/to/ReferenceFiles/"
95-
export REFERENCEFILES="/path/to/OpenModelica/testsuite/ReferenceFiles"
96-
export PNLIBREFS="/path/to/ReferenceFiles/PNlib/ReferenceFiles"
97-
export THERMOFLUIDSTREAMREFS="/path/to/ReferenceFiles/ThermofluidStream-main-regression/ReferenceData"
98-
export THERMOFLUIDSTREAMREFSOM="/path/to/ReferenceFiles/ThermofluidStream-OM-regression/ReferenceData"
99-
```
143+
```bash
144+
./test.py --noclean configs/myConf.json
145+
```
100146

101-
- Run the library test
102-
```bash
103-
./test.py --noclean configs/myConf.json
104-
```
105-
Use `configs/*.json` to specify what to test.
106-
The test results are saved in `sqlite3.db`.
107-
108-
Options:
109-
- `--branch=master`: Branch of OpenModelica
110-
- `--fmi=False`: Test FMI
111-
- `--output=''`: Result location
112-
- `--libraries=~/.openmodelica/libraries/`: Location of Modelica libraries
113-
- `--extraflags=''`: Extra compiler flags.
114-
- `--extrasimflags=''`: Extra simulation flags.
115-
- `--ompython_omhome=''`: Path to OpenModelica for OMPython (can be different to the OM running the tests)
116-
- `--noclean=False`: Clean (most) generated files.
117-
- `--fmisimulator=''`: The default is nothing but you can use the path to OMSimulator executable or 'fmpy'
118-
- `--ulimitvmem=8388608`: Virtual memory limit (in kB)
119-
- `--default=[]`: Add a default value for some configuration key, such as --default=ulimitExe=60. The equals sign is mandatory
120-
- `-j`,`--jobs`: Number of cores to use for testing, default is 0 (max cores), use 1 to run serial (for large tests) and see procOMC and procCCompile above for more insight into individual test parallelization
121-
122-
- Generate HTML results
123-
```bash
124-
./report.py configs/myConf.json
125-
```
126-
- Upload and backup
127-
- Upload HTML files somewhere
128-
- backup sqlite3.db
147+
Use `configs/*.json` to specify what to test.
148+
The test results are saved in `sqlite3.db`.
149+
150+
Options:
151+
152+
- `--branch=master`: Branch of OpenModelica
153+
- `--fmi=False`: Test FMI
154+
- `--output=''`: Result location
155+
- `--libraries=~/.openmodelica/libraries/`: Location of Modelica libraries
156+
- `--extraflags=''`: Extra compiler flags.
157+
- `--extrasimflags=''`: Extra simulation flags.
158+
- `--ompython_omhome=''`: Path to OpenModelica for OMPython (can be different to
159+
the OM running the tests)
160+
- `--noclean=False`: Clean (most) generated files.
161+
- `--fmisimulator=''`: The default is nothing but you can use the path to
162+
OMSimulator executable or 'fmpy'
163+
- `--ulimitvmem=8388608`: Virtual memory limit (in kB)
164+
- `--default=[]`: Add a default value for some configuration key, such as
165+
`--default=ulimitExe=60`. The equals sign is mandatory
166+
- `-j`,`--jobs`: Number of cores to use for testing, default is `0` (max cores),
167+
use `1` to run serial (for large tests) and see `procOMC` and
168+
`procCCompile` above for more insight into individual test
169+
parallelization.
170+
171+
### Generate HTML results
172+
173+
```bash
174+
./report.py configs/myConf.json
175+
```
176+
177+
- Upload and backup
178+
- Upload HTML files somewhere
179+
- backup sqlite3.db
129180

130181
### Reference Results
131182

@@ -135,13 +186,15 @@ download the reference files and make them available by
135186
defining `MSLREFERENCE` and `REFERENCEFILES`.
136187

137188
Some result file locations:
138-
- Modelica Association: https://github.com/modelica/MAP-LIB_ReferenceResults
139-
- PNLib: https://github.com/AMIT-FHBielefeld/PNlib
140-
- DLR-SR: https://github.com/DLR-SR/ThermoFluidStream-Regression.git and https://github.com/DLR-SR/PlanarMechanics_ReferenceResults.git
141189

190+
- Modelica Association: [https://github.com/modelica/MAP-LIB_ReferenceResults](modelica/MAP-LIB_ReferenceResults)
191+
- PNLib: [https://github.com/AMIT-HSBI/PNlib](AMIT-HSBI/PNlib)
192+
- DLR-SR: [https://github.com/DLR-SR/ThermoFluidStream-Regression](DLR-SR/ThermoFluidStream-Regression)
193+
and [https://github.com/DLR-SR/PlanarMechanics_ReferenceResults](DLR-SR/PlanarMechanics_ReferenceResults)
142194

143195
To download the MSL reference files create a file
144196
installReferenceResults.sh with
197+
145198
```sh
146199
#!/bin/sh
147200
@@ -168,6 +221,7 @@ done
168221
```
169222

170223
and run it
224+
171225
```bash
172226
chmod a+rx installReferenceResults.sh
173227
./installReferenceResults.sh

0 commit comments

Comments
 (0)