pyphs 0.1.9.9.3

Development Status :: 4 - Beta

PyPHS

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

It is developped by :

• Antoine Falaize, Team M2N (Mathematical and Numerical Methods) at the LaSIE Research Lab (CNRS UMR 7356), hosted by Université de La Rochelle, France.

• Thomas Hélie, Project/team S3 (Sound Signals and Systems) at STMS Research Lab (CNRS UMR 9912), hosted by IRCAM, Paris, France.

It was initially developed between 2012 and 2016 as a part through a funding from French doctoral school EDITE (UPMC ED-130), and in connection with the French National Research Agency project HaMecMoPSys.

Installation

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.

Prerequisites

The PyPHS package run on Python 2.7 and Python 3.5 or newer (3.4 is no longer tested), 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).

The generated C++ sources build with CMake >= 3.1 (see Configuration below). The code relies on the Eigen library (not needed for pure Python usage).

Install from package

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

Install from source

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

Configuration

After installation, it is recommanded to configure the config.py to your needs. Particularily, this is where the local path to the CMake binary and Eigen library is specified.

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

>>> from pyphs import path_to_configuration_file
>>> print(path_to_configuration_file)

Upgrade of existing installations

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.

Upgrade a package

Simply upgrade the package via pip:

pip install –upgrade pyphs [–user]

In some cases, you will need to manually uninstall the package:

pip uninstall pyphs pip install pyphs [–user]

Upgrade from source

Simply pull the latest sources:

git pull

Package structure

The package is divided into the following folders:

/pyphs/tutorials

Tutorials for the main PyPHS classes (executable programs).

/pyphs/examples

Various applications (executable programs).

/pyphs/core

PHSCore class :

This is the core PHS structure. It provides several methods for the manipulation of symbolic expression (reorganization, connection, simplification, etc.). It is passed as an argument to the constructor of most of others PyPHS objects.

/pyphs/graphs

PHSNetlist class :

Management of netlist description files.

PHSGraph class :

1. Construction and manipulation of network systems,

2. Analysis of network realizability,

3. Generation of PHS equations (PHSCore).

/pyphs/dictionary

Components are PHSGraph objects. The dictionary is organized in thematic sub-packages (electronics, thermics, fractional calculus, etc.). Each theme is organized in component sub-packages (electronics.resistor, thermics.transfer, fraccalc.fracderec, etc.).

/pyphs/numerics

PHSNumericalEval class :

Numerical evaluation of a given PHSCore.

PHSCoreMethod object :

Construction of the symbolic expressions associated with several numerical methods (theta-schemes, trapezoidal rule, discret gradient, etc.).

PHSNumericalCore object :

Numerical evaluation of a given PHSCore associated with a given PHSCoreMethod.

PHSSimulation object :

Perform the simulation of a given PHSCore associated with a given PHSCoreMethod through the execution of the resulting PHSNumericalCore.

PHSData object :

Methods for writing, reading and rendering PHSSimulation file results.

/pyphs/tests

Test programs executed by nose (see above).

/pyphs/misc

Miscelaneous tools (plots, LaTeX code generation, signal processing, iles I/O).

Documentation

Implemented methods

The package began as an implementation of the methods proposed in the reference [1], 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.

Tutorials and examples

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 is not currently up-to-date.

Reference

[1]

Falaize, A., & Hélie, T. (2016). Passive Guaranteed Simulation of Analog Audio Circuits: A Port-Hamiltonian Approach. Applied Sciences, 6(10), 273.