This repository contains all development code for a GUI plugin for lumped parameter modeling in SimVascular. The ultimate goal is to provide an intuitive and extensible graphical interface for designing and simulating lumped parameter networks, for use in both independent simulations and as coupled boundary conditions to 1-D and 3-D models. The current design allows users to drag-and-drop circuit elements to build a model, and provides a step-by-step wizard to run independent simulations. All simulations are run by Ngspice using their shared C library.
The simulator
directory contains the Qt project for the standalone GUI for building and simulating independent LPNs. It is envisioned that this will be the basis for the eventual SimVascular plugin.
The noGUI
directory contains code to provide similar simulation functionality to the GUI wizard, but without the GUI interface. This may be helpful for running simulations on a cluster machine. See the README in the noGUI
directory for more information.
The GenBC
directory contains code used for testing and development of a coupled boundary conditions system using Ngspice, to replace the current GenBC
system. This code is currently not ready for use.
All simulation functionality across all parts of this project is handled by the Ngspice shared library. In order to run the simulator you will need to download and install Ngspice and the shared library.
- Clone the ngspice repo:
git clone http://git.code.sf.net/p/ngspice/ngspice
or download the tarball from this link - Follow the install instructions in the file
INSTALL
in the topngspice
directory, but ensure to include the flag--with-ngshared
to the./configure
command. (i.e. you should run this command:./configure --enable-xspice --enable-cider --disable-debug=yes --with-ngshared && make && sudo make install
). - Make sure that the file
/usr/local/include/ngspice/sharedspice.h
exists
Download and install Qt Creator and Qt 5.11 from the Qt website. The free open source version is fine.
For plotting functionality, you need to install Gnuplot. On Linux you can download it with the command apt-get install gnuplot
.
To run the circuit simulator, open Qt Creator and click Open Project. Open the file simulator/simulator.pro
. Qt Creator should automatically configure the project for you. You can build and run using the Qt Creator buttons in the lower left corner.
Check out the tutorial here to learn how to use the program.
- There is no way to delete a connection between elements without deleting one of the elements. Wires should be selectable and deletable
- The way wires are drawn right now may not be ideal for further development (one segment of each wire is drawn by each node in the connection, the way the segments are assigned isn't the most aesthetic and isn't dynamic)
- The model parsing algorithm hasn't been rigorously tested
- Very occasionally, an element will jump to the top left corner of the window when clicked and dragged
- The Ngspice callback
ControlledExit
ignores the bool arguments given because the documentation is very confusing
- Implement clinical units and conversion between these units and ngspice-compatible units
- Allow for time-varying voltage and current sources that aren't external (documented in Chapter 4 of the Ngspice manual)
- The current method of using a 'START' ground node for parsing start isn't optimal or intuitive. Maybe something like a visual representation of an inlet/outlet would be better, or maybe the Voltage/Current sources could only have one wire leading out of them to represent an inlet/outlet.
- Add drag-and-drop blocks e.g. Windkessel or Heart models
- Test and improve support for other operating systems (currently only tested on Linux)
- Implement as a plugin
The vision for the GenBC
system is that users will be able to open the GUI to build a model for a particular surface (or surfaces, in the case of closed loop boundary condition), assign the model to the surface(s), and be able to run the simulation with no more interaction with the models.
My current proposal is to use Cython to generate an executable that can simply replace the current GenBC executable, requiring no changes to SimVascular. The required functionality of this executable is to:
- Read the Fortran binary
GenBC.int
to get values at surfaces from SimVascular - Run a simulation on each LPN, using these values
- Write the simulation results back to
GenBC.int
for SimVascular to read
The code in the GenBC/testing
directory is currently in development to perform these three steps. What is currently working:
- The
scipy.io.FortranFile
package can read from and write toGenBC.int
- The
cython
package is capable of loading the Ngspice shared library and it is callable from Python code.
There are two main challenges currently:
- How to communicate between the SV GUI plugin and the cython executable regarding:
- The order in which values need to be read from and written to
GenBC.int
(i.e. the order of the surfaces/models) - How to know which value to set in the Ngspice netlist to the value read from
GenBC.int
- How to know which vector generated by Ngspice to write to
GenBC.int
- The order in which values need to be read from and written to
- Testing and justifying Ngspice simulation
- Is the Ngspice simulator fast enough to make it worthwhile? It removes the user's need to write out ODEs, but if it increases simulation time significantly this may not be worthwhile
- What analysis mode actually produces the right values? I've been running transient analysis where the duration is the timestep SV writes to
GenBC.int
and the analysis timestep is the duration divided bynTimesteps
which is defined as 100 inUSER.f
. So far, I have not been able to replicate the values generated byGenBC
for the simple test case provided (see directory levelREADME
).