addrule (model)

Create rule object and add to model object

Syntax

ruleObj = addrule(modelObj, Rule) ruleObj = addrule(modelObj, Rule, RuleType) ruleObj = addrule(..., 'PropertyName', PropertyValue,...)

Arguments

modelObj Model object to which to add the rule.

Rule Character vector specifying the rule. For example, enter the algebraic rule 'Va*Ea + Vi*Ei - K2'.

RuleType

Character vector specifying the type of rule. Choices are:

'algebraic'
'initialAssignment'
'repeatedAssignment'
'rate'

For more information, see RuleType

Description

A rule is a mathematical expression that changes the amount of a species or the value of a parameter. It also defines how species and parameters interact with one another.

ruleObj = addrule(modelObj, Rule) constructs and returns ruleObj, a rule object. In ruleObj, the rule object, this method assigns the modelObj input argument to the Parent property, assigns the Rule input argument to the Rule property, and assigns 'initialAssignment' or 'algebraic' to the RuleType property. (This method assigns 'initialAssignment' for all assignment rules and 'algebraic' for all other rules.) In modelObj, the model object, this method assigns ruleObj, the rule object, to the Rules property.

ruleObj = addrule(modelObj, Rule, RuleType) in addition to the assignments above, assigns the RuleType input argument to the RuleType property. For more information on the types of rules, see RuleType.

ruleObj = addrule(..., 'PropertyName', PropertyValue,...) defines optional properties. The property name/property value pairs can be in any format supported by the function set.

View additional rule properties with the function get, and modify rule properties with the function set. Copy a rule object to a model with the function copyobj, or delete a rule object from a model with the function delete.

Note

If you use the addrule method to create an algebraic rule, rate rule, or repeated assignment rule, and the rule expression is not continuous and differentiable, see Using Events to Address Discontinuities in Rule and Reaction Rate Expressions before simulating your model.

Method Summary

Methods for rule objects

copyobj	Copy SimBiology object and its children
delete	Delete SimBiology object
display	Display summary of SimBiology object
get	Get SimBiology object properties
rename	Rename SimBiology model component and update expressions
set	Set SimBiology object properties

Property Summary

Properties for rule objects

Active	Indicate object in use during simulation
Name	Specify name of object
Notes	HTML text describing SimBiology object
Parent	Indicate parent object
Rule	Specify species and parameter interactions
RuleType	Specify type of rule for rule object
Tag	Specify label for SimBiology object
Type	Display SimBiology object type
UserData	Specify data to associate with object

Examples

Add a rule with the default RuleType.

Create a model object, and then add a rule object.

modelObj = sbiomodel('cell');
ruleObj = addrule(modelObj, '0.1*B-A')

Get a list of properties for a rule object.

get(modelObj.Rules(1)) or get(ruleObj)

MATLAB displays a list of rule properties.

    Active: 1
    Annotation: ''
          Name: ''
         Notes: ''
        Parent: [1x1 SimBiology.Model]
          Rule: '0.1*B-A'
      RuleType: 'algebraic'
           Tag: ''
          Type: 'rule'
      UserData: []

Add a rule with the RuleType property set to rate.

Create model object, and then add a reaction object.

modelObj = sbiomodel ('my_model');
reactionObj = addreaction (modelObj, 'a -> b');

Add a rule which defines that the quantity of a species c. In the rule expression, k is the rate constant for a -> b.
```
ruleObj = addrule(modelObj, 'c = k*(a+b)')
```

Change the RuleType from default ('algebraic') to 'rate', and verify using the get command.

set(ruleObj, 'RuleType', 'rate');
get(ruleObj)

MATLAB returns all the properties for the rule object.

    Active: 1
Annotation: ''
      Name: ''
     Notes: ''
    Parent: [1x1 SimBiology.Model]
      Rule: 'c = k*(a+b)'
  RuleType: 'rate'
       Tag: ''
      Type: 'rule'
  UserData: []

Version History

Introduced in R2006a

expand all

R2022b: Having duplicate model component names issues a warning

SimBiology issues a warning if multiple model components (model, compartment, species, parameter, reaction, rule, event, observable, dose, and variant) have the same name. In a future release, within a single model, these components will be required to have unique names even when they are of different types with the following two exceptions:
- Species in different compartments can have the same name.
- Parameters can have the same name if they are scoped to different parents. Specifically, you can use the same name for a model-scoped parameter and reaction-scoped parameters, where each reaction-scoped parameter belongs to a different reaction.
The purpose of this naming restriction is to ensure that every model component can be unambiguously referenced by its unique name within a model. For details on how to reference model component names in expressions, see Guidelines for Referencing Names in Expressions.
To disambiguate duplicate names from your model, use the updateDuplicateNames function at the command line. The function takes in a SimBiology model as an input and updates the component names as necessary. You can also specify optional outputs, such as a logical flag to check whether any update occurred, a list of model changes, and a copy of the original model before any updates were made.
The updateDuplicateNames function disambiguates the duplicate names by adding a suffix "_N", where N is the first positive integer that results in a unique name. If there is an existing suffix, N will be incremented from that suffix. For example, if there are two model components named x_3, the function updates one of the names to x_4. If the existing suffix has leading zeros, the function omits the zeros in the new name. For instance, if x_003 is a duplicate name, it gets renamed to x_4. However, the function assumes that names with leading zeros and without leading zeros are different. For instance, x_005 and x_5 are considered to be different names.

R2022a: Having duplicate model component names will not be allowed in a future release

SimBiology will not allow you to have duplicate names for model components within a model.