Python is a general-purpose programming language supported by a rich set of libraries and an active user community.  The Jython interpreter is an implementation of the Python language which runs on a Java virtual machine, and enables a seamless integration of Java and Python code.  As such, Jython/Python has been embedded in Magnolia to provide a fully-featured scripting language for controlling simulation runs as an alternative to the simpler CMD language.  Compared to the CMD language, Python adds capabilities for creating and manipulating variables, control flow (loops and if/else statements), classes and object-orientation, a rich set of numerical and analytical libraries, etc.




A full introduction to Python programming can be found elsewhere (see, for example, the documentation section of the Python website: www.python.org).  But much of the details of how Python interfaces with the models created in Magnolia can be explained by examination of the “Model” class.  Every compiled CSL model inherits from this class, and the member functions of this class represent most of the ways of interacting with a Magnolia model from within Python code.


To use these functions, one must first obtain a reference to the Model object associated with a particular model loaded in Magnolia.  This is done using the global “models” object, which is a dictionary mapping the file name of a model to its associated object:


mdl = models.get(“Example_1.csl”)


The above line of code places a “reference” to the compiled version of “Example_1.csl” (which needs to be open in Magnolia) in the variable “mdl”.  Having done this, the model variables and constants can be accessed using the “dot” notation.  For example, if the model contains a variable “x”, the value of this variable can be assigned to a new variable “tmp” using the following line of Python code:


       tmp = mdl.x


Similarly, if the model contains a parameter named “k”, the value of that parameter may be set using the following line of code:


       mdl.k = 3.0


The following table summarizes some of the other model functions which are useful in developing Python scripts to control simulation runs:


mdl.prepare(“x”)

Add the model variable named “x” to the prepare list.

mdl.run()

Perform a simulation run.

mdl.history(“x”)

Return the history of variable “x” into a Python array.


To create a plot from within Python code, the global “plot” object provides two member functions:


plot.line(x, y)

Creates a new plot from the data points contained in the arrays x and y.  Returns a “handle” to the newly constructed plot for use in subsequent calls to append().

plot.append(h, x, y)

Appends the data contained in the arrays x and y to an existing plot with handle “h”.


Alternately, a plot may be constructed using the plot.open() command, where a model name and “plot settings” object is passed to plot.open() as in the following example:




# Create a plot settings object
ps = plot_settings()

# Set up axis ranges, titles, etc
ps.xmin = 0.0
ps.xmax = 10.0
ps.title = 'styrene.csl'
ps.xlabel = 'Time (hr)'
ps.ylabel = 'Conc (mg/L)'

# Inidicate which variables will be included on the plot
ps.pnames = ["CV", "CL", "CX"]

# Create the plot
plot.open("styrene.csl", ps)