Main Content

Evaluation of Model Component Names in Expressions

SimBiology model components include quantities and expressions. You can refer to model quantities (compartments, species, and parameters) and observables by their names in an expression, such as a reaction or an assignment equation. Follow these guidelines when you name model components or referencing their names in expressions. When evaluating a name that matches different quantities, SimBiology resolves it by following precedence rules.

Guidelines for Naming Model Components

  • Model, parameter, and observable names cannot contain brackets [ ] and cannot be empty, the word time, or all whitespace.

  • Compartment, species, and observable names cannot contain the characters ->, <->, [ or ] and cannot be empty, the word null, or the word time. However, a name can contain the words null and time within the name, such as nullDrug.

  • Reaction, event, and rule names cannot contain brackets [ ] and cannot be the word time.

  • You cannot set a reaction name to an empty character vector ('') or empty string ( "").

Note

SimBiology removes any leading or trailing white spaces from model component names.

Warning

Starting in R2022b:

  • 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.

Tip

To get a list of model components with the same name, do one of the following:

  • At the command line, enter sbioselect(model,Name="dupName"), where model is a SimBiology model and dupName is the duplicate name.

  • In SimBiology Model Builder, you can filter the components by entering the duplicate name in the Browser pane.

Guidelines for Referencing Names in Expressions

  • If the quantity name is not a valid MATLAB® variable name, you must enclose the name in brackets when referring to it in an expression. For example, if the name of a species is DNA polymerase+, write [DNA polymerase+].

  • If you have multiple species with the same name in different compartments, you must qualify the name by referring to the name of the compartment that contains the species. For example, the qualified name nucleus.[DNA polymerase+] refers to the DNA polymerase+ species that resides in the nucleus compartment.

Precedence Rules for Evaluating Quantity Names

If a name referenced in an expression matches multiple quantities or observable objects, SimBiology evaluates the expression using precedence rules. The rules depend on whether the name is referenced in a reaction or other expressions that are not reactions.

For Reactions

When a reaction refers to a name that matches different quantities, SimBiology evaluates the name as the first quantity with a matching name in this order: species, parameter scoped to the reaction, compartment, or parameter scoped to the model.

For Other Expressions

There are different types of expressions that are not reactions, namely rules, events, and observables. Rules include initial and repeated assignment equations, algebraic equations, and differential rate equations. An event contains expressions that represent an event trigger and one or more event functions to model discrete transitions in the values of quantities or expressions in the model. An observable object is a mathematical expression that lets you perform post-simulation calculations.

When a nonreaction expression refers to a name that matches different quantities, SimBiology evaluates the name as the first quantity with a matching name in this order: species, compartment, or parameter scoped to the model. An active observable expression can reference another active observable object by its name as long as there are no circular dependencies (or algebraic loops).

See Also

Related Topics