SimuPy

SimuPy: A Python framework for modeling and simulating dynamical systems - Published in JOSS (2017)

https://github.com/simupy/simupy

Keywords

Scientific Fields

Repository

A framework for modeling and simulating dynamical systems

README.rst

.. |simupy_logo| image:: docs/_static/simupy_color_small.png
   :alt: SimuPy

|simupy_logo|
=============

.. image:: https://img.shields.io/pypi/v/simupy.svg
    :alt: PyPI Package latest release
    :target: https://pypi.python.org/pypi/simupy

.. image:: https://readthedocs.org/projects/simupy/badge/?style=flat
    :target: https://simupy.readthedocs.io/en/latest/
    :alt: Documentation Status

.. image:: https://travis-ci.org/simupy/simupy.svg?branch=master
    :alt: Travis-CI Build Status
    :target: https://travis-ci.org/simupy/simupy

.. image:: https://codecov.io/gh/simupy/simupy/branch/master/graph/badge.svg
  :alt: Coverage Status
  :target: https://codecov.io/gh/simupy/simupy

.. |API documentation| replace:: `API Documentation`_
.. _API Documentation: https://simupy.readthedocs.io/en/latest/api/api.html

SimuPy is a framework for simulating interconnected dynamical system models and
provides an open source, python-based tool that can be used in model- and
system- based design and simulation workflows. Dynamical system models can be
specified as an object with the interface described in the 
|API documentation|. Models can also be constructed using symbolic
expressions, as in

.. code-block :: python

    from sympy.physics.mechanics import dynamicsymbols
    from sympy.tensor.array import Array
    from simupy.systems.symbolic import DynamicalSystem

    x = x1, x2, x3 = Array(dynamicsymbols('x1:4'))
    u = dynamicsymbols('u')
    sys = DynamicalSystem(Array([-x1+x2-x3, -x1*x2-x2+u, -x1+u]), x, u)

which will automatically create callable functions for the state equations,
output equations, and jacobians. By default, the code generator uses a wrapper
for ``sympy.lambdify``. You can change it by passing the system initialization
arguments ``code_generator`` (the function) and additional keyword arguments
to the generator in a dictionary ``code_generator_args``. You can change the
defaults for future systems by changing the module variables

.. code-block :: python

   import simupy.systems.symbolic
   simupy.systems.symbolic.DEFAULT_CODE_GENERATOR = your_code_generator_function
   simupy.systems.symbolic.DEFAULT_CODE_GENERATOR_ARGS = {'extra_arg': value}

A number of helper classes/functions exist to simplify the construction of
models. For example, a linear feedback controller can be defined as

.. code-block :: python

   from simupy.systems import LTISystem
   ctrl = LTISystem([[1.73992128, 0.99212953,  -2.98819041]])

The gains in the example come from the infinite horizon LQR based on the system
linearized about the origin. A block diagram of the system under feedback
control can be constructed

.. code-block :: python

   from simupy.block_diagram import BlockDiagram
   BD = BlockDiagram(sys, ctrl)
   BD.connect(sys, ctrl) # connect the current state to the feedback controller
   BD.connect(ctrl, sys) # connect the controlled input to the system

Initial conditions for systems with non-zero dimensional state can be defined
(it defaults to zeros of the appropriate dimension) and the interconnected
systems can be simulated with the ``BlockDiagram``'s ``simulate`` method,

.. code-block :: python

   sys.initial_condition = [5, -3, 1]
   res = BD.simulate(10)

which uses ``scipy.integrate.ode`` as the default solver for the initial-valued
problem. The results are an instance of the ``SimulationResult`` class, with
array attributes ``t``, ``x``, ``y``, and ``e``, holding time, state, output,
and event values for each integrator time step. The first axis indexes the time
step. For ``x``, ``y``, and ``e``, the second axis indexes the individual
signal components, ordered first by the order each system was added to the
block diagram then according to the system state and output specification. The
simulation defaults to the ``dopri5`` solver with dense output, but a different
``integrator_class`` and ``integrator_options`` options can be used as long as
it supports a subset of the ``scipy.integrate.ode`` API. The default values
used for future simulations can be changed following the pattern for the
symbolic code generator options.

A number of utilities for constructing and manipulating systems and the
simulation results are also included:

- ``process_vector_args`` and ``lambdify_with_vector_args`` from
  ``simupy.utils.symbolic`` are helpers for code generation using
  ``sympy.lambdify``
- ``simupy.utils.callable_from_trajectory`` is a simple wrapper for making
  polynomial spline interpolators using ``scipy.interpolate.splprep``
- ``simupy.matrices`` includes tools for constructing (vector) systems using
  matrix expressions and re-wrapping the results into matrix form
- ``simupy.systems.SystemFromCallable`` is a helper for converting a function
  to a state-less system (typically a controller) to simulate
- ``MemorylessSystem`` and ``LTISystem`` are subclasses to more quickly create
  these types of systems
- ``SwitchedSystem`` is used to construct systems with discontinuities,
  defined by zero-crossings of the ``event_equation_function`` output.

The examples subdirectory includes a number of worked problems. The 
documentation and docstrings are also available for reference.

Installation
------------

Version 1.0 of SimuPy is ``pip`` installable

.. code-block:: bash

   $ pip install simupy

However, the latest features and examples are only available in the development
version. To install,

.. code-block:: bash

  $ git clone https://github.com/simupy/simupy.git 
  $ pip install -e simupy


SimuPy has been tested locally against

 - Python >= 3.6
 - NumPy_ >= 1.11
 - SciPy_ >= 0.18
 - SymPy_ >= 1.0

but tests on Travis may run with newer versions. Much of the functionality
works without SymPy, so installation does not require it. The examples use
matplotlib_ to visualize the results. Testing uses pytest_. The documents are
built with Sphinx_ == 1.6.3.

.. _NumPy: http://numpy.scipy.org
.. _SymPy: http://sympy.org
.. _SciPy: http://www.scipy.org/scipylib/index.html
.. _matplotlib: http://matplotlib.org
.. _pytest: https://docs.pytest.org/en/latest/
.. _Sphinx: http://sphinx-doc.org/

Contributing
------------

1. To discuss problems or feature requests, file an issue. For bugs, please
   include as much information as possible, including operating system, python
   version, and version of all dependencies. 
2. To contribute, make a pull request. Contributions should include tests for
   any new features/bug fixes and follow best practices including PEP8, etc.

JOSS Publication

SimuPy: A Python framework for modeling and simulating dynamical systems

Published

September 20, 2017

DOI

10.21105/joss.00396

Volume 2, Issue 17, Page 396

Authors

Benjamin W. l. Margolis
University of California, Davis

Editor

Christopher R. Madan

Tags

simulation block diagram

View PDF Review Thread Software Archive

GitHub Events

Committers

Last synced: 5 months ago

Issues and Pull Requests

Last synced: 4 months ago

Packages