[HomePage] [TitleIndex] [WordIndex] 

DynSim Documentation

Contents

  1. DynSim Documentation
    1. Structure of this Documentation
      1. Built-in Documentation
    2. Introduction
    3. Installation
      1. Prerequisites
      2. dynsim
    4. Classes Available
    5. Example simulation models (included in zip file)
    6. Advanced Simulation Topics
      1. Simulation Initialisation
      2. Stiff Models
      3. Discrete-Time execution
      4. Selecting the Timestep

Structure of this Documentation

There are four elements of documentation for DynSim:

Built-in Documentation

The Python docstrings ("built-in documentation") are the primary documentation of DynSim, and contain detailed information on the use of individual modules, classes and functions within DynSim. These docstrings are available via different mechanisms for the most convenience:

The content of each of these mechanisms is generated from the doc-strings in the package and each module, class and function.

Introduction

DynSim is a simulation environment created within the Python language aimed at fast construction and testing of control schemes in the field of Process Control Engineering.

It is essentially a simple set of classes which allow quick simulation of analog and hybrid control schemes and the process they are applied to. The framework includes a library of "block" or component classes from which we can build the simulation, but allows the user to pull it all together with his own python scripting to do all the housekeeping and analysis or to interface with other data or input/output systems.

There is no GUI for execution. For rapid development of models, a text-based programming approach is chosen. Of course, there is graphical output for trends and output data exploration. It is also easy to add graphical controls and animation outputs.

Installation

Prerequisites

dynsim

You can find the latest version of DynSim in the Weblog at the bottom of the main DynSim page. Look for the latest (top-most) entry with the title "Uploaded new version (dynsim_YYYYMMDD.zip)" . The zip file will contain all of files you need. Find your installed version of Python and navigate to "...\python\Lib\site-packages". Unzip the dynsim directory there. That's it! You should now be able to start up Python and from dynsim import control etc.

Classes Available

For an overview of the dynsim classes, the structure of dynsim is outlined here. Some modules/classes have links in the dot-points below (click on the name) to an overview of that component and these are intended to complement the docstrings held within each module/class. Note that capitalisation of the class name here is for clarity and doesn't necessarily match the actual class name.

Control Classes (from dynsim import control) basic simulation control and control/dynamics building blocks:

Process Classes (from dynsim import process) presently aimed at simple slurry streams:

Mechanics Classes (from dynsim import mechanics)

Finance Classes (from dynsim import finance) for personal finance simulation (beware - specific to Australian taxation law):

InputOutput Classes (from dynsim import io) providing real-time Input-Output functionality, especially using OPC:

Discrete Classes (from dynsim import discrete) if necessary for integrating SimPy discrete-event elements to form a hybrid simulation:

How are these models different to what you'd find in other dynamic simulation systems? Here's a comparison with SysCAD (from their published documentation, and from a Process Control perspective).

Example simulation models (included in zip file)

These example simulation scripts provide a wide range of concise Process Control simulations to learn from, or use as a starting point template to ease the construction of a new simulation. These are distributed with the DynSim source.

Advanced Simulation Topics

Simulation Initialisation

Initialisation of a model at the start of a simulation can be done by setting "dt" to be -ve (the DynSim2 library module objects recognise this), so that the simulation is executed (with blocks in "track" mode) for several timesteps in order for the initialisation of output values to be fully propagated through all blocks. DynSim's "timesteps" generator (see the examples) is designed to do this automatically and easily. The number of initialisation timesteps required will depend on how well the blocks are ordered and the number of signal "recycles" in the model. At most there will need to be N initialisation steps for a model which contains a cascaded sequence of N objects/blocks executed in the worst-case order. However, the default of two "timesteps" of initialisation are usually sufficient.

If you need to heed these initialisation "timesteps" in your own script code, the following template is useful: 

        if dt<0.0:
            # code initialise variables
        else:
            # normal execution code

Stiff Models

Wikipedia defines stiff differential equations as those "for which certain numerical methods for solving the equation are numerically unstable, unless the step size is taken to be extremely small."

However, there seems to be two main types of "stiffness" with regard to how they can be treated in a simulation:

  1. a type arising from instability in one "period" of the simulation time or transitioning through a "range" of values at one part of the simulation time; and
  2. a type arising from isolated elements (differential equations) of the simulation being persistently unstable compared to the remainder of the simulation.

Type 1 is described in detail in the Wikipedia entry on "stiff equations" and can be solved by taking small steps when the values are changing rapidly. In dynsim this is difficult and would require drastic customisation of the timestep over the unstable periods with a priori knowledge of when these periods are. In dynsim, these are best handled by simply reducing the timestep until the solution doesn't change (to a tolerance).

Type 2 is essentially a particular form of Type 1, one which can be better solved by applying smaller timesteps to only the problematic equations of the simulation code (as opposed to different periods of simulation time). Type 2 cannot be effectively solved using the solution to Type 1 because the whole simulation would have to be slowed down.

The Stiff systems solution described here are for Type 2 systems that have some segments of the simulation code (equations) that need to have a very small timestep while the rest of the simulation can tolerate a very large timestep. If the entire simulation is run at the very small timestep, the progress is very slow. If the entire simulation is run at the very large timestep, the simulation accuracy is inadequate. Multiple time-step intervals may, as well as being required for stiff systems, may also be needed for a sampled PLC/DCS system (e.g. 5 second control scan-time) plus continuous plant (very small timesteps).

The principle behind this solution is achieved by including a nested "for" loop with smaller "dt" set (e.g. inner loop dt = 0.1, outer loop dt = 1.0), such that only the "stiff" (or high resolution) components are executed at a smaller time-step. In practice, this is automatically performed by using the generator function "smalltimesteps" for a "for" loop within the main simulation loop. Look at the documentation for "smalltimesteps" for further details.

Discrete-Time execution

Some parts of a simulation may need to be executed at a very slow interval to simulate discrete-time control (such as PID loop execution in a PLC or DCS at 1 second intervals). The "largesteps" generator function should be used as an inner execution loop within the main simulation "for" loop. Note that, for discrete-time implementation, the same solution can be achieved by using either "smallsteps" or "largesteps" depending on your perspective.

Selecting the Timestep

As with any sequential-modular simulator, selecting the timestep or "dt" is important. You want dt to be as large as possible to make your simulation run quickly; but you want the simulation to be accurate. The most common technique for determining the largest discretisation is to create a working simulation, then decrease dt by factors of 2 until no changes occur to the results (to the desired accuracy). If there is no change on the first decrease, then try increasing dt until you get a change and backtrack.

2015-05-14 10:33