SimBiology.EquivalenceSet

R2026b

Set of equivalent quantities across submodels

Since R2026b

expand all in page

    Description

    A SimBiology.EquivalenceSet object declares that two or more quantities in different submodels represent the same biological entity. For example, if a liver submodel and a gut submodel each have a Venous Blood compartment that represents the same physical blood pool, an equivalence set groups them so that the software treats them as a single shared state. One member of the set is designated the resolved quantity—during simulation, the software uses the resolved quantity in place of all other members. For details, see Model Hierarchy and Equivalence Sets.

    Creation

    Create a SimBiology.EquivalenceSet object in one of these ways:

    • Use the addequivalence function on a model to group quantities from different submodels into an equivalence set.

    • Use the split function on an existing SimBiology.EquivalenceSet object to move quantities into a new equivalence set.

    Properties

    expand all

    This property is read-only.

    Model that owns the equivalence set, represented as a SimBiology.Model object. The ModelScope property determines the level in the model hierarchy at which the equivalence is resolved. For more information, see Equivalence Sets.

    This property is read-only.

    Quantities grouped in the equivalence set, represented as an array of SimBiology.Compartment, SimBiology.Species, or SimBiology.Parameter objects. Each quantity is in a different model within the ModelScope hierarchy. During simulation, the software uses ResolvedQuantity in place of all other quantities in the set.

    Quantity used in place of all other quantities in the set during simulation, specified as a SimBiology.Compartment, SimBiology.Species, or SimBiology.Parameter object. The resolved quantity must be a member of the Quantities array. During simulation, the software uses the resolved quantity in place of all other quantities in the equivalence set. Simulation results report only the resolved quantity, not the individual equivalent quantities. Each equivalence set in a chain of supersets and subsets has its own distinct resolved quantity.

    This property is read-only.

    Parent equivalence set, represented as a SimBiology.EquivalenceSet object. If this equivalence set is a top-level set, SuperSet is empty. A nonempty SuperSet indicates that this equivalence set is nested within a higher-level equivalence set in the model hierarchy.

    This property is read-only.

    Child equivalence sets, represented as an array of SimBiology.EquivalenceSet objects. Each subset corresponds to a submodel-level equivalence set that is grouped under this equivalence set. If this equivalence set has no children, SubSets is empty.

    This property is read-only.

    Top-level equivalence set in the hierarchy, represented as an SimBiology.EquivalenceSet object. For a top-level set, this property refers to itself. For a subset, this property provides a reference to the root of the equivalence hierarchy, which is the set scoped to the top-level model.

    Object Functions

    addAdd quantities to equivalence set
    deleteDelete SimBiology object
    mergeMerge two or more equivalence sets into one
    removeRemove quantities from equivalence set
    splitSplit quantities into a new equivalence set

    Examples

    collapse all

    Open Live Script

    Build a PBPK model from a generic organ template using submodels, then use sbioselect and addequivalence to connect shared compartments and species across organ submodels.

    Create a generic organ model with venous blood, arterial blood, and organ compartments, each containing a Drug species.

    genericOrganModel = sbiomodel("Generic Organ");
venousComp = addcompartment(genericOrganModel,"Venous Blood",3000,Units="milliliter");
arterialComp = addcompartment(genericOrganModel,"Arterial Blood",1500,Units="milliliter");
organComp = addcompartment(genericOrganModel,"Organ",0.5e-10,Units="milliliter");
addspecies(venousComp,"Drug",0,Units="milligram/milliliter");
addspecies(arterialComp,"Drug",0,Units="milligram/milliliter");
addspecies(organComp,"Drug",0,Units="milligram/milliliter");
addparameter(genericOrganModel,"DrugBloodPlasmaRatio",0.8,Units="dimensionless");
addparameter(genericOrganModel,"DrugFractionUnbound",0.6,Units="dimensionless");

    Build the PBPK model hierarchy by copying the generic organ model into multiple organ submodels using copyobj.

    pbpkModel = sbiomodel("PBPK");
for organ = ["Gut","Liver","Lung","Heart","Brain","Kidney"]
    organModel = copyobj(genericOrganModel,pbpkModel);
    organModel.Name = organ + " submodel";
    organCompartment = sbioselect(organModel.Compartments,Name="Organ");
    rename(organCompartment,organ);
end

    Inspect the submodel hierarchy.

    pbpkModel.Models
    ans = 
   SimBiology Model Array

   Index:    Name:              ParentModel:
   1         Gut submodel       PBPK        
   2         Liver submodel     PBPK        
   3         Lung submodel      PBPK        
   4         Heart submodel     PBPK        
   5         Brain submodel     PBPK        
   6         Kidney submodel    PBPK

    Use sbioselect to find all Venous Blood compartments across submodels.

    venousComps = sbioselect(pbpkModel,"Type","compartment","Name","Venous Blood")
    venousComps = 
   SimBiology Compartment Array

   Index:    Name:           Value:    Units:        ParentModel:   
   1         Venous Blood    3000      milliliter    Gut submodel   
   2         Venous Blood    3000      milliliter    Liver submodel 
   3         Venous Blood    3000      milliliter    Lung submodel  
   4         Venous Blood    3000      milliliter    Heart submodel 
   5         Venous Blood    3000      milliliter    Brain submodel 
   6         Venous Blood    3000      milliliter    Kidney submodel

    Use addequivalence to create an equivalence set grouping all Venous Blood compartments. During simulation, these compartments share a single resolved value.

    eqVenous = addequivalence(pbpkModel,venousComps)
    eqVenous = 
  EquivalenceSet with properties:

          ModelScope: [1×1 SimBiology.Model]
          Quantities: [6×1 SimBiology.Compartment]
    ResolvedQuantity: [1×1 SimBiology.Compartment]
            SuperSet: []
             SubSets: [6×1 SimBiology.EquivalenceSet]
         TopLevelSet: [1×1 SimBiology.EquivalenceSet]

    Check which compartment is the resolved quantity. This is the quantity used in simulation and analysis workflows.

    eqVenous.ResolvedQuantity
    ans = 
   SimBiology Compartment - Venous Blood 

   Compartment Components:
     Value:             3000
     Units:             milliliter
     Compartments:      0
     Constant:          true
     Owner:             
     Species:           1
     ParentModel:       Gut submodel

    Similarly, create an equivalence set for Arterial Blood compartments.

    arterialComps = sbioselect(pbpkModel,"Type","compartment","Name","Arterial Blood");
eqArterial = addequivalence(pbpkModel,arterialComps);

    Making compartments equivalent does not automatically make their species equivalent. Create equivalence sets for the Drug species in the Venous Blood and Arterial Blood compartments.

    venousDrugSpecies = sbioselect(venousComps,"Type","species","Name","Drug");
eqVenousDrug = addequivalence(pbpkModel,venousDrugSpecies);

arterialDrugSpecies = sbioselect(arterialComps,"Type","species","Name","Drug");
eqArterialDrug = addequivalence(pbpkModel,arterialDrugSpecies);

    Verify the equivalence sets on the model.

    pbpkModel.EquivalenceSets
    ans = 
  4×1 EquivalenceSet array with properties:

    ModelScope
    Quantities
    ResolvedQuantity
    SuperSet
    SubSets
    TopLevelSet
    Open Live Script

    Reorganize equivalence sets after creation using split, merge, and remove.

    Open this example and load the prebuilt PBPK model. For details on model building, see the first example Create Equivalence Sets for Shared Compartments and Species Across Submodels.

    load pbpkmodel.mat pbpkModel
eqVenous = pbpkModel.EquivalenceSets(1);
eqVenous.Quantities
    ans = 
   SimBiology Compartment Array

   Index:    Name:           Value:    Units:        ParentModel:   
   1         Venous Blood    3000      milliliter    Gut submodel   
   2         Venous Blood    3000      milliliter    Liver submodel 
   3         Venous Blood    3000      milliliter    Lung submodel  
   4         Venous Blood    3000      milliliter    Heart submodel 
   5         Venous Blood    3000      milliliter    Brain submodel 
   6         Venous Blood    3000      milliliter    Kidney submodel

    Split the Brain and Kidney Venous Blood compartments into a separate equivalence set. Use sbioselect with the FullyQualifiedName property to select quantities directly without first selecting the submodel. The split function moves the specified quantities out of the original set and returns a new equivalence set.

    brainVenous = sbioselect(pbpkModel,"FullyQualifiedName","PBPK.[Brain submodel].[Venous Blood]");
kidneyVenous = sbioselect(pbpkModel,"FullyQualifiedName","PBPK.[Kidney submodel].[Venous Blood]");
eqBrainKidney = split(eqVenous,[brainVenous,kidneyVenous])
    eqBrainKidney = 
  EquivalenceSet with properties:

          ModelScope: [1×1 SimBiology.Model]
          Quantities: [2×1 SimBiology.Compartment]
    ResolvedQuantity: [1×1 SimBiology.Compartment]
            SuperSet: []
             SubSets: [2×1 SimBiology.EquivalenceSet]
         TopLevelSet: [1×1 SimBiology.EquivalenceSet]

    Verify the original equivalence set now contains only the remaining four compartments.

    eqVenous.Quantities
    ans = 
   SimBiology Compartment Array

   Index:    Name:           Value:    Units:        ParentModel:  
   1         Venous Blood    3000      milliliter    Gut submodel  
   2         Venous Blood    3000      milliliter    Liver submodel
   3         Venous Blood    3000      milliliter    Lung submodel 
   4         Venous Blood    3000      milliliter    Heart submodel

    Merge the two equivalence sets back together. The merge function moves all quantities from the second set into the first set.

    merge(eqVenous,eqBrainKidney);
eqVenous.Quantities
    ans = 
   SimBiology Compartment Array

   Index:    Name:           Value:    Units:        ParentModel:   
   1         Venous Blood    3000      milliliter    Gut submodel   
   2         Venous Blood    3000      milliliter    Liver submodel 
   3         Venous Blood    3000      milliliter    Lung submodel  
   4         Venous Blood    3000      milliliter    Heart submodel 
   5         Venous Blood    3000      milliliter    Brain submodel 
   6         Venous Blood    3000      milliliter    Kidney submodel

    Remove a single compartment from the equivalence set using remove.

    remove(eqVenous,kidneyVenous);
eqVenous.Quantities
    ans = 
   SimBiology Compartment Array

   Index:    Name:           Value:    Units:        ParentModel:  
   1         Venous Blood    3000      milliliter    Gut submodel  
   2         Venous Blood    3000      milliliter    Liver submodel
   3         Venous Blood    3000      milliliter    Lung submodel 
   4         Venous Blood    3000      milliliter    Heart submodel
   5         Venous Blood    3000      milliliter    Brain submodel

    Change which quantity provides the resolved value during simulation by setting ResolvedQuantity.

    liverVenous = sbioselect(pbpkModel,"FullyQualifiedName","PBPK.[Liver submodel].[Venous Blood]");
eqVenous.ResolvedQuantity = liverVenous;
eqVenous.ResolvedQuantity
    ans = 
   SimBiology Compartment - Venous Blood 

   Compartment Components:
     Value:             3000
     Units:             milliliter
     Compartments:      0
     Constant:          true
     Owner:             
     Species:           1
     ParentModel:       Liver submodel

    Version History

    Introduced in R2026b

    See Also

    |

    Topics