Package: pyphs
PyPHSA Python software (Py) dedicated to the simulation of multi-physical Port-Hamiltonian Systems (PHS) described by graph structures.The PHS formalism decomposes network systems intoconservativeparts,dissipativeparts andsourceparts, which are combined according to anenergy conserving interconnection. This approach permits to formulate the dynamics of multi-physical systems as aset of differential-algebraic equationsstructured according to energy flows. Thisstructureproves thepassivityof the system, including the nonlinear cases. Moreover, it guarantees thestabilityof the numerical simulations for an adapted structure preserving numerical method.The main objects of the library are introduced inthis presentation.
The standard workflow is as follows.Inputs arenetlist descriptionsof network systems (very similar to SPICE netlists).The associatedgraphsare analyzed to produce thecore system’s dynamics equationsin the PHS formalism.Simulations(i.e. numerical solving of DAE equations) are performed based on a variety ofnumerical methods(can be extended with new ones).The correspondingC++simulation code is automatically generated and called from python (can also be used in bigger applications).LaTeXdescription files can be generated (for documentation, publication, etc.).The Python classCoredefines symbolically acontinuous-time Port-Hamiltonian structure.The Python classMethoddefines symbolically adiscrete-time port-Hamiltonian structurederived from a givenCoreobject and for several numerical schemes. It includes a structure preserving numerical method (see[NumericalMethod2015]).The Python classNetlistreads and writes the descriptions of network systems.The Python classGraphdefines a network structure for the automated generation ofCorefromNetlist, based on (i) the implementation of a specially designedgraph analysis(see[GraphAnalysis2016]), and (ii) a set of elementarycomponentscompiled in theDictionary.The Python classSimulationevaluates iteratively a givenMethodobject to produce the data result in text files. The evaluation can run in pure Python code with theNumericalobject, or can run in C++ through the generated C++ files.StatusThis package is in development status Beta. The continuous integration is checked with Travis for Unix systems and AppVeyor for Windows systems (see build status below).LicencePyPHSis distributed under the GNU General Public License v3.0. In short, permissions of this strong copyleft license are conditioned on making available complete source code of licensed works and modifications, which include larger works using a licensed work, under the same license. Copyright and license notices must be preserved. Contributors provide an express grant of patent rights.InstallationIt is possible to installPyPHSfrom 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.Python prerequisitesThePyPHSpackage run on Python 2.7 and Python 3.5 or newer (3.4 is no longer tested).
Please refer to therequirements.txtfile for the required packages and make sure they are up to date.
Additionally,theanois used if it can be found on the system, for faster numerical evaluation of symbolic expressions.C++ prerequisitesThe generated C++ sources build withCMake>= 3.1 (seeConfigurationbelow). The code relies on theEigen library(not needed for pure Python usage).Install from packageThe easiest way to install the package is viapipfrom thePyPI (Python
Package Index):pip install pyphsThis includes the latest code and should install all dependencies automatically. If it complains about some missing dependencies, install them the same way withpipbeforehand.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–userargument:pip install --user pyphsInstall from sourceIf you plan to use the package as a developer, clone the Git repository:git clone --recursive https://github.com/pyphs/pyphs.gitThen you can simply install the package in development mode:python setup.py develop --userTo run the included tests:python setup.py testConfigurationAfter installation, it is recommended to configure theconfig.pyto your needs. Particularly, this is where the local path to the CMake binary is specified.Your localconfig.pyfile is located at the root of thePyPHSpackage, which can be recovered in a Python interpreter withfrompyphsimportpath_to_configuration_fileprint(path_to_configuration_file)Upgrade of existing installationsTo upgrade the package, please use the same mechanism (pip vs. source) as you did for installation.Upgrade a packageFirst, manually uninstall the package:pip uninstall pyphsand reinstall as explained above.Upgrade from sourcePull the latest sources:git pullPackage structureThe package is divided into the following folders:/pyphs/tutorialsTutorials for the mainPyPHSclasses (executable programs)./pyphs/examplesVarious real-life applications (executable programs)./pyphs/coreCoreclass :This is the central object of thePyPHSpackage. It implements the core PHS structure and provides several methods for its manipulation (reorganization, connection, simplification, etc.)./pyphs/graphsNetlistclass :Management of netlist description files.Graphclass :Construction and manipulation of network systems,Analysis of network realizability,Generation of PHS equations (Core)./pyphs/dictionaryComponents areGraphobjects.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/numericsEvaluationclass :Numerical evaluation of a givenCore.Methodobject :Construction of thesymbolicexpressions associated with several numerical methods (theta-schemes, trapezoidal rule, discret gradient, etc.).Simulationobject :Manage the iterative evaluation and associated results data for a givenMethod.Numericobject :Python evaluation of a givenMethod.Dataobject :Methods for writing, reading and renderingSimulationfile results./pyphs/testsTest programs executed bynose(see above)./pyphs/miscMiscellaneous tools (plots, LaTeX code generation, signal processing, files I/O).DocumentationMost of the documentation can be found in thewebsite.
In particular, you can see the two following resources:Theslidesfrom a talk given at IRCAM that introduces most the scientific background.Thetutorialthat shows practical usage of most PyPHS objects (3Mb).Theoretical overviewThe development ofPyPHSstarted as an implementation of the methods proposed in the reference [GraphAnalysis2016], in which the port-Hamiltonian formalism, the graph analysis and the structure preserving numerical method are exposed. This is worth to read before using the package.Q&A Mailing listThe package mailing list is athttps://groups.google.com/forum/#!forum/pyphs.Tutorials and examplesThe package comes with a set of tutorials for the use of the main functionalities (definition,evaluation, andsimulationof a core PHS structure). More tutorials are to come. Additionally, you can see theexamplesscripts. Both thetutorialsand theexamplesfolders are located at your package root, which can be recovered in Python interpreter withfrompyphsimportpath_to_examples,path_to_tutorialsprint(path_to_examples)print(path_to_tutorials)Typical useConsider the following serial diode-inductor-capacitor (DLC) electronic circuit:with the following physical parameters:ParameterDescription (SI unit)Typical valueIsDiode saturation current (A)2e-9v0Diode thermal voltage (V)26e-3muDiode ideality factor (dimensionless)1.7RDiode connectors resistance (Ohms)0.5LInductance value (H)0.05CCapacitance value (F)2e-061. Define the NetlistPut the following content in a text file with.netextension, (heredlc.net):electronics.source in (‘#’, ‘n1’): type=’voltage’;electronics.diode D (‘n1’, ‘n2’): Is=(‘Is’, 2e-9); v0=(‘v0’, 26e-3); mu=(‘mu’, 1.7); R=(‘Rd’, 0.5);electronics.inductor L (‘n2’, ‘n3’): L=(‘L’, 0.05);electronics.capacitor C (‘n3’, ‘#’): C=(‘C’, 2e-06);2. Perform graph analysisRun the following in a Python interpreter in the netlist file directory:importpyphsasphs# Read the 'dlc_netlist.net'netlist=phs.Netlist('dlc.net')# Construct the graph associated with 'netlist'graph=netlist.to_graph()# Construct the core Port-Hamiltonian System from 'graph'core=graph.to_core()3. Export LaTeX# Add netlist to LaTeX contentcontent=phs.netlist2tex(netlist)# Add PHS core to LaTeX contentcontent+=phs.core2tex(core)# Write ready-to-use .tex documentphs.texdocument(content,title='DLC',path='dlc.tex')This yields the followingtexfile:dlc.texwhich is compiled to produce the followingpdffile:dlc.pdf4. Export C++ code# Numerical method for time discretization of 'core'# with default configurationmethod=core.to_method()# Export the set of C++ file for simulationmethod.to_cpp()This yields the followingcppfiles:core.cppcore.hparameters.cppparameters.hThecore.hdefines a class ofDLCsystems with an update method to be called at each iteration for the simulations.Authors and AffiliationsPyPHS is mainly developed byAntoine FalaizeandThomas Hélie, respectively intheTeam M2N(Mathematical and Numerical Methods),LaSIE Research Lab(CNRS UMR 7356), hosted by theUniversity of La Rochelle,theTeam S3AM(Sound Systems and Signals: Audio/Acoustics, InstruMents) atSTMS Research Lab(CNRS UMR 9912), hosted byIRCAMin Paris.See theAUTHORSfile for the complete list of authors.Short HistoryThe ideas behind PyPHS where developed between 2012 and 2016 as a part of the PhD thesis ofAntoine Falaizeunder the direction ofThomas Hélie, through a funding from  the French doctoral schoolEDITE(UPMC ED-130) and in connection with the French National Research Agency projectHaMecMoPSys.References[NumericalMethod2015]Lopes, N., Hélie, T., & Falaize, A. (2015). Explicit second-order accurate method for the passive guaranteed simulation of port-Hamiltonian systems. IFAC-PapersOnLine, 48(13), 223-228.[GraphAnalysis2016]Falaize, A., & Hélie, T. (2016). Passive Guaranteed Simulation of Analog Audio Circuits: A Port-Hamiltonian Approach. Applied Sciences, 6(10), 273.