A python software dedicated to the simulation of multiphysical systems in the Port-Hamiltonian Systems (PHS) formalism.

It is developped in the project/team S3 (Sound Signals and Systems) at STMS Research Lab (CNRS UMR 9912), hosted by IRCAM.

It was initially developed between 2012 and 2016 as a part of the PhD project of Antoine Falaize, under the direction of Thomas Hélie, through a funding from French doctoral school EDITE (UPMC ED-130), and in connection with the French National Research Agency project HaMecMoPSys.

It is possible to install pyphs from package (if you just want to use it) or source (if you plan to use it for development). Whichever method you choose, make sure that all prerequisites are installed.

The pyphs package run on Python 2.7 and Python 3.4 or newer, with the following packages installed:

• sympy
• numpy
• scipy
• matplotlib
• networkx
• stopit
• progressbar2
• nose (to run the tests)

Please refer to the requirements.txt file for the minimum required versions and make sure that these modules are up to date.

Additionally, theano is used if installed (for faster numerical evaluation of symbolic expressions).

Finally, the generated C++ code rely on the Eigen library (see Configuration below). It is not needed for pure Python usage.

The instructions given here should be used if you just want to install the package, e.g. to run the bundled programs or use some functionality for your own project. If you intend to change anything within the pyphs package, please follow the steps in the next section.

The easiest way to install the package is via pip from the PyPI (Python Package Index):

pip install pyphs

This includes the latest code and should install all dependencies automatically. If this is not the case, each dependency can be install the same way with pip.

You might need higher privileges (use su or sudo) to install the package globally. Alternatively you can install the package locally (i.e. only for you) by adding the --user argument:

pip install --user pyphs

If you plan to use the package as a developer, clone the Git repository:

git clone --recursive https://github.com/afalaize/pyphs.git

Then you can simply install the package in development mode:

python setup.py develop --user

To run the included tests:

python setup.py test

After installation, it is recommanded to configure the config.py to your needs. Particularily, this is where the local path to the Eigen library is specified (and then included in the generated C++ code).

Your local config.py file is located at the root of the pyphs package, which can be recovered with:

>>> import pyphs >>> help(pyph)

To upgrade the package, please use the same mechanism (pip vs. source) as you did for installation. In each case, it is recommanded to uninstall the package first.

Simply upgrade the package via pip:

pip install --upgrade pyphs [--user]

Simply pull the latest sources:

git pull

The package divided into the following folders:

/docs

package documentation

/pyphs/tutorials

tutorials programs for the main `pyphs classes

/pyphs/examples

additional examples (executable programs)

/pyphs/core

define the core PHS structure class PHSCore

/pyphs/graphs

define the classes PHSNetlist and PHSGraph

/pyphs/dictionary

components (PHSGraph)

/pyphs/numerics

define the classes PHSNumericalEval, PHSNumericalMethod and PHSNumericalCore for the numerical evaluation of PHSCore

/pyphs/simulations

define the classes PHSSimulation and PHSData for simulation

/pyphs/latex

LaTeX code generation

/pyphs/cpp

C++ code generation

/pyphs/tests

test programs (withe nose)

/pyphs/plots

Plot tools

/pyphs/misc

Miscelaneous tools

The package began as an implementation of the methods proposed in the reference¹, in which the port-Hamiltonian formalism, the graph analaysis and the numerical method are exposed. This is worth to read before using the pyphs package.

The package comes with a serie of tutorials for the use of the main functionalities (definition, evaluation, and simulation of a core PHS structure). More tutorials are to come. Additionally, you can see the examples scripts. Both the tutorials and the examples folders are located at your package root, which can be recovered in Python interpreter with:

>>> import pyphs >>> help(pyphs)

The website contains additional materials.