Merge branch 'release/v0.2.2'

CATIA-Systems · Mar 13, 2018 · a46c772 · a46c772
2 parents 5cf66f1 + 4cb3f7f
commit a46c772
Show file tree

Hide file tree

Showing 21 changed files with 585 additions and 110 deletions.
diff --git a/.gitignore b/.gitignore
@@ -18,3 +18,6 @@ MANIFEST
 
 # file-based project format
 *.iws
+
+# generated documentation
+_build
diff --git a/CHANGELOG.md b/CHANGELOG.md
diff --git a/README.md b/README.md
@@ -27,7 +27,7 @@ If you don't have Python on your machine you can install [Anaconda Python 3.6](h
 
 You can start the FMPy GUI with `python -m fmpy.gui`
 
-![FMPy GUI](fmpy/images/Rectifier_GUI.png)
+![FMPy GUI](docs/Rectifier_GUI.png)
 
 ## Simulate an FMU in Python
 
@@ -69,7 +69,7 @@ outputs             output        282.842712474619  V        Rectifier1.Capacito
 >>> plot_result(result)                # plot two variables
 ```
 
-![Rectifier Result](fmpy/images/Rectifier_result.png)
+![Rectifier Result](docs/Rectifier_result.png)
 
 ## Simulate an FMU on the command line
 
@@ -95,9 +95,9 @@ fmpy --help
 ## Advanced Usage
 
 To learn more about how to use FMPy in you own scripts take a look at the
-[coupled_clutches.py](fmpy/examples/custom_input.py),
+[coupled_clutches.py](fmpy/examples/coupled_clutches.py),
 [custom_input.py](fmpy/examples/custom_input.py) and
-[parameter_variation.py](fmpy/examples/custom_input.py>) examples.
+[parameter_variation.py](fmpy/examples/parameter_variation.py) examples.
 
 ------------------------------------
 

diff --git a/fmpy/images/Rectifier_GUI.png → docs/Rectifier_GUI.png b/fmpy/images/Rectifier_GUI.png → docs/Rectifier_GUI.png
diff --git a/fmpy/images/Rectifier_result.png → docs/Rectifier_result.png b/fmpy/images/Rectifier_result.png → docs/Rectifier_result.png
diff --git a/docs/changelog.md b/docs/changelog.md
@@ -0,0 +1,64 @@
+## v0.2.2 (2018-03-13)
+
+- `NEW` FMI 2.0 state serialization functions added
+- `NEW` Graphical representation of the FMU's inputs and outputs added to settings page
+- `NEW` Platform check when simulating FMUs
+- `NEW` MkDocs documentation added
+- `FIXED` Record values at time == start_time when simulating model exchange FMUs
+- `FIXED` Correct source files are now used when compiling model exchange FMUs
+- `CHANGED` Required dependency on pypiwin32 changed to pywin32
+
+
+## v0.2.1 (2018-02-15)
+
+- `NEW` About dialog in the GUI that shows version and environment info
+- `NEW` Copy variable names and value references to the clipboard from the context menu
+- `NEW` Navigation buttons are new toggled to indicated selected page
+- `FIXED` fmu_info() now works with FMUs where not all attributes are set in the modelDescription.xml
+- `FIXED` Improved error message when the FMU does not support the selected FMI type
+
+
+## v0.2.0 (2018-01-29)
+
+- `NEW` graphical user interface
+- `NEW` compilation of source code FMUs
+- `NEW` model structure elements: ModelDescription.outputs and ModelDescription.derivatives
+- `NEW` FMI functions: setRealInputDerivatives() and getRealOutputDerivatives()
+- `FIXED` constructor arguments for solver classes
+
+
+## v0.1.2 (2017-12-21)
+
+- `CHANGED` 'fmpy' command is now directly accessible from the command line
+- `CHANGED` SSP schema updated to Draft20171219
+
+
+## v0.1.1 (2017-12-11)
+
+- `NEW` dependency information in setup.py
+- `NEW` platform check for parameter variation example
+- `FIXED` FMI call logging
+- `FIXED` plot_result() now works with older matplotlib versions
+- `CHANGED` timeout in cross-check removed
+
+
+## v0.1.0 (2017-11-24)
+
+- `NEW` custom simulation loop and input example
+- `NEW` parameter variation example running on multiple cores
+- `NEW` experimental [System Structure and Parameterization](https://www.modelica.org/projects#ssp) support
+- `NEW` max. step size parameter for CVode solver
+- `FIXED` return values in completedIntegratorStep()
+
+
+## v0.0.9 (2017-10-13)
+
+- `FIXED` set start values of type String
+- `NEW` CVode variable-step solver
+- `NEW` cross-check API for external tools
+
+
+## v0.0.8 (2017-09-10)
+
+- `FIXED` resourceLocation in FMU2.instantiate() now points to resources directory instead of unzip directory
+- `NEW` FMI functions (fmi1Reset, fmi2Reset, fmi2GetFMUState, fmi2SetFMUState, fmi2FreeFMUState)
diff --git a/CONTRIBUTING.md → docs/contributing.md b/CONTRIBUTING.md → docs/contributing.md
diff --git a/docs/hacking.md b/docs/hacking.md
@@ -0,0 +1,90 @@
+# Hacking FMPy
+
+You want to learn more about FMPy, debug it or contribute? Here's how to get started.
+
+## Setup your Python environment
+
+**`Alternative 1:` Create a a new Conda environment (recommended)**
+
+If you don't have conda yet you can either install [Anaconda](https://www.anaconda.com/download/) which includes
+the most common Python packages or [Miniconda](https://conda.io/miniconda.html) which only contains the conda package manager
+and Python.
+
+To create a new conda environment named "py36_64" enter
+
+```bash
+conda create -q -n py36_64 -c anaconda python=3.6 dask lxml matplotlib numpy pathlib pyqt pyqtgraph pywin32 requests
+```
+
+on Linux and macOS the `pywin32` package is not required but you might need to prepend `sudo` to
+the command depending on your permissions. If you want Python 2.7 you can use `python=2.7`.
+If you want a 32-bit Python environment you have to enter `set CONDA_FORCE_32BIT=1` before creating
+the environment. Note that in order to simulate FMUs the Python environment has to match the
+platforms supported by the FMU. I.e. you need a 64-bit Python on Windows to simulate an FMU that
+only supports `win64`. To activate the environment run `activate py36_64` on Windows or `source activate py36_64` on Linux and macOS and `deactivate` to deactivate it.
+
+**`Alternative 2:` Use an existing Python environment**
+
+If you want to use an existing Python you can install the necessary dependencies with conda
+
+```bash
+conda install dask lxml matplotlib numpy pathlib pyqt pyqtgraph pywin32 requests
+```
+
+or pip
+
+```bash
+python -m pip install dask lxml matplotlib numpy pathlib pyqt pyqtgraph pywin32 requests
+```
+
+The package `pywin32` is only required on Windows.
+
+
+## Clone the repository
+
+Go the directory where you want to clone the repository and enter
+
+```bash
+git clone https://github.com/CATIA-Systems/FMPy.git
+```
+
+or use your favorite Git tool to clone it. To checkout the latest development branch change
+to the directory and enter
+
+```bash
+git fetch
+git checkout -b develop origin/develop
+```
+
+## Install FMPy
+
+To install or update FMPy without changing the dependencies of your python environment change to the folder where you cloned FMPy and run
+
+```bash
+python -m pip install --upgrade --no-deps .
+```
+
+## Create a PyCharm project
+
+Download and install [PyCharm Community Edition](https://www.jetbrains.com/pycharm/download/). On the welcome screen click `Create New Project` or select `File > New Project...`.
+
+As `Location` select the `FMPy` directory you just cloned. Expand `Project Interpreter`, check `Existing Interpreter` and select
+the environment you created. You might need to add your interpreter first using the cogwheel button. After clicking `Create` a dialog pops up asking if you want to create a project from existing sources. Click `Yes`.
+
+## Debug the "coupled_clutches" example
+
+Open `FMPy > fmpy > examples > coupled_clutches.py` from the project view and put a breakpoint in `def simulate_coupled_clutches()` by left-clicking between the line number and the code. To start debugging right-click on `coupled_clutches.py` and select `Debug 'coupled_clutches'`.
+Use the buttons in the debug view to step through the code.
+
+## Debug the GUI
+
+Click on the drop-down box on the top-right and select `Edit Configurations...`. In the dialog click on the `+` button and select `Python` to add a new run configuration. Fill in the following values:
+
+Option               | Value
+---------------------|----------
+Name                | FMPy GUI
+Script path         | fmpy.gui
+Python interpreter  | the environment you've created
+Interpreter options | -m
+
+Now you can set breakpoints and start debugging by clicking on the debug button on the top right.
diff --git a/docs/index.md b/docs/index.md
@@ -0,0 +1,11 @@
+# FMPy
+
+FMPy is a free Python library to simulate [Functional Mock-up Units (FMUs)](http://fmi-standard.org/) that...
+
+- supports FMI 1.0 and 2.0
+- supports Co-Simulation and Model Exchange
+- runs on Windows, Linux and macOS
+- has a graphical user interface ``NEW``
+- compiles source code FMUs ``NEW``
+
+It's developed at Dassault Syst&egrave;mes and released under the BSD 3-clause license.
diff --git a/docs/install.md b/docs/install.md
@@ -0,0 +1,69 @@
+## Get Python
+
+To use FMPy you need Python. If you do not have a Python environment on your machine you can install
+[Anaconda](https://www.anaconda.com/download/) that comes with a range of packages for scientific computing. If you want
+to install your packages individually you can use [Miniconda](https://conda.io/miniconda.html).
+
+## Required Packages
+
+Depending on what you intent to use FMPy for you might only need certain packages.
+
+| Function                  | Required packages                         |
+|---------------------------|-------------------------------------------|
+| Read modelDescription.xml | lxml                                      |
+| Simulate FMUs             | numpy, pathlib, pywin32 (only on Windows) |
+| Plot results              | matplotlib                                |
+| Parallelization example   | dask                                      |
+| Download example FMUs     | requests                                  |
+| Graphical user interface  | pyqt, pyqtgraph                           |
+
+
+## Install with Conda
+
+To install FMPy from [conda-forge](https://conda-forge.org/) including all dependencies type
+
+```bash
+conda install -c conda-forge fmpy
+```
+
+To install FMPy w/o dependencies type
+
+```bash
+conda install -c conda-forge fmpy --no-deps
+```
+
+and install the dependencies with
+
+```bash
+conda install <packages>
+```
+
+
+## Install with PIP
+
+To install FMPy from [PyPI](https://pypi.python.org/pypi) including all dependencies type
+
+```bash
+python -m pip install fmpy[complete]
+```
+
+To install FMPy w/o dependencies type
+
+```bash
+python -m pip install fmpy --no-deps
+```
+
+and install the dependencies with
+
+```bash
+python -m pip install <packages>
+```
+
+
+## Install from Source
+
+To install the latest development version directly from GitHub type
+
+```bash
+python -m pip install https://github.com/CATIA-Systems/FMPy/archive/develop.zip
+```