This section describes the various Application Programming Interfaces (APIs) which are used to develop VBM modules. This section is intended for people who want to develop their own modules. If you only want to use modules that already exist there is no need to read this section.
The bifurcation visualization API allows the user to use various tools to interactively visualize bifurcation diagrams. The two main functions of this interface are to allow visualization of the bifurcation diagram and interactive selection of specific points. The following table shows the functions which make up this API.
|
Function Name | Purpose |
setUpdateFunc | Registers a callback to use if the data is modified |
Draw | Redraws the bifurcation diagram |
setFileData | Sends a copy of the current bifurcation diagram object |
setPointer | Sends the list of currently defined pointer objects |
|
|
The setFileData and setPointer methods
allow the sending of bifurcation diagram and
pointer objects to the module. It is important
that these two data structures be set independently
for efficiency. The bifurcation diagram object
may be large and require a nontrivial amount of computation
each time it is reset. The pointer objects, on the
other hand, are normally small and change frequently.
The bifurcation visualization API is the one bi-directional API
in VBM. Through this API the user can move the markers on the
bifurcation diagram to designate new points of interest. This
functionality
is implemented with the setUpdateFunc method. This method allows
the bifurcation diagram module to register a callback which it may
use to inform the VBM Core when it modifies
either the bifurcation manifold object or the pointer
object.
The Draw method informs the module that it should update
its output based upon any new data that has been
given to it.
The Draw method seems to be redundant at first glance, since
the module knows that the data is updated whenever
setFileData or setPointer are called, but it is
needed for efficiency. The Draw method can be very expensive
in graphical bifurcation visualization modules, so its functionality
was extracted from the setFileData and setPointer routines
so that it can be called only when necessary. For example,
if both the bifurcation manifold object and the pointer object
need to be updated, the Draw function can be called only once.
If its functionality was part of setFileData and setPointer
it would have been called twice.
The data probe API is designed to allow the visualization of solutions to a problem in greater detail than is possible in a bifurcation diagram. There are a wide range of visualization tools and methods that can be applied for specific problems, hence this interface is specifically designed to make almost no assumptions about how this visualization will occur. Basically, this interface transmits to the data probe module the numeric data of a points of the bifurcation diagram along with all of its corresponding tags. The data probe module is then free to interpret this data as it wishes.
|
Key | Purpose |
setWhichPointer | |
| Sets the pointer that this data probe should follow | |
setFileData | |
| Sends a copy of the current bifurcation manifold object | |
setPointer | |
| Sends the list of currently defined pointer objects | |
Draw | |
| Redraws the solution | |
|
|
setFileData and
setPointer
functions are straight forward. The one point to emphasize is that the
setFileData routine sends the data probe
all of the data for the bifurcation diagram,
not just the single point defined by the
setWhichPointer routine. The reason for
this is to give the data probe freedom in the visualization that it implements.
For example, all of the data in the bifurcation diagram may not have the proper
tags for a given data probe to function. If the data probe is given access to
the total bifurcation diagram, it can perhaps choose a nearby point which does
have the proper tags and visualize that point instead. This
functionality is another example of the
need to separate the visualization and computation domains. Perhaps the
data needed by the data probe is large and the computational
discretization
is fine. In such a case, a large amount of data would be required if
every point of the bifurcation diagram was to be valid for this data probe.
Given the above described freedom, we can store the large data sets
at only a small number of the points.
The setWhichPointer routine is, as discussed above, only a recommendation.
There is no guarantee as to how a given module will interpret the
arguments of this method, but well designed
modules should give feedback if they stray too far from the point specified in
this method.
By far the most complex API in VBM is the compute engine API. This API is our attempt to encapsulate the interactivity required to steer continuation algorithms, in a very general sense. It consists not only of a functional API, but also a set of states. Certain functions are only valid in certain states, and functions can cause the state of the computation to change. The interface methods follow, and the states are discussed in Section.
Creates the compute engine
Starts a new continuation
Extends an already started continuation
Stops the current continuation and prepares to start a new one
Modifies the computational parameters
Destroys the computation and frees its resources
Having the various states, as discussed in Section, is not functionally necessary, i.e. one could implement the control of continuation algorithms without separating these various pieces of functionality, as we have done here. Pragmatically, one could control continuation algorithms with only a single function call, which would have as arguments the starting points, how many steps to compute, and perhaps some setup parameters. Unfortunately, this mode of operation would be very inefficient, because we would not be able to distinguish between those computational parameters which may be easily changed and those which are expensive to change.
The following table contains the arguments to the powerup
method of the Compute Engine API.
A directory in which the compute engine may store temporary files. If this argument is set to `NULL' the compute engine is free to create a directory itself.
An array of strings, each of which is an address of a machine on which to run a compute engine. Again, if the first entry in this array is `NULL' then the compute engine is free to select the host on which it will run.
A stream which the compute engine may read to get computational defaults, e.g. discretization parameters.
A stream which defines the problem which the compute engine will solve. It may be a string, data file, or an executable program.
stream from which the bifurcation diagram object may be accessed, which is canonically in the shown in Section.
The values of the problem and data streams are fixed after
powerup is called. On the other hand, the value of the defaults stream may
be modified, and this action is performed
through the setup
method. We make this distinction for
efficiency. We allow the compute engine to
place options which are slow to change into the
problem stream and those which are fast to change
into the defaults stream.
The start method affects the transition from the
Idle state to the Active state. It takes as arguments
the numeric data of the desired starting point, the tags
at that point, a vector of integers which describe
what parameters to continue
in, and a vector of directions.
The interpretation of the direction vector is up to the compute
engine, but normally positive values correspond to
the increase of some parameter. The reset function
returns the module to the Off state.
The following table contains the arguments to the start
method of the Compute Engine API.
An array which contains the numeric data from the bifurcation diagram object.
An array which contains all of the tags, both point-wise and global, which apply to the point in the data array. These tags and the numeric data must provide enough information for the compute engine to start a new computation.
An array of integers which define what parameters the compute engine should continue in. The values which are contained in this array are compute engine dependent.
An array of integers whose sign is used to determine the direction of continuation. The compute engine is free to interpret these integers as it wishes, though canonically a positive value should imply that the appropriate parameter is increasing and a negative value should imply the parameter is decreasing.
The extend function allows more data to be computed
as part of the current continuation. It takes two arguments,
the first of which is an array of numeric values and the second
of which is a string.
The string defines what type of continuation the compute engine
should perform. The currently defined types are "edge"
and "bounding box", which are explained
in the following table. The array of numerical
values defines the stopping conditions for the
continuation algorithm and their interpretation is
defined by the type string.
The following table contains the arguments to the extend
method of the Compute Engine API.
A string which defines how the stopping conditions for the continuation algorithm are implemented. For example, the "edge" type allows the values of the params array to be used as the number of steps to add to a continuation. Another example is the "bounding box" type, in which the params array are interpreted as maximum or minimum values of some parameter to compute
An array of numerical values which are used as stopping conditions for the compute engine. Their interpretation is determined by the type variable.