Mathworks SIMBIOLOGY RELEASE NOTES

SimBiology

®

Release Notes

How to Contact The MathWorks

www.mathworks.
comp.soft-sys.matlab Newsgroup
www.mathworks.com/contact_TS.html Technical Support

[e-mail] Product enhancement suggestions

bugs@mathwo
[e-mail] Documentation error reports
[e-mail] Order status, license renewals, passcodes

info@mathwo

com

rks.com

rks.com

Web

Bug reports

Sales, prici

ng, and general information

508-647-7000 (Phone)

508-647-7001 (Fax)

The MathWorks, Inc.
3 Apple Hill Drive
Natick, MA 01760-2098

For contact information about worldwide offices, see the MathWorks Web site.

®

SimBiology

© COPYRIGHT 2005–20 10 by The MathWorks, Inc.

The software described in this document is furnished under a license agreement. The software may be used
or copied only under the terms of the license agreement. No part of this manual may be photocopied or
reproduced in any form without prior written consent from The MathW orks, Inc.

FEDERAL ACQUISITION: This provision applies to all acquisitions of the Program and Documentation
by, for, or through the federal government of the United States. By accepting delivery of the Program
or Documentation, the government hereby agrees that this software or documentation qualifies as
commercial computer software or commercial computer software documentation as such terms are used
or defined in FAR 12.212, DFARS Part 227.72, and DFARS 252.227-7014. Accordingly, the terms and
conditions of this Agreement and only those rights specified in this Agreement, shall pertain to and govern
theuse,modification,reproduction,release,performance,display,anddisclosureoftheProgramand
Documentation by the federal government (or other entity acquiring for or through the federal government)
and shall supersede any conflicting contractual terms or conditions. If this License fails to meet the
government’s needs or is inconsistent in any respect with federal procurement law, the government agrees
to return the Program and Docu mentation, unused, to The MathWorks, Inc.

Trademarks

MATLAB and Simulink are registered trademarks of The MathWorks, Inc. See

www.mathworks.com/trademarks for a list of additional trademarks. Other product or brand

names may be trademarks or registered trademarks of their respective holders.

Patents

The MathWorks products are protected by one or more U.S. patents. Please see

www.mathworks.com/patents for more information.

Release Notes

Summary by Version ............................... 1

Contents

Version 3.2 (R2010a) SimBiology Software

Version 3.1 (R2009b) SimBiology Software

Version 3.0 (R2009a) SimBiology Software

Version 2.4 (R2008b) SimBiology Software

Version 2.3 (R2008a) SimBiology Software

Version 2.2 (R2007b+) SimBiology Software

Version 2.1.2 (R2007b) SimBiology Software

Version 2.1.1 (R2007a) SimBiology Software

Version 2.1 (R2006b+) SimBiology Software

Version 2.0.1 (R2006b) SimBiology Software

........... 5

........... 10

........... 13

........... 17

........... 28

.......... 31

.......... 44

.......... 45

.......... 46

.......... 49

Version 2.0 (R2006a+) SimBiology Software

Version 1.0.1 (R2006a) SimBiology Software

Version 1.0 (R14SP3+) SimBiology Software

Compatibility Sum mary for SimBiology Software

.......... 50

.......... 55

.......... 56

.... 62

iii

iv Contents

SummarybyVersion

This table provides quick access to what’s new in each version. For
clarification, see “Using Release Notes” on page 2 .

SimBiology®Release Notes

Version
(Release)

Latest Versi
V3.2 (R2010a

V3.1 (R2009b)

V3.0 (R2009a)

V2.4 (R2

V2.3 (R2008a)

V2.2 (R2007b+)

2 (R2007b)

V2.1.

.1 (R2007a)

V2.1

1 (R2006b+)

V2.

on

008b)

New Features
and Changes

Yes

)

Details

Yes
Details

Yes
Details

Yes
Details

Yes
Details

Yes

ls

Detai

No No Bug Reports No

No No Bug Reports No

Yes
Details

Version
Compatibilit
Consideratio

Yes
Summary

Yes
Summary

No Bug R epor

Yes
Summary

Yes
Summary

Yes
Summa

Yes
Summary

ry

Fixed Bugs

y

and Known

ns

Problems

Bug Reports
Includes fix

Bug Reports
Includes fixes

Includes

Bug Reports
Includes fixes

Bug Reports
Includes fixes

Bug Rep
Inclu

Bug Reports
Includes fixes

des fixes

ts

fixes

orts

Related
Documentation
at Web Site

Printable Release

es

Notes: PDF

Current product
documentation

No

No

No

No

No

No

V2.0.1 (R2006b)

V2.0 (R2006a+)

No No Bug Reports

Includes fixes

Ye
De

s

tails

s

Ye

mmary

Su

g Reports

Bu

cludes fixes

In

No

No

1

SimBiology®Release Notes

Version
(Release)

V1.0.1 (R2006a)

V1.0 (R14SP3+)

New Features
and Changes

Yes
Details

Yes
Details

Version
Compatibility
Considerations

No Bug Reports No

No Bug Reports No

Fixed Bugs
and Known
Problems

Related
Documentation
at Web Site

Using Release Notes

Use release notes when upgrading to a newer version to learn about:

• New features

• Changes

• Potential impact on your existing files and practices

Review the release notes for other MathWorks™ products required for this
product (for example, MATLAB
bugs, or compatibility considerations in other products impact you.

If you are upgrading from a software version other than the m ost recent one,
review the current release notes and all interim versions. For example, when
you upg rade from V1.0 to V1.2, review the release notes for V1.1 and V1.2.

®

or Simulink®). Determine if enhancements,

What Is in the Release Notes

New Features and Changes

• New functionality

• Changes to existing functionality

Version Compatibility Con si derations

When a new feature or change introduces a reported incompatibility between
versions, the Compatibility Considerations subsection explains the
impact.

2

SummarybyVersion

Compatibility issues reported after the product release appear under Bug
Reports at The MathWorks™ Web site. Bug fixes can sometimes result
in incompatibilities, so review the fixed bugs in Bug Reports for any
compatibility impact.

Fixed Bugs and Known Problems

The MathWorks offers a user-searchable Bug Reports database so you can
view Bug Reports. The development team updates this database at release
time and as more information becomes available. Bug Reports include
provisions for any known workarounds or file replacem ents. Information is
available for bugs existing in or fixed in Release 14SP2 or later. Information
is not avail able for all bugs in earlier releases.

Access Bug Reports using y our MathWorks Account.

About Functions Being Removed

This section lists functions removed or in the process of being removed.
Functions typically go through several stages across multiple releases before
being co mplete ly removed. This provides time for you to make adjustments
to your code.

• Announcement – The release notes announce the planned removal, but

there are no functional changes; the function runs as it did before.

• Warning – When you run the function, it displays a warning message

indicating it will be removed in a future release; otherwise the function
runs as it did before.

• Error – When you run the function, it produces an error. The error message

indicates the function was removed and suggests a replacement function, if
one is available.

• Removal – When you run the function, it fails. The error message is the

standard message when MATLAB does not recognize an entry.

Functions might be in a stage for one or more releases before moving to
another stage. Functions are listed in the Functions Being Removed sectio n
only when they enter a new stage and their behavior changes. For example,
if a function displayed a warning in the previous release and errors in this

3

SimBiology®Release Notes

release, it appears on the list. If it continues to display a warn i ng , it does n ot
appear on the list because there was no change between the releases.

Not all functions go through all stages. For example, a function’s impending
removal might not be announced, but instead the first notification might be
that the function displays a warning.

The release notes include actions you can take to mitigate the effects of a
function’s removal, such as adapting your code to use a replacement function.

4

Version 3.2 (R2010a) SimBiology®Software

Version 3.2 (R2010a) SimBiology Software

This table summarizes what’s new in Version 3.2 (R2010a):

New Features and
Changes

Yes
Details below

Ver sion
Compatibility
Considerations

Yes—Details labeled
as Compatibility
Considerations,
below. See also
Summary.

New features and changes introduced in this version are:

• “Stochastic Approximation Expectation-Maximization (SAEM) Algorithm

for Fitting Population Data” on page 5

• “Enhanced Support for Importing NONMEM Formatted Files” on page 6

• “New Mode for Accelerating Simulations” on page 6

• “Enhanced Support for Applying Dosing to a Model and Dosing Multiple

Compartments” on page 6

• “Support for Parameter Transformations” on page 8

• “Support for Error Models ” on page 8

• “Functions and Propertie s Being Removed” on page 9

Fixed Bugs and
Known Problems

Bug Reports
Includes fixes

Related
Documentation at
Web Site

Printable Release
Notes: PDF

Current product
documentation

Stochastic Approximation Expectation-Maximization
(SAEM) Algorithm for Fitting Population Data

Now you can choose the SAEM algorithm when fitting population data. This
functionality requires Statistics Toolbox™ (Version 7.3 or later).

The new stochastic algorithm for fitting NLME models is more robust with
respect to starting values, enables parameter transformations, and relaxes
assumption of constant error variance.

For more information, see:

5

SimBiology®Release Notes

• sbionlmefitsa in the SimBiology®documentation

nlmefitsa in the Statistics Toolbox documentation

•

• “Pharmacokinetic Modeling Functionality” in the SimBiology

documentation

Enhanced Support for Importing NONMEM Formatted
Files

Import data files with NONMEM®interpretation of column headers.
SimBiology interprets the data file d uring import and creates the data set to
use during fitting. For more information see “Importing Data — Supported
Files and Data Types”. After import you can also create dose s chedules using
the information in the imported data.

New Mode for Accelerating Simulations

SimBiology enables you to prepare your mo de ls for accelerated simulations.
Use this functionality to run many simulations with different initial
conditions, or to run very long simulations (for example, simulations that take
a minute or longer to run). Before you can use this feature you must install a
Ccompiler,andrun
information see “Accelerating Simulations” in the SimBiology documentation.

mex -setup before you can use this feature. For more

Enhanced Support for Applying Dosing to a Model
and Dosing M ultiple Compartments

Create and apply dosing using RepeatDose Object, ScheduleDose Object
and the adddose method at the command line or the Doses pane in the
desktop.

6

Version 3.2 (R2010a) SimBiology®Software

Compatibility Considerations

• Previously, sim u la tin g mode ls with dosing informatio n required the

sbiosetdosingprofile function. Using sbiosetdosingprofile now

7

SimBiology®Release Notes

errors and you must change how you apply dosing. For related information
on dosing in pharmacokinetic models see “About Dosing Types” in the
SimBiology documentation.

• Previously, you could specify that a parameter is dosed. No w only species

can accept a dose.

• Previously, the PK models you created using the New Project Wizard or

the

construct method varied depending on the dose chosen. Now you get

the same model, w hich allows you to change between dosing types.

Support for Parameter Transformations

During parameter fitting, you now can specify parameter transformations.
The following parameter transformations are now supported:

•

none

• log

• probit

• logit

You can specify parameter transformations in individual (sbionlinfit)
and population fitting (
“Specifying Parameter Transformations” in the SimBiolog y documentation.

sbionlmefit or sbionlmefitsa) functions . See

Compatibility Considerations

Previously, sbionlinfit and sbionlmefit returned the log-transformed
estimates for the fixed effects. Now

sbionlmefitsa) return untransformed and transformed estimates for the

fixed effects.

sbionlinfit, sbionlmefit (and

Support for Error Models

Parameter fitting functionality now supports the following error models:

•

constant

• proportional

• combined

8

Version 3.2 (R2010a) SimBiology®Software

• exponential

Youcanspecifyanerrorterminconjunction with a population fitting
(

sbionlmefitsa) function.

For more information see, “Specifying an Error Model” in the SimBiolo gy
documentation.

Functions and Properties Being Removed

For more information about the process of removing functions, see “About
Functions Being Removed” in “What Is in the Release Notes” on page 2.

Function or Property
Name

sbiosetdosingprofile

What
Happens
When
You Us e
Function
or
Property?

Errors

Use This Instead Compatibility

Considerations

RepeatDose Object,
ScheduleDose Object,
adddose

See th e Compat ibility
Considerations subheading
in“Enhanced Support
for Applying Dosing to a
Model and Dosing Multiple
Compartments” on page 6.

9

SimBiology®Release Notes

Version 3.1 (R2009b) SimBiology Software

This table summarizes what’s new in Version 3.1 (R2009b):

New Features and
Changes

Yes
Details below

Ver sion
Compatibility
Considerations

Yes—Details labeled
as Compatibility
Considerations,
below. See also
Summary.

New features and changes introduced in this version are:

• “Increased Performance When RepeatedlySimulatingaModel”onpage10

• “Enhanced Desktop Support for Scanning Using Monte Carlo Methods”

on page 11

• “Desktop Support for Copy and Paste ” on page 11

• “View Status of Parameter Fitting Task During Run” on page 11

• “Improved Usability for Model Building and Debugging” on page 11

• “Unit Conversion C ompatibility Considerations” on page 12

• “Functions and Properties Being Removed” on page 12

Fixed Bugs and
Known Problems

Bug Reports
Includes fixes

Related
Documentation at
Web Site

No

Increased Performance When Repeatedly Simulating
aModel

Many analysis tasks that involve repeatedly simulating a model now run
faster. These tasks include parameter fits and scans, as well as repeatedly
simulating the same model using different variants or setting different
values for the
and the
the model generates any applicable warnings only the first time. To display
warnings again, use the verification methods described in “Verifying that a
Model H as No W a rnings or Errors” in the SimBiology User’s Guide.

InitialAmount of species, the Capacity of compartments,

Value of parameters. Under these conditions, repeatedly simulating

10

Version 3.1 (R2009b) SimBiology®Software

Enhanced Desktop Support for Scanning Using Monte
Carlo Methods

Scanning analysis now includes additional support for Monte Carlo
methods. You can specify sampling using the options

distribution

The Statistics Toolbox is required for this functionality. For more information,
see “Scanning Analysis” in the SimBiology User’s Guide documentation.

or lat in hypercube sample with a normal distribution.

multivariate normal

Desktop Support for Copy and Paste

The SimBiology desktop now supports copying and pasting. Use the typical
keyboard shortcuts or the context menus to execute these commands.

View Status of Parameter Fitting Task During Run

You can track the status of a parameter fit when using nonlinear mixed
effects with the
selecting an option in the SimBiology desktop. For more information, see
“Obtaining the Status of Fitting” (command line) or “Obtaining the Status
of Fitting” (desktop).

sbiofitstatusplot function at the command line or by

Improved Usability for Model Building and
Debugging

The SimBiology des kto p now supports:

• Dynamically updated error indicators for variants, configuring plots,

and defining scans — Shows correctly defined, incorrectly defined, and
warning indicators (green, red, and yellow) for additional help with model
debugging.

• M-Lint indicators — Wherever code appears in the desktop, the indicators

used by M-lint also appear.

• Help for us er-identified MATLAB code—Selectandusethecontextmenu

to find help on functions where code appears in the desktop.

11

SimBiology®Release Notes

Unit Conversion

Previously a mod
off. Now, a model
an error. Set

Functions and

For more infor
Functions Be

Function or Property
Name

-flat as an option for

getstoichmatrix and
getadjacencymatrix

Compatibility Considerations

el with no units specified could have unit conversion on or

with no units specified that has

itConversion

Un

off for models without units.

UnitConversion on shows

Properties Being Removed

mation about the process of removing functions, see “About

ing Rem ove d” in “What Is in the Release Notes” on page 2.

What
Happens
When
You Us e
Function
or
Property?

Errors

Use This Instead Compatibility

Considerations

Not appli

cable

Since support for submodels
has been removed, this
option no longer applies.

12

Version 3.0 (R2009a) SimBiology®Software

Version 3.0 (R2009a) SimBiology Software

This table summarizes what’s new in Version 3.0 (R2009a):

New Features and
Changes

Yes
Details below

Ver sion
Compatibility
Considerations

No Bug Reports

New features and changes introduced in this version are:

• “New Feature to Import, Visualize, and Statistically Analyze Clinical and

Experimental Data” on page 13

• “New Functionality to Create Pharmacokinetic Models” on page 14

• “New Functionality to Fit Data and Estimate Parameters Using Nonlinear

Mixed Effects” on page 14

• “New Diagnostic Plots for Individual and Population Fitting Results” on

page 15

• “New Project Wizard to Add Data, Create Models, and Specify Tasks” on

page 15

• “New simbiology Command to Open the SimBiology Desktop” on page 16

• “Enhanced Usability Features in the SimBiology Desktop” on page 16

• “New Demo for Pharmacokinetic Modeling” on page 16

Fixed Bugs and
Known Problems

Includes fixes

Related
Documentation at
Web Site

No

New Feature to Import, Visualize, and Statistically
Analyze C linical and Experimental Data

You can import tabular data into the SimBiology desktop or the MATLAB
Workspace. The supported file types are

At the command line, you can process and visualize the data using
command-line functions. In the SimBiology desktop, you can filter the raw
data to suppress outliers, visualize data using MATLAB plots, and calculate

.xls, .csv,and.txt.

13

SimBiology®Release Notes

statistics to analyze the data. You can further choose to plot the imported
data with any analysis task.

See “Importing Data — Supported Files and Data Types” in the SimBiology
User’s Guide for more information.

New Functionality to Create Pharmacokinetic Models

You can automatically generate pharmacokinetic (PK) models by specifying
number of compartments, dosing type, and method of elimination. If you plan
to use the MATLAB command line, see “Creating PK Models at the Command
Line” in the SimBiology User’s Guid e for more information.

If you plan to use the SimBiology desktop, the new Add Model wizard lets you
automatically generate PK models in the desktop. See “Creating PK Models
in the SimBiology Desktop Using a Wizard” in th e SimBiology User’s Guide
for more information.

In addi tion, in the Sim B iology desktop you can start by creating a new project
using the new Project Wizard which also lets you add data, create models,
and add analysis tasks in a SimBiology project. See “New Project W izard
to Add Data, Create Models, and Specify Tasks” on page 15 for additional
information.

14

New Functionality to Fit Data and Estimate
Parameters Using Nonlinear Mixed Effects

You can perform both individual and population fits to grouped longitudinal
data.

• Individual fit — Fit data using nonlinear least squares method, estimate

parameters, and calculate residuals and the estimated coefficient
covariance matrix.

• Population fit — Estimate the fixed effects and the random sources of

variation on parameters, using nonlinear mixed-effects models.

You can use the following methods to estimate the fixed effects:

- LME — Linear mixed-effects approximation

- RELME — Restricted LME appr ox imation

Version 3.0 (R2009a) SimBiology®Software

- FO — First-order estimate

- FOCE — First-order conditional estimate

For more information, see “Pharmacokinetic Modeling Functionality” in the
SimBiology User’s Guide.

New Diagnostic Plots for Individual and Population
Fitting Results

In the SimBiology desktop, after fitting the data, the analysis generates
diagnostic plots that show:

• The predicted time courses and observations for an individual or the

population

• Observed versus predicted values

• Residuals versus time, group, or predictions

• Distribution of the residuals

• A box-plot for random effects or parameter estimates from individual

fitting.

For more information, see “Visualizing Parameter Fitting Results and
Generating Diagnostic Plots” in the SimBiology User’s Guide.

New Project Wizard to Add Data, Create Models,
and Specify Tasks

The newly added P roject Wizard in the SimB iology desktop lets you:

• Add data from text files, spreadsheets, or the MATLAB Workspace.

• Create models, including autom ati cal ly generate pharmacokinetic models

by specifying number of compartments, dosing type, and me thod of
elimination.

• Specify analysis tasks to add to the project.

15

SimBiology®Release Notes

For an example of how to use the Project Wizard, see “Modeling U sing the
SimBiology Graphical User Interface” in the SimBiology Getting Started
Guide.

New simbiology Command to Open the SimBiology
Desktop

A new function, simbiology , has been added for enhanced usability in opening
the SimBiology desktop.
function, which is also supported.

simbiology is equivalent to the sbiodesktop

Enhanced Usability Features in the SimBiology
Desktop

The following enhancements to the SimBiology desktop are included in this
release:

• Back and Forward buttons to help with navigation between desktop panes

16

• In Preferences, the ability to choose default model tasks to add to a

model when loading an SBML file or importing a model from the MATLAB
Workspace

New Demo for Pharmacokinetic Modeling

There is a new demo showing pharmacokinetic modeling functionality
(Modeling the Population Pharmacokinetics of Phenobarbital in Neonates).
To see all demos, click SimBiology demos or type

'SimBiology')

at the command prompt.

demo('MATLAB',

Version 2.4 (R2008b) SimBiology®Software

Version 2.4 (R2008b) SimBiology Software

This table summarizes what’s new in Version 2.4 (R2008b):

New Features and
Changes

Yes
Details below

Ver sion
Compatibility
Considerations

Yes—Details labeled
as Compatibility
Considerations,
below. See also
Summary.

New features and changes introduced in this version are:

• “Enhanced Usability with the Redesigned Reaction Pane” on pag e 17

• “Additional Support for Showing Usages and Generating Reports in the

SimBiology Desktop” on page 18

• “Support for Specifying Additional Inputs in Custom Plot Types” on page 19

• “Edit Graphical Models Using the New Block Property Editor” on page 20

• “Manage and Share Libraries Using the New Library Explorer” on page 21

• “Additional Options for Renaming Compartments, Species, and

Parameters” on page 23

• “Change in the Random Number Generator Used During Stochastic

Simulations” on page 24

Fixed Bugs and
Known Problems

Bug Reports
Includes fixes

Related
Documentation at
Web Site

No

• “Functions and Properties Being Removed” on page 25

Enhanced Usability with the Redesigned Reaction
Pane

In the SimBiology desktop, the redesigned reaction pane consolidates the
procedure to configure kinetic law, rate parameters, rate species, and reaction
rates on one screen.

17

SimBiology®Release Notes

18

Additional Support for Showing Usages and
Generating Reports in the SimBiology Desktop

Additional Support for Showing Usages

The Compartments and Species panes now have added support for
showing usages of compartments and species in a model. To show usages
of a component, right-click (Windows

®

), or Ctrl+click (Macintosh®)the

Version 2.4 (R2008b) SimBiology®Software

compartment or species table, and select Show Usages. Support has also
been added for showing usages from the Diagram View.

Additional Sup port for Generating Reports

You can now automatically populate report contents with one click in the
Report pane. In the Project Explorer, right-click (Windows), or Ctrl+click
(Macintosh) Project Tasks and select Add Task > Generate report
to create a report. Select Help > SimBiology Desktop Help to see the
context-sensitive help for information on how to generate reports. Click
AutoBuild to populate the contents of your report automatically.

port for Specifying Additional Inputs in Custom

Sup

tTypes

Plo

can now specify additional inputs for plot types and define their types,

You

fault values, and ranges where applicable. For example, you can use this

de

aturetoextendthe

fe

Time plot with an additional input to specify markers.

19

SimBiology®Release Notes

Compatibility Considerations

This consideration applies when you previously created custom plot types.
Before, you could define the number of species or parameters that could be
specified for
should modify your plot code to enforce this constraint. For an example of
enforcing the constraint, see the code for the built-in plot type

To access this code:

1 In the SimBiology desktop, select Desktop > Library Explorer.The

Library Explorer opens.

2 Select Plot Types.

3 In the plot types table, select XY. The code section updates to show XY plot

type code.

x or y arguments. This functionality has been removed. You

XY.

Edit Graphical Models Using the New Block Property
Editor

The Block Property Editor is a tool that facilitates model building using
the Diagram View pane by docking next to the diagram and allowing you to
change properties of the selected block in the diagram. If you select multiple
blocks, you can edit the properties that are common between each block. To
open the Block Property Editor, select a block in the Diagram View pane,
and then select Diagram > Tools > Block Property Editor.

20

Version 2.4 (R2008b) SimBiology®Software

Manage and Share Libraries Using the New Library
Explorer

The Library Explorer adds the ability to add, modify, and share the contents
of kinetic law, plot type, unit, unit prefix, and blo ck libraries. To open the

Library Explorer, in the SimBiology desktop, select Desktop > Show
Library Explorer.

21

SimBiology®Release Notes

The Library Explorer shows all built-in and user-defined components,
namely kinetic laws, units, unit prefixes, plot types, and blocks.

22

• Kinetic Laws — C ontains kinetic laws that you can use as templates

while creating a reaction rate expression.

• Units — Contains units that you can specify for compartment capacity,

species amounts and parameter values, to do dimensional analysis and
unit conversion during simulation.

• Unit Prefixes — Contains all unit prefixes that you can specify in

combination with a valid unit for compartment capacity, species amounts
and parameter values, to do dimensional analysis and unit conversion
during simulation.

• Plot Types — Contains different types of plots that you can use with

Model Tasks to visualize your results.

• Blocks — Contains blocks that you can use in the Diagram View.

For help, open the Library Explorer and select Help > SimBiology

Desktop Help to see the context-sensitive help. Select a library in the
Library Explorer to view information specific to the library.

Version 2.4 (R2008b) SimBiology®Software

Additional Options for Renaming Compartments,
Species, and Parameters

New Method for Renaming at the Command Line

The newly added rename method allows you to change the name of a
compartment, species, or parameter, and update the name in expressions that
refer to the component. Use the
enable the name change and expression update.

New Options for Renaming in the SimBiology Desktop

You can specify how compartments, species, and parameter names should
be updated in expressions. When you rename a compartment, species, or
parameter, by default the names are settobeupdatedinallexpressionsthat
refer to the component being renamed. During renaming, if the component is
used in one or more expressions, you will see a dialog box that tells you which
expressions will be updated. For example, the following dialog box appears
when you try to rename species

rename method instead of the set method to

G to Gnew.

You can choose not to see this dialog box for every instance of renaming. You
can also set your preferences on whether ex pre ssio n s should be updated.
To select preferences for renaming:

1 Select File > Preferences. The Preferences dialog box opens.

23

SimBiology®Release Notes

2 Click Rename to view and select default renaming options.

You can also specify whether to update expressions while renaming a
component in the Compartment, Species,orParameter panes. Right-click
(Windows or Linux
compartment table and select Rename. Thisallowsyoutoselectwhetherto
use the new name in all expressions referring to the component.

®

)orCtrl+click (Macintosh) the species, parameters, or

Compatibility Considerations

Previously, if you changed the name in a table or the diagram, expressions
that used the components were not updated unless you selected Rename in
Expressions from the context menu. Now the default is to change the name
in expressions. But, you will see a dialog box that allows you to cancel the
action if necessary, and you can specify the default as shown in “Additional
Options for Renaming Compartments, Species, and Parameters” on page 23.

Change in the Random Number Generator Used
During Stochastic Simulations

The default random number generator used during stochastic simulation
has changed. The stochastic solver now uses the random numbers from the
MATLAB default stream. When you run a model using a stochastic solver,
and have set the
different simulation results relative to previous releases because the random
numbers used may be different.

RandomState property in the configuration set, you may se e

24

For more information about the change to the random number generator, see
Upgrade to Random Number Generator in the MATLAB release notes.

Compatibility Considerations

If you never set the RandomState property, there should be no compatibility
considerations. If however, you have previously set
model and want to reproduce your previous results, type
at the command line before running the simulation. This sets the random
number generator to the one used in previous releases.

RandomState for your

rand('state',0);

Version 2.4 (R2008b) SimBiology®Software

Functions and Pr

For more informa
Functions Being

Function or Property
Name

sbioevent

sbiopara

sbioreaction

Mode

argu

iorule

sb

meter

l name

ment for

as an input

sbioroot

operties Being Removed

tion about the process of removing functions, see “About

Removed” in “What Is in the Release Notes” on page 2.

What
Happens
When
You Us e
Function
or
Property?

Errors

Errors

Errors

Errors

Errors

Use This Instead Compatibility

Considerations

addevent

Events must
model. Rep
instances
with ad dev

addparam

eter

Parameters must belong
to a model or a kinetic
law. Replace all existing
instances of
with addparame ter.

addreaction

Reactions must belong to a
model. Replace all existing
instances of
with addreac tion .

sbioselect

drule

ad

root

sbio

el name as an input

amod

ment. Use

argu

uery models by name.

to q

Rules must belong to a
model. Replace all existing
instances of

addrule.

belong to a

lace all existing

of

sbioevent

ent

.

sbioparameter

sbioreaction

does not accept

sbioselect

sbiorule with

25

SimBiology®Release Notes

Function or Property
Name

sbiospecies

sbioregisterunit

sbiounregisterunit

sbioregisterunitprefix

sbiounregisterunitprefix

BuiltInKineticLaws

BuiltInUnitPrefixes

BuiltInUnits

What
Happens
When
You Us e
Function
or
Property?

Errors

Errors

Errors

Errors

Errors

Errors

Errors

Errors

Use This Instead Compatibility

Considerations

addspecies

Species must belong to
a compartment. Replace
all existing instances
of

sbiospecies with

addspecies.

Unit object and
sbioaddtolibrary

See “New Way to Add Units
and Unit Prefixes” on p a ge

40.

sbioremovefromlibrary

See “New Way to Add Units
and Unit Prefixes” on p a ge

40.

Unit object and
sbioaddtolibrary

See “New Way to Add Units
and Unit Prefixes” on p a ge

40.

sbioremovefromlibrary

See “New Way to Add Units
and Unit Prefixes” on p a ge

40.

BuiltInLibrary

See “Changes to the Library
Structure in the Root” on
page 37.

BuiltInLibrary

See “Changes to the Library
Structure in the Root” on
page 37.

BuiltInLibrary

See “Changes to the Library
Structure in the Root” on
page 37.

26

Version 2.4 (R2008b) SimBiology®Software

Function or Property
Name

UserDefinedKineticLaws

UserDefinedUnits

UserDefinedUnitPrefixes

What
Happens
When
You Us e
Function
or
Property?

Errors

Errors

Errors

Use This Instead Compatibility

Considerations

UserDefinedLibrary

See “Changes to the Library
Structure in the Root” on
page 37.

UserDefinedLibrary

See “Changes to the Library
Structure in the Root” on
page 37.

UserDefinedLibrary

See “Changes to the Library
Structure in the Root” on
page 37.

27

SimBiology®Release Notes

Version 2.3 (R2008a) SimBiology Software

This table summarizes what’s new in Version 2.3 (R2008a):

New Features and
Changes

Yes
Details below

New features and changes introduced in this version are:

• “Support for 64-Bit Microsoft Windows” on page 28

• “Functions and Properties Being Removed” on page 28

Support for 64-Bit Microsoft Windows

SimBiology software now has added support for 64-bit Windows (Win64).

Functions and Properties Being Removed

For more information about the process of removing functions, see “About
Functions Being Removed” in “What Is in the Release Notes” on page 2.

Function or Property
Name

sbioevent

sbioparameter

Ver sion
Compatibility
Considerations

Yes
Summary

What
Happens
When
You Us e
Function
or
Property?

Warns

Warns

Fixed Bugs and
Known Problems

Bug Reports
Includes fixes

Use This Instead Compatibility

addevent

addparameter

Related
Documentation at
Web Site

No

Considerations

Events must belong to a
model. Replace all existing
instances of
with ad deve nt.

Parameters must belong
to a model or a kinetic
law. Replace all existing

sbioevent

28

Version 2.3 (R2008a) SimBiology®Software

Function or Property
Name

sbioreaction

Model name as an input

argument for

sbiorule

sbiospecies

sbioregisterunit

sbiounregisterunit

sbioregisterunitprefix

sbioroot

What
Happens
When
You Us e
Function
or
Property?

Warns

Errors

Warns

Warns

Errors

Errors

Errors

Use This Instead Compatibility

Considerations

instances of sbiopa rameter
with addparame ter.

addreaction

Reactions must belong to a
model. Replace all existing
instances of

sbioreaction

with addreac tion .

sbioselect

sbioroot

does not accept
a model name as an input
argument. Use
to query models by name.

addrule

Rules must belong to a
model. Replace all existing

addspecies

instances of

addrule.

Species must belong to

sbiorule with

a compartment. Replace
all existing instances
of

sbiospecies with

addspecies.

Unit object and
sbioaddtolibrary

See “New Way to Add Units
and Unit Prefixes” on p a ge

40.

sbioremovefromlibrary

See “New Way to Add Units
and Unit Prefixes” on p a ge

40.

Unit object and
sbioaddtolibrary

See “New Way to Add Units
and Unit Prefixes” on p a ge

40.

sbioselect

29

SimBiology®Release Notes

Function or Property
Name

sbiounregisterunitprefix

BuiltInKineticLaws

BuiltInUnitPrefixes

BuiltInUnits

UserDefinedKineticLaws

UserDefinedUnits

UserDefinedUnitPrefixes

What
Happens
When
You Us e
Function
or
Property?

Errors

Errors

Errors

Errors

Errors

Errors

Errors

Use This Instead Compatibility

Considerations

sbioremovefromlibrary

See “New Way to Add Units
and Unit Prefixes” on p a ge

40.

BuiltInLibrary

See “Changes to the Library
Structure in the Root” on
page 37.

BuiltInLibrary

See “Changes to the Library
Structure in the Root” on
page 37.

BuiltInLibrary

See “Changes to the Library
Structure in the Root” on
page 37.

UserDefinedLibrary

See “Changes to the Library
Structure in the Root” on
page 37.

UserDefinedLibrary

See “Changes to the Library
Structure in the Root” on
page 37.

UserDefinedLibrary

See “Changes to the Library
Structure in the Root” on
page 37.

30

Version 2.2 (R2007b+) SimBiology®Software

Version 2.2 (R2007b+) SimBiology Software

This table summarizes what’s new in Version 2.2 (R2007b+):

New Features and
Changes

Yes
Details below

Ver sion
Compatibility
Considerations

Yes—Details labeled
as Compatibility
Considerations,
below. See also
Summary.

New features and changes introduced in this version are:

• “Changes to the Model Structure” on page 31

• “Events” on page 33

• “Variants” on page 33

• “Support for Analysis Tasks in the Desktop” on page 34

• “Changes to the Library Structure in the Root” on page 37

• “New Features for Solvers and Simulation Settings” on page 38

• “New Plot Functions” on page 40

• “New Sensitivity Analysis PropertyforSpeciesOutputs”onpage40

• “New Way to Add Units and Unit Prefixes” on page 40

Fixed Bugs and
Known Problems

Bug Reports
Includes fixes

Related
Documentation at
Web Site

No

• “Functions and Properties Being Removed” on page 41

Changes to the Model Structure

The following new features and changes apply to a model’s structure:

• “Compartments Now Supported” on page 32

• “Submodel Support Will Be Removed” on page 32

31

SimBiology®Release Notes

Compartments Now Supported

SimBiology models now let you add compartments to a model, specify
compartment size, simulate, and do analysis with multiple compartments.
Any model co ntaining species must have a compartment, and the species
must belong to a compartment. You can also perform dimensional analysis
and unit conversion accounting for the specified compartment size. For
more information on compartments, refer to the following sources in the
documentation:

• “Compartment” — Introduction to compartments in the SimBiology Getting

Started Guide.

•

Compartment object — Reference for compartment objects.

Submodel Support Will Be Removed

Support for submodels will be removed in a future release. You can still open
models containing submodels and create submodels, but you cannot simulate
or perform any analysis tasks on the model. Therefore, you should transition
to using compartments where applicable.

32

Compatibility Cons id er ati ons . If you have submodels in your previously
created model, you can still open your model, but you must convert the
submodels into top-level SimBiology models to be able to perform any tasks.

To convert submodels, use

sbioupdate.

If you open a model that contains submodels in the SimBiologydesktop, the
submodels are automatically converted to models and placed in separate
model sessions. See

As a result o f removing submodels, the
of the model object are no longer relevant. You can still access the

sbioupdate for more information.

addmodel method and Models property

addmodel

method and the Models property for this version of the software, though it
may be removed in a future release.

Version 2.2 (R2007b+) SimBiology®Software

Events

You can now add events to SimBiology models. Use events to describe sudden
changes in a model system. Events are supported only by the
and the stochastic solver

For more information on events, refer to the following:

• “Events” — Introduction to events in the SimBiology Getting Started Guide.

• “Changing Model Component Values Using Events” — Discussion about

events including how events are evaluated in the SimBiology User’s Guide.

•

Event object — Reference for event objects.

• “Sundials Solvers” — Deterministic solver for simulating models with

events in the SimBiology User’s Guide.

Models containing events do not s upport sensitivity analysis.

ssa.

sundials so lver

Variants

Variants let you store the names and values of model components and use the
values stored in a variant as the alternate value to apply during a simulation.
You can store values for species
compartment

Capacity in a variant.

InitialAmount,parameterValue,and

For more information on variants, refer to the following:

• “Variants” — Introduction to variants in the SimBiology Getting Started

Guide.

•

Variant object — Reference for variant objects in the SimBiology

Reference.

• “Desktop Example — Applying Changes to Parameter Value Using a

Variant” — Example in a tutorial in the SimBiology Model Reference.

In the SimBiology desktop, expand Model Variable Settings and
double-click Variants to open the Variants pane. The SimBiology Desktop
Help updates with more information on adding and setting variants. If the
help is not open in the desktop, select Help > SimBiology Desktop Help.

33

SimBiology®Release Notes

Support for Analysis Tasks in the Desktop

The SimBiologydesktop now supports adding and managing analysis tasks
through the following features:

34

• “Task Manager” on page 34

• “Sensitivity Analysis in the Desktop” on page 35

• “Scanning and Scanning with Sensitivities in the Desktop” on page 36

• “Ensemble Simulation Runs in the Desktop” on page 36

• “Conserved Cycle Calculations in the Desktop” on page 36

• “Create Custom Analysis Tasks” on page 37

• “Generate Reports for Projects” on page 37

Task Manager

The Task Manager lets you add and manage simulation and analysis tasks.
In the Project Explorer, double-click Model Session.TheModel Session
pane opens with the Task Manager listed on the right.

Version 2.2 (R2007b+) SimBiology®Software

Click a task to add it to your model. The desktop adds the task to the
Project Explorer and op ens the task pane. For more information on
setting up and running a task in the desktop, open the task pane and select
Help > SimBiology Desktop Help to see the context-sensitive help.

Sensitivity Analysis in the Desktop

Sensitivity analysis is now supported in the desktop. Sensitivity analysis
was previously available only through command line. Sensitivity analysis
lets you calculate the time-dependent sensitivities of a species specified in
SpeciesOutputs with respect to species initial conditions and parameter
values.

35

SimBiology®Release Notes

See “Performing Sensitivity AnalysisUsingtheDesktop”intheSimBiology
User’s Guide for more information. You must have a model in the desktop
for this feature to be enabled.

For more information on sensitivity a nalysis, see “Sensitivity Analysis” in
the SimBiology User’s Guide.

Scanning and Scanning with Sensitivities in the Desktop

You can perform species and parameter scanning analysis alone or in
combination with sensitivity analysis in the d esk t op . Scan a parameter value
or a species initial amount to determine the effect of a range of values of the
parameterorspecies.

Combine the scan with sensitivity analysis to explore the sensitivity of a
species with respect to a range of values of a paramet er or a species.

Forinformationonhowtoaddthetasktoamodel,see“TaskManager”on
page 34. For more information on setting up and running the task in the
desktop, open the task pane and select Help > SimBiology Desktop Help
to see the context-sensitive help. Youneedamodelinthedesktopforthis
featuretobeenabled.

36

Ensemble Simulation Runs in the Desktop

The SimBiologydesktop now supports ensemble simulations. You can perform
ensemble simulations using the stochastic solvers to gather data from
multiple stochastic runs of the model.

See “Running Ensemble Simulations in the Desktop” in the SimBiology User’s
Guide for more information. You need a mode l in the desktop for this feature
to be enabled.

Conserved Cycle Calculations in the Desktop

The SimBiologydesktop now supports conserved cycle calculations. This
feature l ets you calculate a complete set of linear conservation relations for
the species in a SimBiology model object. For an introduction, see “Moiety
Conservation” in the SimBiology User’s Guide .

Version 2.2 (R2007b+) SimBiology®Software

Forinformationonhowtoaddthetasktoamodel,see“TaskManager”on
page 34. For more information on setting up and running the task in the
desktop, open the task pane and select Help > SimBiology Desktop Help
to see the context-sensitive help. Youneedamodelinthedesktopforthis
featuretobeenabled.

Create Custom Analysis Tasks

The SimBiologydesktop lets you create custom tasks that are associated with
a project. You can either write new code or copy and modify task code from
built-in tasks in the desktop. For more information about creating custo m
tasks, see “Desktop Example — Creating Custom Analysis” in the SimBiology
User’s Guide.

Forinformationonhowtoaddthetasktoamodel,see“TaskManager”on
page 34. For more information on setting up and running the task in the
desktop, open the task pane and select Help > SimBiology Desktop Help
to see the context-sensitive help. Youneedamodelinthedesktopforthis
featuretobeenabled.

Generate Reports for Projects

You can now generate reports for your projects. Report templates let you
generate a report with specified information about a model. To generate a
template, in the Project E xplorer,clickReport Templates to open the
Report Templates pane. Select Help > SimBiology Desktop Help to see
the context-se ns itive help for information on how to generate reports.

Changes to the Library Structure in the Root

Built-in and user-defined libraries for units, unit prefixes, and abstract kinetic
laws are now organized under two root object properties,

UserDefinedLibrary, with subcategories for units, unit prefixes, and abstract

kinetic laws. See
in SimBiology Reference for more information.

Root object, BuiltInLibrary,andUserDefinedLibrary

Compatibility Considerations

In previous versions, the libraries were organized under six properties:

•

UserDefinedKineticLaws

BuiltInLibrary and

37

SimBiology®Release Notes

• BuiltInKineticLaws

• UserDefinedUnits

• BuiltInUnits

• UserDefinedUnitPrefixes

• BuiltInUnitPrefixes

The changes to the library structure improve the organization of root object
properties.

To illustrate the change using an example, previously you would access a
user-defined kinetic law using the following syntax:

rootObj = sbioroot;
get(rootObj, 'UserDefinedKineticLaws')

You must now use the following syntax:

rootObj = sbioroot;
get(rootObj.UserDefinedLibrary, 'KineticLaws')

38

New Features for Solvers and Simulation Settings

The following new features and changes apply to solvers and simulation
settings:

• “Support for Sundials Solvers” on page 38

• “New Property in Configuration Sets to Specify Species Dimensions” on

page 39

• “SimData Object Holds All Si mulation Data” on page 39

Support for Sundials Solvers

The Sundials package of solvers has been added in this release. The Sundials
solvers are part of a freely available third-party package developed at
Lawrence Livermore National Laboratory. Models that contain events are
supported by the Sundials solver s and by the stochastic solver
information, see “Sundials Solvers” in the SimBiology U ser’s Guide.

ssa.Formore

Version 2.2 (R2007b+) SimBiology®Software

New Property in Configuration Sets to Specify Species
Dimensions

The new property DefaultSpeciesDimension lets you specify whether the
default species dimensions should be

concentration (default) or substa nce.

This property thus lets you specify whether the solver should account for
compartment capacity. If however, you specify the species units in the

InitialAmountUnits property, these units define the species dimension

regardless of the value in

DefaultSpeciesDimension.

SimData Object Holds All Simulation Data

The SimBiology SimData object now stores the data returned from any
simulation. For example, the output from the
now stored in a

SimData object which holds time and state data as well

as metadata, such as the types and names for the logged states or the
configuration set used during simulation.

You can also store data from multiple simulation runs as an array of SimData
objects. Thus, the output of
objects. See

SimData object for more information and a list of methods and

sbioensemblerun is an array of SimData

properties.

sbiosimulate function is

Compatibility Considerations. The SimData object is now the preferred
container for simulation and analysis task data. Previously, simulation and
analysis data w ere stored as time series objects. Functions that used to
return time series objects now return SimData objects. If you have time series
objects in your projects, you can convert them using

sbioupdate. Functions

that used to take a time series object as an input argument now take SimData
object. You can use time series objects in an input argument, but you see a
warning. Support for time series objects in SimBiology functions may be
removed in a future version.

The

sbiogetsensmatrix and sbiogetnamedstate functions are being

replaced by the SimData object methods

getsensmatrix and selectbyname

respectively.

39

SimBiology®Release Notes

New Plot Functio

Therearetwonew
functions let yo
Object Holds Al

sbioplot plot

objects from a
the object. Th
tree, where y

sbiosubplot

objects int
object. You
subset of th

New Sensit

u plot data directly from the SimData object (see “SimData

l Simulation Data” on page 39).

s each simulation run for a SimData object or array of SimData

model in the same figure. The plot is a time plot of each state in

e figure also shows a hierarchical display of all the runs in a

ou can choose which trajectories to show.

plotseachsimulationrunforaSimDataobjectorarrayof

o its own subplot. The subplot is a time plot of each state in the

can navigate through the plots in the figure window and select a
e plots to view.

ivity Analysis Property fo r Species

ns

plot functions —

sbioplot and sbiosubplot.Both

Outputs

To set up s
called
you want

Compatibility Considerations

Previo
the spe
improv

ensitivity analysis, you must now specify an additional property

eciesOutputs

Sp

to compute sensitivities.

usly, sensitivity analy s is used the species specified in

cies for which sensitivities should be calculated.

es the functionality by separating the use of the properties.

.InSpeciesOutputs, specify the species for which

StatesToLog as

SpeciesOutputs

40

have models from a previous version configured for sensitivity analysis,

If you
you mu

Speci

give
to us
this

Spec

New

Un
an

st specify species for which you want to compute sensitivities in the

esOutputs

sawarningthatthe

e the species specified in

context may not be available in a future version, so you should set the

iesOutputs

property. Until this property is specified, sensitivity analysis

SpeciesOutputs property is not set, and continue s

StatesToLog. The use of StatesToLog in

property for your models, if applicable.

Way to Add Units and Unit Prefixes

its and unit prefixes are now represented by objects. You can create units

d prefixes and add them to the user-defined library using the function

Version 2.2 (R2007b+) SimBiology®Software

sbioaddtolibrary.SeeUnit object and UnitPrefix object for more

information.

Compatibility Considerations

Previously, sbioregisterunit and sbiounregisterunit created and
removed units respectively. These functions now produce warnings and will
be removed in a future version. Use unit objects and
instead.

sbioremovefromlibrary

Similarly,
created and removed unit prefixes respectively. These functions now produce
warnings and will be removed in a future version. Use unit prefix objects
and

sbioremovefromlibrary instead.

Functions and Properties Being Removed

For more information about the process of removing functions, see “About
Functions Being Removed” in “What Is in the Release Notes” on page 2.

Function or Property Name

addmodel

Models

sbioregisterunitprefix and sbiounregisterunitprefix

What
Happens

Use This Instead Compatibility

Considerations
When
You Us e
Function
or
Property?

Warns

addcompartment,where

applicable

See “Submodel

Support Will Be

Removed” on page

32.

Still runs

Compartments,where

applicable

See “Submodel

Support Will Be

Removed” on page

32.

41

SimBiology®Release Notes

Function or Property Name

Model name as an input

argument for

sbioregisterunit

sbiounregisterunit

sbioregisterunitprefix

sbiounregisterunitprefix

sbiogetsensmatrix

sbioroot

What
Happens
When
You Us e
Function
or
Property?

Warns

Warns

Warns

Warns

Warns

Warns

Use This Instead Compatibility

Considerations

sbioselect

sbioroot

does not
accept a model
name as an input
argument. Use

sbioselect to

query models by
name.

Unit object and
sbioaddtolibrary

See “New Way to
Add Units and
Unit Prefixes” on
page 40.

sbioremovefromlibrary

See “New Way to
Add Units and
Unit Prefixes” on
page 40.

Unit object and
sbioaddtolibrary

See “New Way to
Add Units and
Unit Prefixes” on
page 40.

sbioremovefromlibrary

See “New Way to
Add Units and
Unit Prefixes” on
page 40.

getsensmatrix

See “SimData
Object Holds All
Simulation Data”
on page 39.

42

Version 2.2 (R2007b+) SimBiology®Software

Function or Property Name

sbiogetnamedstate

BuiltInKineticLaws

BuiltInUnits

BuiltInUnitPrefixes

UserDefinedKineticLaws

UserDefinedUnits

UserDefinedUnitPrefixes

What
Happens
When
You Us e
Function
or
Property?

Warns

Warns

Warns

Warns

Warns

Warns

Warns

Use This Instead Compatibility

Considerations

selectbyname

See “SimData
Object Holds All
Simulation Data”
on page 39.

BuiltInLibrary

See “Changes
to the Library
Structure in the
Root” on page 37.

BuiltInLibrary

See “Changes
to the Library
Structure in the
Root” on page 37.

BuiltInLibrary

See “Changes
to the Library
Structure in the
Root” on page 37.

UserDefinedLibrary

See “Changes
to the Library
Structure in the
Root” on page 37.

UserDefinedLibrary

See “Changes
to the Library
Structure in the
Root” on page 37.

UserDefinedLibrary

See “Changes
to the Library
Structure in the
Root” on page 37.

43

SimBiology®Release Notes

Version 2.1.2 (R2007b) SimBiology Software

This table summarizes what’s new in Version 2.1.2 (R2007b):

New Features and
Changes

No No Bug Reports No

Ver sion
Compatibility
Considerations

Fixed Bugs and
Known Problems

Related
Documentation at
Web Site

44

Version 2.1.1 (R2007a) SimBiology®Software

Version 2.1.1 (R2007a) SimBiology Software

This table summarizes what’s new in Version 2.1.1 (R2007a):

New Features and
Changes

No No Bug Reports No

Ver sion
Compatibility
Considerations

Fixed Bugs and
Known Problems

Related
Documentation at
Web Site

45

SimBiology®Release Notes

Version 2.1 (R2006b+) SimBiology Software

This table summarizes what’s new in Version 2.1 (R2006b+):

New Features and
Changes

Yes
Details below

Ver sion
Compatibility
Considerations

Yes—Details labeled
as Compatibility
Considerations,
below. See also
Summary.

New features and changes introduced in this version are:

• “Printing and Exporting the Diagram” on page 46

• “Diagram Menu” on page 46

• “Block Overview Tool” on page 47

• “Miscellaneous Desktop Enhancements” on page 47

Fixed Bugs and
Known Problems

Bug Reports
Includes fixes

Related
Documentation at
Web Site

No

Printing and Exporting the Diagram

You can annotate and print your pathway’s block diagram in SimBiology, or
export the diagram using
can annotate the diagram with the name of the author, the date, notes, and
name of the organization. You can choose to place this content as a header or
footer on the diagram page.

.svg, . jpeg,or.pdf file formats. For example, you

46

Diagram Menu

The SimBiology desktop supports multiple diagra m features and actions
through the Diagram menu. Use the menu options to do the following:

• Copy, paste, and delete blocks.

• Select model or diagram components by category (for example, select all

lines or all S pecies blocks).

Version 2.1 (R2006b+) SimBiology®Software

• Filter selected portions of a model diagram to include only model or

diagram components b y category.

• Edit multiple blocks or lines.

• Add selected blocks to a Block Library.

• Annotate and print, or export your model diagram.

• Perform layout tasks, for example, hide and show blocks, move blocks to the

front or back of a diagram, rotate a block, and pin or unpin selected blocks.

• Copy the style of a block and apply the style to a group of selected blocks.

• Reload a graphic used for a block in the Block Properties dialog box.

• Access diagram tools such as the Diagram Table View, Block L ibrary

Browser, Diagram Overview, and Block Overview.

Compatibility Considerations

There is a compatibility consideration regarding the s upport for editing
multiple blocks or lines. In SimBiology Versions 2.0 and 2.0.1, if you selected
multiple blocks and/or lines and applied an editing action such as Hide, Pin,
or Hide Name, the action applied only to the block on w hich you selected the
right-click (context) menu. Starting in Version 2.1, applicable editing actions
arepropagatedtoallselectedblocks.

Block Overview Tool

The Block Overview tool provide s a summary of key information about
a particular block. Hover the mouse over a block to find information in
the Block Overview pane. Each block includes information pertinent
to that type of block, for example, a species block overview shows Name,
InitialAmount, InitialAmountUnits, the number and list of reactions
the species is involved in, and a descriptionofanyindicatorsshowninthe
diagram.

Miscellaneous Desktop Enhancements

The enhancements for the SimBiologydesktop let you do the following:

47

SimBiology®Release Notes

• Set your preference to open a SimBiology pane with a single-click in the

Project Explorer. Select File > Preferences to open the Preferences
dialog box.

• Interrupt and stop m odel verification by clicking Stop when Verify is

running.

• Sorttheavailableplot arguments in the Simulation and Data panes. The

XandYargumentlistsarenowtabulated.

• View a species and any of its cloned blocks from the search results for the

species.

• Select and view multiple results for Find and Bookmarks in either the

diagram or the table form.

48

Version 2.0.1 (R2006b) SimBiology®Software

Version 2.0.1 (R2006b) SimBiology Software

This table summarizes what’s new in Version 2.0.1 (R2006b):

New Features and
Changes

No No Bug Reports

Ver sion
Compatibility
Considerations

Fixed Bugs and
Known Problems

Includes fixes

Related
Documentation at
Web Site

No

49

SimBiology®Release Notes

Version 2.0 (R2006a+) SimBiology Software

This table summarizes what’s new in Version 2.0 (R2006a+):

New Features and
Changes

Yes
Details below

Ver sion
Compatibility
Considerations

Yes—Details labeled
as Compatibility
Considerations,
below. See also
Summary.

New features and changes introduced in this version are:

• “Diagram Interface” on page 50

• “Find and Bookmarks in Projects” on page 51

• “Sensitivity Analysis” on page 51

• “Parameter Estimation” on page 52

• “Ensemble Simulation Runs” on page 52

• “Moiety Conservation” on page 52

• “Model Verification and Validation” on page 53

• “Simulation and Solvers” on page 53

• “New Demos for SimBiology Version 2.0” on page 54

Fixed Bugs and
Known Problems

Bug Reports
Includes fixes

Related
Documentation at
Web Site

No

50

Diagram Interface

The Diagram is a graphical user interface you can use to enter model pathways
using block representations for species, reactions, and submodels. Use the
Plot block to visualize simulation data during a simulation. For a tutorial, see
“Modeling U sing the SimBiology Diagram” in the SimBiology Getting Started
Guide. You can also access video demos from a list of SimB iology demos.

Version 2.0 (R2006a+) SimBiology®Software

Find and Bookmar

• Find —Typeastri

components in t

• Bookmarks —Us

create a custo

he project and in abstract kinetic laws.

m a nd persistent set of desktop and project objects.

ks in Projects

ng in the Find box to quickly find matching model

ecomplexrulestoidentifyobjectsfromtheproject,and

Compatibility Considerations

In Versions 1
the project s
search into
is saved and
search, you
than a sear

All functi
bookmark
search ro
and or,wh

all or an

Sensiti

You can

.0 and 1.0.1, SimBiology projects saved searches. In Version 2.0,

aves bookmarks. The software converts a previous version’s saved

a b ookmark. After you save a project in Version 2.0, a bookmark

the old search is no longer available. If a project contains a

see a warning that the project file will contain a bookmark rather

ch after saving.

onality available in Version 1.0 searches are present in Version 2.0

s except for the ability to mix and match

ws. If you have a multiple-row search saved with a mixture of

en you load this project into Version 2.0, it is converted to either

y

based on whether the software first encounters and or or.

vity Analysis

perform sensitivity analysis using the following properties:

and and or between t h e

and

•

Sensit

the ti

State

param

•

Sens

anal

Sens

- Spec

- Par

ivityAnalysis

me-dependent sensitivities of all the species states defined by the

sToLog

eter values.

itivityAnalysisOptions

ysis options in the configuration set object. Properties of

itivityAnalysisOptions

t to compute the sensitivities of the species states in your model.

wan

ameterInputFactors

ch you want to compute the sensitivities of the species states in your

whi

del.

mo

property with respect to species initial conditions and

iesInputFactors

— Configuration set property that lets you calculate

— An object that holds the sensitivity

are summarized below:

— Specify the species with respect to which you

— Specify the parameters with respect to

51

SimBiology®Release Notes

- Normalizatio n — Specify the normalization for the calculated

sensitivities.

For an introduction and an example, see “Sensitivity Analysis” in the
SimBiology User’s Guide.

Parameter Estimation

The sbioparamestim function lets you estimate any or all parameters in
your model using the experimental data you provide. The software uses the
optimization functions in the MATLAB, Optimization Toolbox™, and Global
Optimization Toolbox software to enable parameter estimation.

Optimization Toolbox and Global Optimization Toolbox software are not
required for you to use
installed,

For an introduction and an example, see “Parameter Estimation” in the
SimBiology User’s Guide.

sbioparamestim uses the MATLAB function fminsearch by default.

sbioparamestim. If you do not have these products

52

Ensemble Simulation Runs

You can perform ensemble simulations using the stochastic solvers to gather
data from multiple stochastic runs of the model. The following functions let
you perform ensemble runs:

•

sbioensemblerun — P erforms multiple stochastic ensemble runs of the

SimBiology model object.

•

sbioensembleplot — Shows a 2-D distribution plot or a 3-D shaded plot

ofthetimevaryingdistributionofone or more specified species in the
ensemble data generated by

sbioensemblestats — Gets mean and variance as a function of time for all

•

the species in the ensemble data generated by

sbioensemblerun.

sbioensemblerun.

Moiety Conservation

The sbioconsmoiety function lets you calculate a com plete set of linear
conservation relations for the species in a SimBiology model object.

Version 2.0 (R2006a+) SimBiology®Software

For an introduction and an example, see “Moiety Conservation” in the
SimBiology User’s Guide.

Model Verification and Validation

SimBiology software performs model verification and validation eith er during
simulation, or whe n you explicitly execute the commands for verification
before simulation.

Verification at the Command Line

The following new functions let you verify and validate, at the command line,
that your model is ready for simulation:

•

verify — Performs checks on a model to verify that you can simulate the

model. You see stacked errors and warnings if any problems are found.
To see the entire list of errors and warnings, use

sbiolastwarning.

sbiolasterror — Returns a SimBiology diagnostic structure array

•

containing the last errors that are generated.

sbiolasterror and

•

sbiolastwarning — Returns a SimBiology diagnostic structure array

containing the last warnings that are generated.

Verification on the SimBiology Desktop

Click the Verify button on the SimBiology desktop toolbar to perform
verification and validation of your model. The Output pane opens to show the
errors and warnings. You can double-click a result row to go to the location of
theerrororwarning.

Simulation and Solvers

The following new features and changes apply to simulation settings and
solvers:

•

MaxStep — Lets you specify the upper bound on solver step size for a

deterministic solver.

• Implicit Tau solver settings —For

holds the value for convergence tolerance fo r the nonlinear solver that

MaxStep is a property of the SolverOptions object.

impltau, AbsoluteTolerance

53

SimBiology®Release Notes

is used internally by the Implicit Tau solver. You can now specify

AbsoluteTolerance for impltau. Previously, if you selected the Implicit

Tau solver, the software ignored any changes to the

AbsoluteTolerance

and RelativeTolerance options within a configuration set and used the
default values set internally.

•

UnitConversion — Supported by both deterministic solvers and stochastic

solvers. Previously

UnitConversion was supported only by the stochastic

solvers.

Implicit Tau Solver Settings Compatibility Considerations

The RelativeTolerance property is no longer valid for the Implicit Tau
(

impltau)solver.

When you load a file created in a previous version, the project loads the

RelativeTolerance property. But when you save the file, the software

updates the change.

Unit Conversio n Compatibility Considerations

The UnitConversion property default is now 'false'.Ifyouloada
SimBiology project created in a previous version into the SimBiology desktop,
the

UnitConversion setting in each model in the project remains as the s aved

setting. If however, you are running a script, you must now remember to set
the

UnitConversion property to true if you want the software to perform

unit conversions

54

New Demos for SimBiology Version 2.0

There are 14 new demos for SimBiology Version 2.0. Click SimBiology
demos or type

demo('MATLAB', 'SimBiology') at the command prompt.

Version 1.0.1 (R2006a) SimBiology®Software

Version 1.0.1 (R2006a) SimBiology Software

This table summarizes what’s new in Version 1.0.1 (R2006a):

New Features and
Changes

Yes
Details below

Ver sion
Compatibility
Considerations

No Bug Reports No

The changes introduced in this version are:

• The characters

supported in rules.

• Rules are now supported in submodels.

\, ^,and* in species and parameter names are now

Fixed Bugs and
Known Problems

Related
Documentation at
Web Site

55

SimBiology®Release Notes

Version 1.0 (R14SP3+) SimBiology Software

This table summarizes what’s new in Version 1.0 (R14SP3+):

New Features and
Changes

Yes
Details below

Version
Compatibility
Considerations

No Bug Reports No

The features introduced in this version are:

• “Introduction” on page 56

• “Features” on page 57

• “Known Software Problems” on page 57

• “Upgrading from a Beta Release” on page 61

Fixed Bugs an d
Known Problems

Related
Documentation at
Web Site

Introduction

SimBiology Version 1.0 (Release 14SP3+) is an integrated environment for
modeling biological proce sses, simulating the dynamic behavior of these
processes, and analyzing simulation and experimental data. Biological
processes include metabolic, genetic, and signaling pathways with transform,
binding, and transport reactions. You can use SimBiology software as a tool
in three major areas:

• Model — Design and build m odels by entering model components with a

graphical desktop interface, or use the MATLAB Command Window.

56

• Simulate — Select deterministic or stochastic solvers and observe the

changes in species amounts and variable parameter values over time.

• Analyze — Log data from a simulation and export the data to the MATLAB

workspace. Compare simulation with experimental data for parameter
estimation and model validation.

Version 1.0 (R14SP3+) SimBiology®Software

Features

The features in SimBiology Version 1.0 are the following:

• Graphical user interface — Provides access to the command-line

functionality through a g raphical user interface (GUI).

• Command-line interface — All the features are accessible and executable

from the MATLAB Command Window.

• Data formats and projects — Organize and save related models,

simulation data, and analysis results in project files. Save user-defined
kinetic laws and units. Share models by exporting SBML Level 2 files.

• Modeling — Create biological models by adding components that include

reactions, species, parameters, kinetic laws, rules, and submodels.

• Simulation — Select either deterministic or stochastic solvers with

dimensional analysis and unit conversion.

• Analysis — SimBiology so ftware is fully integrated with MATLAB. Record

data during a simulation and analyze results in MATLAB.

Known Software Problems

To vie w important open bugs for SimBiology Version 1.0, use the Bug Rep orts
interface on the MathWorks Web site.

Note If you are not already logged in to your MathWorks Account, when you
link to the Bug Reports interface (see below), you will be prompted to log in
or create an account.

Afteryouareloggedin,usethisBug Reports link. You will see the bug report
for SimBiology. The report is sorted with fixed bugs listed first, and then open
bugs. You can select the Status column to list the open bugs first.

If you are viewing these release notes in PDF form on the MathWorks Web
site, you can refer to the HTML form of the release notes on the MathWorks
Web site and use the link provided.

Software problems include unsupported SBML features and current feature
and function limitations.

57

SimBiology®Release Notes

Unsupported SBML Level 2 Version 1 Features

SimBiology software supports a subset of the SBML Level 2 Version 1
specification. Unsupported features include:

• Compartments — Model compartments are not supported. If an imported

SBML model has a sin gle compartment, the model is loaded as a top-level
model. If the model has multiple compartments, you see a warning and the
software does not load the SBML file.

• Volume — Volume is not supported and cannot be specified.

• Events—EventsinanSBMLfileareignored when you are importing

into a project.

• Piecewise kinetics — Models with piecewise kinetics are loaded in, but the

software ignores the definitions for piecewise kinetics.

• Function definitions — Models containing functional definitions are loaded,

but you see a warning and the software ignores the function definitions.

• MATLAB incompatible variable names in

have variable names incompatible with MATLAB in

UnitDefinition — Models that

UnitDefinition are

not loaded and you see an error message.

Functional Limitations

Simulation and Solvers

• Stochastic solvers support only mass action kinetics, while ODE solvers

support all built-in and user-defined kinetic laws.

• If you use a stochastic solver to simulateamodel,thesoftwareignoresany

rate, assignment, or algebraic rules if present in the model.

• If you have

stochastic solvers, note that the software assumes that volume is unity
during simulation. The stochastic solvers perform calculations using
species units in molecules. Therefore, if you specify the species units
in molecules per unit volume or moles per unit volum e, the software
assumes volume to be unity and converts species amounts to molecules
for simulation. The results are finally plotted in the units you specified
for the species.

DimensionalAnalysis and UnitConversion on for the

58

Version 1.0 (R14SP3+) SimBiology®Software

In addition, if you have reactions with stoichiometric coefficients greater
than or equal to
stochastic rate constants. For example,

v=k[R]^2.IfR is moles/liter, the deterministic rate constant k has units of
liter/mole-second. If the unit of species concentration is molecule,then

the stochastic rate constant

2k/NV

where N is Avogadro’s Number, 6.022e23 molecules/mole,andV

2, you need to convert the deterministic rate constants to

2R->Phas a reaction rate of

c has units of 1/molec ule- second,andc=

isthevolumeofthemodelinliters.

• When you select the Implicit Tau solver, the software ignores any

changes to

AbsoluteTolerance and RelativeTolerance options within a

configuration set and uses the default values that are set internally.

• By default,

logged. Variable parameters are those that have
or

false. If you choose the species to log, however, you cannot log the

StatesToLog is set to 'all ' and all variable parameters are

ConstantValue cleared

variable parameters.

• The characters

\, ^,and* in species and parameter names are not

supported in rules.

Units

• Stochastic solvers support dimensional analysis and unit conversion. ODE

solvers support dimensional analysis but not unit conversion.

• You can delete a unit that is being used in a model; however, you will see

an error when you try to simulate the model or export to SBML.

Submodels

• The context menus (right-click options) for the Species, Reaction,

Parameter and Rule nodes that appear beneath a submodel node all act

on the corresponding parent model node, and not on the submodel node.
For example, if you select Delete All Species in the submodel Species
node, this selection deletes the species in the parent model.

• Rules are not supported in submodels.

59

SimBiology®Release Notes

SBML Export Limitations

There are features in SimBiology software that are not supported in SBML.
When you export a model to an SBML file, you might lose some of these
features.

• Submodels are not supported by SBML export.

• The abstract kinetic law name and corresponding expression are not

supported by SBML, but the associated reaction rate equation is exported
to SBML.

• The properties

export.

Tag, UserData,andActive are not supported by SBML

Tips

Naming SimBiology Variables

• If you are using a species or parameter name that is not a valid MATLAB

variable name, do the following:

- Enclose the name in square brackets when writing a reaction rate

equation or a rule.

- Enter the name without brackets when you are creating the species or

parameter, or when you add a reaction.

For example, enclose
within brackets in reaction rates and rules, but, enter DNA polymerase+
or K_DNA polymerase+ when creating a species, adding a reaction, or
creating a parameter.

• The names

in abstract kinetic laws, reaction rates, and rules are considered to be
MATLAB code, the software evaluates
not as the value of species
interpreted to have three names,
to protect such variables.

i and j are reserved MATL AB characters. Because expressions

[DNA polymerase+] and [K_DNA polymerase+]

i or j as an imaginary number and

i or j. For example, an expression V*S*i/K is

V, S,andK, instead of four. Use brackets

60

If a variable in a reaction rate equation or rule has the same name as a
MATLABfunction,thesoftwareevaluatestheexpressionasacalltothe
MATLAB function. In general, when creating variable names, you should

Version 1.0 (R14SP3+) SimBiology®Software

avoid using MATLAB function names or variable names that are invalid
in MATLAB.

Changing SimBiology Variable Names

• If you change the

Name of a parameter you must configure all applicable

elements, such as rules that use the parameter, any user-specified

ReactionRate, or the kinetic law object property ParameterVariableNames.

Use the method

setparameter to configure ParameterVariableNames.

To update parameter names in the SimBiology graphical user interface,
access each appropriate pane through the Project Explorer.

• If you change the

Name of a spe cie s you must configure all applicable

elements, such as rules that use the parameter, any user-specified

ReactionRate, or the kinetic law object property SpeciesVariableNames.

Use the method

setspecies to configure SpeciesVariableNames.

To update species names in the SimBiology graphical user interface, access
each appropriate pane through the Project Explorer.Thesoftware
automatically updates species names for reactions that use

MassAction

kinetic law.

Upgrading from a Beta Release

Any projects that you created and saved with the SimBiology beta release
version will not load in Version 1.0.

As a workaround, before upgrading to Version 1.0, save your models to SBML,
upgrade to Version 1.0, and then import the SBML models into Version 1.0
projects. Alternatively, contact the MathWorks for help with your conversion.

61

SimBiology®Release Notes

Compatibility Summary for SimBiology Software

This table summarizes new features and changes that might cause
incompatibilities when you upgrade from an earlier version, or wh en you
use files on multiple versions. Details are provided in the description of the
new feature or change.

Version (Rel ea se) New Features and Chang e s with Version Compatibility

Impact

Latest Version
V3.2 (R2010a)

V3.1 (R2009b) See the following:

V3.0 (R2009a)

V2.4 (R2008b) See the Compatibility Considerations subheadings for:

See the Compatibility Considerations subheadings for:

• “Enhanced Support for Applying Dosing to a Model and Dosing

Multiple Compartments” on page 6

• “Support for Parameter Transformations” on page 8

See “Functions and Properties Being Removed” on page 9.

• “Unit Conversion Compatibility Considerations” on page 12

• “Functions and Properties Being Removed” on page 12

None

• “Support for Specifying Additional Inputs in Custom Plot Types”

on page 19

• “Additional Options for Renaming Compartments, Species, and

Parameters” on page 23

• “Change in the Random Number Generator Used During

Stochastic Simulations” on page 24

See “Functions and Properties Being Removed” on page 25.

V2.3 (R2008a) See “Functions and Properties Being Removed” on page 28.

62

Compatibility Summary for SimBiology®Software

Version (Rel ea se) New Features and Chang e s with Version Compatibility

Impact

V2.2 (R2007b+) See the Compatibility Considerations subheadings for:

• “Submodel Support Will Be Removed” on page 32

• “Changes to the Library Structure in the Root” on page 37

• “SimData Object Holds All Simulation Data” on page 39

• “New Sensitivity Analysis Property for Species Outputs” on

page 40

• “New Way to Add Units and Unit Prefixes” on page 40

See “Functions and Properties Being Removed” on page 41.

V2.1.2 (R2007b)

V2.1.1 (R2007a)

None

None

V2.1 (R2006b+) See the Compatibility Considerations subheading for “Diagram

Menu” on page 46.

V2.0.1 (R2006b)

None

V2.0 (R2006a+) See the Compatibility Considerations subheading for “Find and

Bookmarks in Projects” on page 51 and the following:

• “Implicit Tau Solver Settings C om patibility Considerations” on

page 54

• “Unit Conversion Compatibility Considerations” on page 54

V1.0.1 (R2006a)

V1.0 (R14SP3+)

None

None

63