1. Welcome to the NSR Physiome Project!
  2. Physiome JSim
  3. The JSim Documentation Set
  4. JSim Plugin Developer's Guide

JSim Plugin Developer's Guide

Introduction

This document describes how to write JSim plugins, code modules that extend JSim's functionality at run-time. Familiarity with both JSim and Java software engineering is assumed.

Contents:

  • Plugin Basics
  • Creating a plugin
  • DataFormat plugins
  • Graphic plugins
  • ModelEasel plugins
  • Optimizer plugins
  • Limitations and Future Plans
  • Comments or Questions?
    Give feedback

Plugin Basics

A JSim plugin is a Java archive (.jar file) that is loaded into jsim, jsbatch or jsserver at run-time to enhance functionality for some user purpose. For example, a user might wish to output model data in a format not currently provided by JSim. This format may be peculiar to a the user's current project, but of little value to the general JSim user community. Here a JSim plugin provides the advantages:

  • the public JSim distribution is not weighed down with code specific to a single user;
  • the user may implement the plugin without waiting for the JSim development team to allocate time for his particular project.

A plugin's type determines the sort of functionality the plugin will have within JSim. The example above is of the DataFormat type. A plugin's variant is a unique name for the plugin, within all available plugins of the same type. Suppose the example above was implemented via a plugin MyDataFormat.jar, with type DataFormat and variant "mine". Below, the plugin is loaded via the jsbatch -plugin switch, and accessed via the -ofmt switch:

      jsbatch -f some.proj -plugin MyDataFormat.jar -ofmt mine

Note that -ofmt does not normally accept "mine" as a valid format. However, with the plugin "mine" becomes acceptable (and functional).

JSim has a client-server architecture, and plugins may enhance either the client or server operation. When (as by default) jsim or jsbatch is run using the local server, either type of plugin will be operational. When running the JSim applet or running jsim or jsbatch on a remote server, only client-side plugins will be operational. Remote server-side plugins must be installed via jsserver.

Creating a plugin

For each type of plugin, there is an associated JSim internal class which implements that functionality. For example, the JSim.data.DataFormat class implements the functionality of the plugin type DataFormat. The plugin .jar file must contain a new subclass of the internal class. In our example MyDataFormat extends JSim.data.DataFormat. The new subclass, along with supporting classes and resources are bundled into the plugin .jar. The manifest for a plugin .jar must have the following entries that allow JSim to recognize the plugin and use is appropriately. Values for each entry correspond to the above example:

      JSimPluginType: DataFormat
      JSimPluginVariant: mine
      JSimPluginClass: MyDataFormat

The plugin classes may be compiled against the JSimClient and JSimServer distributed jar files found in $JSIMHOME/lib. A client-side plugin will need only JSimClient.jar, a server-side plugin will need both.

Details for plugin programming may be found in the JSim Public API .

See $JSIMHOME/doc/plugins in your JSim distribution for some examples of JSim plugins and how to build them (on a Macintosh, the doc directory is in the installation directory). More complete documentation for plugin programming may be found in the JSim Public API .

Currently supported plugin types:

  • DataFormat : allow import and export of JSim data in formats not currently supported by JSim.
  • Graphic : allow customized graphics representation of JSim model properties, constraints and (possibly live) data.
  • ModelEasel : allow point-and-click model building within JSim.
  • Optimizer : allow use of novel optimization algorithms not currently supported by JSim.

Planned future plugin types:

  • ODESolver : allow external ODE solvers in JSim model run-time calculations.
  • if you have ideas for other JSim plugin types, please contact the JSim development team.

DataFormat plugins

A DataFormat plugin allows import and export of JSim data in formats not currently supported by JSim. This client-side plugin extends the JSim internal class JSim.data.DataFormat. DataFormat may implement an associated DataReader (for importing data) or a DataWriter (for exporting data) or both. Each DataFormat defines a set of file suffixes (e.g. .mydata) that are associated with the format.

DataReader plugin functionality is activated when a data file is read (e.g. the -f switch) and has one of the format associated suffixes.

In JSim, DataWriter plugin functionality is activated when a data file is written (e.g. PlotPage -> Export data file...) that has one of the format associated suffixes. In jsbatch, it is activated via the -ofmt switch, where the format name corresponds to JSim.data.DataFormat.shortName(). (Note this is not necessarily the same as the plugin "variant", however it is probably simplest for the two to be the same.)

A simple DataFormat plugin example may be found in $JSIMHOME/doc/plugins/mydata.

DataFormat implementations in the JSim source code may be found in classes JSim.data.*Format.

Graphic plugins

A Graphic plugin allows customized graphics representation of JSim model properties, constraints and (possibly live) data. This client-side plugin extends the JSim internal class JSim.gui.plugin.GGraphic.

Graphic plugins are created in the JSim GUI by selected the "New graphic(plugin)" item in the Project tab "Add" menu. Project files store the Graphics tabs, but do not yet retain any state information. This limitation will be addressed in future releases.

A simple Graphic plugin examples may be found in $JSIMHOME/doc/plugins/mygraphic and $JSIMHOME/doc/plugins/myconstraints.

There are no implementations of GGraphic in the JSim source code at this time.

ModelEasel plugins

This client-side plugin extends the JSim internal class JSim.gui.plugin.GModelEasel, providing point-and-click model building capability within JSim.

ModelEasel plugins are created in the JSim GUI by selecting "New model" in the Project tab "Add" menu. New models are "text" by default (users edit MML code directly). If any ModelEasel plugins are available, the user may select one which will result in a new "Easel" tab within the model. Users manipulate the Easel graphics until satified and then hit the "Compile" button which will generate an MML representation of the graphic and pass it along to the JSim compiler.

A simple ModelEasel plugin example may be found in $JSIMHOME/doc/plugins/myeasel.

There are no implementations if GModelEasel in the JSim source code at this time.

Optimizer plugins

An Optimizer plugin allows use of novel optimization algorithms not currently supported by JSim. This server-side plugin extends the JSim internal class JSim.nml.opt.Optimizer. The plugin class must implement the following static method in order to properly advertise itself to JSim clients applications:

public static OptimAlg.Info algInfo();

In the jsim GUI, an Optimizer plugin will appear as an algorithm choice within a model's optimization configuration tab. For models containing non-linear implicit equations, it will also appear in runtime solvers page "bound" and "unbound" choice options. In jsbatch, an Optimizer plugin may be selected via the model.optim.alg control and the solver.fzero_bound and solver.fzero_unbound parameters.

A sample Optimizer plugin example may be found in $JSIMHOME/doc/plugins/myoptimizer.

Optimizer implementations in the JSim source code may be found in classes Simplex, GGopt, GridSearch and NelderMead in package JSim.nml.opt.

Limitations and Future Plans

JSim plugin functionality is preliminary, and the mechanisms described in this document may change in later JSim releases.

Only two plugin types are currently available. There will be more in the future. If you have an idea for a plugin type that would be useful, please contact the JSim development team.

Plugins are loaded into JSim exclusively via the -plugin switch, which accepts only a file in the local file system. In the future the -plugin switch will accept a URL and there will be a mechanism for installing plugins so they are automatically available to any subsequent JSim sessions.

Plugins are not currently operational in the jsserver program.

Comments or Questions?

Give feedback

Model development and archiving support at https://www.imagwiki.nibib.nih.gov/physiome provided by the following grants: NIH U01HL122199 Analyzing the Cardiac Power Grid, 09/15/2015 - 05/31/2020, NIH/NIBIB BE08407 Software Integration, JSim and SBW 6/1/09-5/31/13; NIH/NHLBI T15 HL88516-01 Modeling for Heart, Lung and Blood: From Cell to Organ, 4/1/07-3/31/11; NSF BES-0506477 Adaptive Multi-Scale Model Simulation, 8/15/05-7/31/08; NIH/NHLBI R01 HL073598 Core 3: 3D Imaging and Computer Modeling of the Respiratory Tract, 9/1/04-8/31/09; as well as prior support from NIH/NCRR P41 RR01243 Simulation Resource in Circulatory Mass Transport and Exchange, 12/1/1980-11/30/01 and NIH/NIBIB R01 EB001973 JSim: A Simulation Analysis Platform, 3/1/02-2/28/07.