search

sys-bio / roadrunner

libRoadRunner: A high-performance SBML simulator
http://libroadrunner.org/
Other
39 stars 25 forks source link

Documentation of r.reset(SelectionRecord.*) missing & probable bug in reset concentrations #250

Closed matthiaskoenig closed 3 years ago

matthiaskoenig commented 8 years ago

I would love to have a documentation of the possible arguments of

r.reset(SelectionRecord.*)

and their respective effects. I.e. what is exactly reset and what not. Like for instance 

SelectionRecord.ALL
SelectionRecord.INITIAL_GLOBAL_PARAMETER
...

What other options are available?

So far I found out some of the behaviour (code below), but it would be nice to have full documentation of the options. This is very important if one wants to change parameters on which other values depend via rules and assignments. It gets even more complex if volumes are involved like the following example shows.

I would for instance expect, that r.reset(SelectionRecord.INITIAL_FLOATING_CONCENTRATION) resets the concentrations, even if the volumes changed ! But this is not the case! It has exactly the same effect like r.reset(SelectionRecord.INITIAL_FLOATING_AMOUNT) As a consequence it is not possible to restore initial concentrations after volumes changed in the model !

# load model
r = roadrunner.RoadRunner("test_3.xml")
r.reset(SelectionRecord.ALL)  # full reset (parameters and concentrations)

# make a concentration backup (needed later)
concentration_backup = dict()
for sid in r.model.getFloatingSpeciesIds():
    concentration_backup[sid] = r["[{}]".format(sid)]

# initial state
print(r.x_cell, r.Vol_c, r['[c__gal]'])

# change parameter 
# -> the depending inital assignments are not updated (makes sense, are only initial)
r.x_cell = 10E-6  # [m]
print(r.x_cell, r.Vol_c, r['[c__gal]'])

# force an update via recalculating depending assignments
# -> Volume is updated, but also the concentrations due to changes in volume !
from roadrunner import SelectionRecord
r.reset(SelectionRecord.INITIAL_GLOBAL_PARAMETER)
print(r.x_cell, r.Vol_c, r['[c__gal]'])

# a reset of the initial concentrations does not bring the concentrations back
r.reset() 
print(r.x_cell, r.Vol_c, r['[c__gal]'])
r.reset(SelectionRecord.INITIAL_FLOATING_CONCENTRATION) 
print(r.x_cell, r.Vol_c, r['[c__gal]'])

# restore concentrations
# the backup of the concentrations is needed because the above things do not work
# -> now same initial concentrations under changed parameters
for key, value in concentration_backup.iteritems():
    r.model['[{}]'.format(key)] = value
print(r.x_cell, r.Vol_c, r['[c__gal]'])

# To reset all use
r.reset(SelectionRecord.ALL)  # full reset (parameters and concentrations)
print(r.x_cell, r.Vol_c, r['[c__gal]'])

(2.5e-05, 1.5625e-14, 0.00012) (1e-05, 1.5625e-14, 0.00012) (1e-05, 1.0000000000000003e-15, 0.0018749999999999995) (1e-05, 1.0000000000000003e-15, 0.0018749999999999995) (1e-05, 1.0000000000000003e-15, 0.0018749999999999995) (1e-05, 1.0000000000000003e-15, 0.00012) (2.5e-05, 1.5625e-14, 0.00012)

test_3.xml

<?xml version="1.0" encoding="UTF-8"?>
<!-- Created by multiscale-modelcreator version 0.1.0 on 2016-01-11 15:13 with libSBML version 5.12.1. -->
<sbml xmlns="http://www.sbml.org/sbml/level3/version1/core" xmlns:fbc="http://www.sbml.org/sbml/level3/version1/fbc/version2" level="3" version="1" fbc:required="false">
  <model metaid="meta_8bb240b7a6de47339464002234653772" id="test_3" name="test_3" substanceUnits="mole" timeUnits="s" volumeUnits="m3" areaUnits="m2" lengthUnits="m" extentUnits="mole" fbc:strict="false">
    <notes>
      <body xmlns="http://www.w3.org/1999/xhtml">
        <h1>Koenig Test Model</h1>
        <h2>Description</h2>
        <h2>Terms of use</h2>
        <div class="dc:rightsHolder">Copyright © 2015 Matthias Koenig.</div>
        <div class="dc:license">
          <p>Redistribution and use of any part of this model, with or without modification, are permitted provided that the following conditions are met:
        <ol>
            <li>Redistributions of this SBML file must retain the above copyright notice, this list of conditions and the following disclaimer.</li>
            <li>Redistributions in a different form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided
          with the distribution.</li>
          </ol>
        This model is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
        </p>
      </div>
    </body>
  </notes>
  <annotation>
    <rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:dcterms="http://purl.org/dc/terms/" xmlns:vCard="http://www.w3.org/2001/vcard-rdf/3.0#" xmlns:bqbiol="http://biomodels.net/biology-qualifiers/" xmlns:bqmodel="http://biomodels.net/model-qualifiers/">
      <rdf:Description rdf:about="#meta_8bb240b7a6de47339464002234653772">
        <dc:creator>
          <rdf:Bag>
            <rdf:li rdf:parseType="Resource">
              <vCard:N rdf:parseType="Resource">
                <vCard:Family>Koenig</vCard:Family>
                <vCard:Given>Matthias</vCard:Given>
              </vCard:N>
              <vCard:EMAIL>konigmatt@googlemail.com</vCard:EMAIL>
              <vCard:ORG rdf:parseType="Resource">
                <vCard:Orgname>Charite Berlin</vCard:Orgname>
              </vCard:ORG>
            </rdf:li>
          </rdf:Bag>
        </dc:creator>
        <dcterms:created rdf:parseType="Resource">
          <dcterms:W3CDTF>2016-01-11T15:13:07Z</dcterms:W3CDTF>
        </dcterms:created>
        <dcterms:modified rdf:parseType="Resource">
          <dcterms:W3CDTF>2016-01-11T15:13:07Z</dcterms:W3CDTF>
        </dcterms:modified>
      </rdf:Description>
    </rdf:RDF>
  </annotation>
  <listOfUnitDefinitions>
    <unitDefinition id="Pa_s_per_m2">
      <listOfUnits>
        <unit kind="pascal" exponent="1" scale="0" multiplier="1"/>
        <unit kind="second" exponent="1" scale="0" multiplier="1"/>
        <unit kind="metre" exponent="-2" scale="0" multiplier="1"/>
      </listOfUnits>
    </unitDefinition>
    <unitDefinition id="Pa_s_per_m3">
      <listOfUnits>
        <unit kind="pascal" exponent="1" scale="0" multiplier="1"/>
        <unit kind="second" exponent="1" scale="0" multiplier="1"/>
        <unit kind="metre" exponent="-3" scale="0" multiplier="1"/>
      </listOfUnits>
    </unitDefinition>
    <unitDefinition id="Pa_s_per_m4">
      <listOfUnits>
        <unit kind="pascal" exponent="1" scale="0" multiplier="1"/>
        <unit kind="second" exponent="1" scale="0" multiplier="1"/>
        <unit kind="metre" exponent="-4" scale="0" multiplier="1"/>
      </listOfUnits>
    </unitDefinition>
    <unitDefinition id="Pa">
      <listOfUnits>
        <unit kind="pascal" exponent="1" scale="0" multiplier="1"/>
      </listOfUnits>
    </unitDefinition>
    <unitDefinition id="m_per_s">
      <listOfUnits>
        <unit kind="metre" exponent="1" scale="0" multiplier="1"/>
        <unit kind="second" exponent="-1" scale="0" multiplier="1"/>
      </listOfUnits>
    </unitDefinition>
    <unitDefinition id="per_m3">
      <listOfUnits>
        <unit kind="metre" exponent="-3" scale="0" multiplier="1"/>
      </listOfUnits>
    </unitDefinition>
    <unitDefinition id="per_m2">
      <listOfUnits>
        <unit kind="metre" exponent="-2" scale="0" multiplier="1"/>
      </listOfUnits>
    </unitDefinition>
    <unitDefinition id="mole_per_s">
      <listOfUnits>
        <unit kind="mole" exponent="1" scale="0" multiplier="1"/>
        <unit kind="second" exponent="-1" scale="0" multiplier="1"/>
      </listOfUnits>
    </unitDefinition>
    <unitDefinition id="m2_per_s">
      <listOfUnits>
        <unit kind="metre" exponent="2" scale="0" multiplier="1"/>
        <unit kind="second" exponent="-1" scale="0" multiplier="1"/>
      </listOfUnits>
    </unitDefinition>
    <unitDefinition id="mole_per_s_per_mM2">
      <listOfUnits>
        <unit kind="mole" exponent="-1" scale="0" multiplier="1"/>
        <unit kind="metre" exponent="6" scale="0" multiplier="1"/>
        <unit kind="second" exponent="-1" scale="0" multiplier="1"/>
      </listOfUnits>
    </unitDefinition>
    <unitDefinition id="m3_per_skg">
      <listOfUnits>
        <unit kind="metre" exponent="3" scale="0" multiplier="1"/>
        <unit kind="kilogram" exponent="-1" scale="0" multiplier="1"/>
        <unit kind="second" exponent="-1" scale="0" multiplier="1"/>
      </listOfUnits>
    </unitDefinition>
    <unitDefinition id="m2">
      <listOfUnits>
        <unit kind="metre" exponent="2" scale="0" multiplier="1"/>
      </listOfUnits>
    </unitDefinition>
    <unitDefinition id="mM_s">
      <listOfUnits>
        <unit kind="mole" exponent="1" scale="0" multiplier="1"/>
        <unit kind="second" exponent="1" scale="0" multiplier="1"/>
        <unit kind="metre" exponent="-3" scale="0" multiplier="1"/>
      </listOfUnits>
    </unitDefinition>
    <unitDefinition id="per_s">
      <listOfUnits>
        <unit kind="second" exponent="-1" scale="0" multiplier="1"/>
      </listOfUnits>
    </unitDefinition>
    <unitDefinition id="m3">
      <listOfUnits>
        <unit kind="metre" exponent="3" scale="0" multiplier="1"/>
      </listOfUnits>
    </unitDefinition>
    <unitDefinition id="mM">
      <listOfUnits>
        <unit kind="mole" exponent="1" scale="0" multiplier="1"/>
        <unit kind="metre" exponent="-3" scale="0" multiplier="1"/>
      </listOfUnits>
    </unitDefinition>
    <unitDefinition id="mole_per_s_per_mM">
      <listOfUnits>
        <unit kind="metre" exponent="3" scale="0" multiplier="1"/>
        <unit kind="second" exponent="-1" scale="0" multiplier="1"/>
      </listOfUnits>
    </unitDefinition>
    <unitDefinition id="kg_per_m3">
      <listOfUnits>
        <unit kind="kilogram" exponent="1" scale="0" multiplier="1"/>
        <unit kind="metre" exponent="-3" scale="0" multiplier="1"/>
      </listOfUnits>
    </unitDefinition>
    <unitDefinition id="per_mM">
      <listOfUnits>
        <unit kind="metre" exponent="3" scale="0" multiplier="1"/>
        <unit kind="mole" exponent="-1" scale="0" multiplier="1"/>
      </listOfUnits>
    </unitDefinition>
    <unitDefinition id="m6_per_Pa2_s2">
      <listOfUnits>
        <unit kind="pascal" exponent="-2" scale="0" multiplier="1"/>
        <unit kind="second" exponent="-2" scale="0" multiplier="1"/>
        <unit kind="metre" exponent="6" scale="0" multiplier="1"/>
      </listOfUnits>
    </unitDefinition>
    <unitDefinition id="kg">
      <listOfUnits>
        <unit kind="kilogram" exponent="1" scale="0" multiplier="1"/>
      </listOfUnits>
    </unitDefinition>
    <unitDefinition id="m">
      <listOfUnits>
        <unit kind="metre" exponent="1" scale="0" multiplier="1"/>
      </listOfUnits>
    </unitDefinition>
    <unitDefinition id="s">
      <listOfUnits>
        <unit kind="second" exponent="1" scale="0" multiplier="1"/>
      </listOfUnits>
    </unitDefinition>
    <unitDefinition id="Pa_s">
      <listOfUnits>
        <unit kind="pascal" exponent="1" scale="0" multiplier="1"/>
        <unit kind="second" exponent="1" scale="0" multiplier="1"/>
      </listOfUnits>
    </unitDefinition>
    <unitDefinition id="m3_per_s">
      <listOfUnits>
        <unit kind="metre" exponent="3" scale="0" multiplier="1"/>
        <unit kind="second" exponent="-1" scale="0" multiplier="1"/>
      </listOfUnits>
    </unitDefinition>
  </listOfUnitDefinitions>
  <listOfCompartments>
    <compartment id="e" name="external" spatialDimensions="3" units="m3" constant="true"/>
    <compartment id="c" name="cytosol" spatialDimensions="3" units="m3" constant="false"/>
    <compartment id="m" name="membrane" spatialDimensions="2" units="m2" constant="true"/>
  </listOfCompartments>
  <listOfSpecies>
    <species id="c__gal" name="D-galactose" compartment="c" initialConcentration="0.00012" substanceUnits="mole" hasOnlySubstanceUnits="false" boundaryCondition="false" constant="false"/>
    <species id="e__gal" name="D-galactose" compartment="e" initialConcentration="3" substanceUnits="mole" hasOnlySubstanceUnits="false" boundaryCondition="true" constant="false"/>
  </listOfSpecies>
  <listOfParameters>
    <parameter id="x_cell" name="cell diameter" value="2.5e-05" units="m" constant="true"/>
    <parameter id="Vol_e" name="external volume" value="0.0001" units="m3" constant="true"/>
    <parameter id="A_m" name="membrane area" value="1" units="m2" constant="true"/>
    <parameter id="Vol_c" name="cell volume" units="m3" constant="true"/>
    <parameter id="GLUT2_Vmax" value="1e-13" units="mole_per_s" constant="true"/>
    <parameter id="GLUT2_k_gal" value="1" units="mM" constant="true"/>
  </listOfParameters>
  <listOfInitialAssignments>
    <initialAssignment symbol="Vol_c">
      <math xmlns="http://www.w3.org/1998/Math/MathML">
        <apply>
          <times/>
          <ci> x_cell </ci>
          <ci> x_cell </ci>
          <ci> x_cell </ci>
        </apply>
      </math>
    </initialAssignment>
    <initialAssignment symbol="e">
      <math xmlns="http://www.w3.org/1998/Math/MathML">
        <ci> Vol_e </ci>
      </math>
    </initialAssignment>
    <initialAssignment symbol="m">
      <math xmlns="http://www.w3.org/1998/Math/MathML">
        <ci> A_m </ci>
      </math>
    </initialAssignment>
  </listOfInitialAssignments>
  <listOfRules>
    <assignmentRule variable="c">
      <math xmlns="http://www.w3.org/1998/Math/MathML">
        <ci> Vol_c </ci>
      </math>
    </assignmentRule>
  </listOfRules>
  <listOfReactions>
    <reaction id="e__GLUT2_GAL" name="galactose transport [e__]" reversible="true" fast="false" compartment="m">
      <listOfReactants>
        <speciesReference species="e__gal" stoichiometry="1" constant="true"/>
      </listOfReactants>
      <listOfProducts>
        <speciesReference species="c__gal" stoichiometry="1" constant="true"/>
      </listOfProducts>
      <kineticLaw>
        <math xmlns="http://www.w3.org/1998/Math/MathML" xmlns:sbml="http://www.sbml.org/sbml/level3/version1/core">
          <apply>
            <divide/>
            <apply>
              <times/>
              <ci> GLUT2_Vmax </ci>
              <apply>
                <minus/>
                <cn sbml:units="dimensionless" type="integer"> 1 </cn>
                <apply>
                  <divide/>
                  <ci> c__gal </ci>
                  <ci> e__gal </ci>
                </apply>
              </apply>
            </apply>
            <apply>
              <plus/>
              <cn sbml:units="dimensionless" type="integer"> 1 </cn>
              <apply>
                <divide/>
                <ci> c__gal </ci>
                <ci> GLUT2_k_gal </ci>
              </apply>
              <apply>
                <divide/>
                <ci> e__gal </ci>
                <ci> GLUT2_k_gal </ci>
              </apply>
            </apply>
          </apply>
        </math>
      </kineticLaw>
    </reaction>
  </listOfReactions>
</model>
</sbml>
hsauro commented 8 years ago

I thought this had been documented, but clearly not!

Herbert

On Monday, January 11, 2016, Matthias König notifications@github.com wrote:

I would love to have a documentation of the possible arguments of

r.reset(SelectionRecord.*)

and their respective effects. I.e. what is exactly reset and what not. Like for instance

SelectionRecord.ALL SelectionRecord.INITIAL_GLOBAL_PARAMETER ...

What other options are available?

So far I found out some of the behaviour (code below), but it would be nice to have full documentation of the options. This is very important if one wants to change parameters on which other values depend via rules and assignments. It gets even more complex if volumes are involved like the following example shows.

I would for instance expect, that r.reset(SelectionRecord.INITIAL_FLOATING_CONCENTRATION) resets the concentrations, even if the volumes changed ! But this is not the case! It has exactly the same effect like r.reset(SelectionRecord.INITIAL_FLOATING_AMOUNT) As a consequence it is not possible to restore initial concentrations after volumes changed in the model !

load model

r = roadrunner.RoadRunner("test_3.xml") r.reset(SelectionRecord.ALL) # full reset (parameters and concentrations)

make a concentration backup (needed later)

concentration_backup = dict() for sid in r.model.getFloatingSpeciesIds(): concentration_backup[sid] = r["[{}]".format(sid)]

initial state

print(r.x_cell, r.Vol_c, r['[c__gal]'])

change parameter

-> the depending inital assignments are not updated (makes sense, are only initial)

r.x_cell = 10E-6 # [m] print(r.x_cell, r.Vol_c, r['[c__gal]'])

force an update via recalculating depending assignments

-> Volume is updated, but also the concentrations due to changes in volume !

from roadrunner import SelectionRecord r.reset(SelectionRecord.INITIAL_GLOBAL_PARAMETER) print(r.x_cell, r.Vol_c, r['[c__gal]'])

a reset of the initial concentrations does not bring the concentrations back

r.reset() print(r.x_cell, r.Vol_c, r['[cgal]']) r.reset(SelectionRecord.INITIAL_FLOATING_CONCENTRATION) print(r.x_cell, r.Vol_c, r['[cgal]'])

restore concentrations

the backup of the concentrations is needed because the above things do not work

-> now same initial concentrations under changed parameters

for key, value in concentration_backup.iteritems(): r.model['[{}]'.format(key)] = value print(r.x_cell, r.Vol_c, r['[c__gal]'])

To reset all use

r.reset(SelectionRecord.ALL) # full reset (parameters and concentrations) print(r.x_cell, r.Vol_c, r['[c__gal]'])

(2.5e-05, 1.5625e-14, 0.00012) (1e-05, 1.5625e-14, 0.00012) (1e-05, 1.0000000000000003e-15, 0.0018749999999999995) (1e-05, 1.0000000000000003e-15, 0.0018749999999999995) (1e-05, 1.0000000000000003e-15, 0.0018749999999999995) (1e-05, 1.0000000000000003e-15, 0.00012) (2.5e-05, 1.5625e-14, 0.00012)

test_3.xml

<?xml version="1.0" encoding="UTF-8"?>

Koenig Test Model

Description

Terms of use

Copyright © 2015 Matthias Koenig.

Redistribution and use of any part of this model, with or without modification, are permitted provided that the following conditions are met:

  1. Redistributions of this SBML file must retain the above copyright notice, this list of conditions and the following disclaimer.
  2. Redistributions in a different form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
This model is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

dc:creator rdf:Bag vCard:FamilyKoenig/vCard:Family vCard:GivenMatthias/vCard:Given /vCard:N vCard:EMAILkonigmatt@googlemail.com /vCard:EMAIL vCard:OrgnameCharite Berlin/vCard:Orgname /vCard:ORG /rdf:li /rdf:Bag /dc:creator dcterms:W3CDTF2016-01-11T15:13:07Z/dcterms:W3CDTF /dcterms:created dcterms:W3CDTF2016-01-11T15:13:07Z/dcterms:W3CDTF /dcterms:modified /rdf:Description /rdf:RDF x_cell x_cell x_cell Vol_e A_m Vol_c GLUT2_Vmax 1 c__gal e__gal 1 c__gal GLUT2_k_gal e__gal GLUT2_k_gal

— Reply to this email directly or view it on GitHub https://github.com/sys-bio/roadrunner/issues/250.

matthiaskoenig commented 8 years ago

I think there is also a bug, not only documentation problem.

r.reset(SelectionRecord.INITIAL_FLOATING_CONCENTRATION) should reset the initial concentrations even if volumes changed in the model !

Currently everything is handled via amounts, so SelectionRecord.INITIAL_FLOATING_CONCENTRATION is performing a reset of the initial amounts, i.e. is doing a SelectionRecord.INITIAL_FLOATING_AMOUNT which is not the same if the volumes where changed !

kirichoi commented 8 years ago

Hi,

An updated doc has been pushed with added details on SelectionRecord class. For the r.reset() bug, a slight hands up for debugging. Try:

import roadrunner
from roadrunner import SelectionRecord
# load model
r = roadrunner.RoadRunner("test_3.xml")
r.reset(SelectionRecord.ALL)  # full reset (parameters and concentrations)

# make a concentration backup (needed later)
concentration_backup = dict()
for sid in r.model.getFloatingSpeciesIds():
    concentration_backup[sid] = r["[{}]".format(sid)]

# initial state
print(r.x_cell, r.Vol_c, r['init([c__gal])'])

# change parameter 
# -> the depending inital assignments are not updated (makes sense, are only initial)
r.x_cell = 10E-6  # [m]
print(r.x_cell, r.Vol_c, r['init([c__gal])'])

# force an update via recalculating depending assignments
# -> Volume is updated, but also the concentrations due to changes in volume !
from roadrunner import SelectionRecord
r.reset(SelectionRecord.INITIAL_GLOBAL_PARAMETER)
print(r.x_cell, r.Vol_c, r['init([c__gal])'])

# a reset of the initial concentrations does not bring the concentrations back
r.reset() 
print(r.x_cell, r.Vol_c, r['init([c__gal])'])
r.reset(SelectionRecord.INITIAL_FLOATING_CONCENTRATION) 
print(r.x_cell, r.Vol_c, r['init([c__gal])'])

# restore concentrations
# the backup of the concentrations is needed because the above things do not work
# -> now same initial concentrations under changed parameters
for key, value in concentration_backup.iteritems():
    r.model['[{}]'.format(key)] = value
print(r.x_cell, r.Vol_c, r['init([c__gal])'])

# To reset all use
r.reset(SelectionRecord.ALL)  # full reset (parameters and concentrations)
print(r.x_cell, r.Vol_c, r['init([c__gal])'])

where I used init([c__gal]) instead of [c__gal] which is the correct notation for the initial value. This will print

(2.5e-05, 1.5625e-14, 0.00012)
(1e-05, 1.5625e-14, 0.0018749999999999995)
(1e-05, 1.0000000000000003e-15, 0.0018749999999999995)
(1e-05, 1.0000000000000003e-15, 0.0018749999999999995)
(1e-05, 1.0000000000000003e-15, 0.0018749999999999995)
(1e-05, 1.0000000000000003e-15, 0.0018749999999999995)
(2.5e-05, 1.5625e-14, 0.00012)

On the second line, you see that the initial concentration of c__gal is changed despite of volume staying constant. Seems like the initial concentration is automatically initialized given the change in x_cell based on set initial assignment rule assuming constant amount of c_gal in the system. In this case reset will not point to the original value, and I think reset function itself is working fine.

@matthiaskoenig: for the time being, try plugging r['init([c__gal])'] = 0.00012 after changing the value of x_cell if you want the retain the initial concentration until we resolve this issue.

matthiaskoenig commented 8 years ago

Hi Kiri et al, thanks for the update.

Unfortunately, not all options are exported from rrSelectionRecord.h in the documentation at http://sys-bio.github.io/roadrunner/python_docs/api_reference.html#selectionrecord If options are listed directly in lines after each other in rrSelectionRecord.h without empty line in between, only the first option is exported in the documentation.

For instance the following

        /**
         * current amounts
         */
        FLOATING_AMOUNT =                   FLOATING | AMOUNT | INDEPENDENT | DEPENDENT | CURRENT,
        INDEPENDENT_FLOATING_AMOUNT =       FLOATING | AMOUNT | INDEPENDENT | CURRENT,
        DEPENDENT_FLOATING_AMOUNT =         FLOATING | AMOUNT | DEPENDENT   | CURRENT,
        BOUNDARY_AMOUNT =                   BOUNDARY | AMOUNT | INDEPENDENT | DEPENDENT | CURRENT,

results in the documentation

SelectionRecord.FLOATING_AMOUNT
    current amounts.

Options like SelectionRecord.INITIAL_GLOBAL_PARAMETER are missing.

(There is a typo in CONSREVED_MOIETY = (0x1 << 20), => CONSERVED_MOIETY)

My problem was not so much the naming of the options, which I can lookup in rrSelectionRecord.h, but which are their effects (just listing them now in the python docs is not helping so much). Namely:

As far as I understood is SelectionRecord calculating one bit for any given symbol in the LLVM model (either 0 or 1), which decides if this symbol is selected or not. There are some basic selections like 

CONCENTRATION =                     (0x1 << 1),
        AMOUNT =                            (0x1 << 2),

which are decided somehow (probably while parsing the SBML). In addition more complex selectionRecords exist which are a combination of the basic building blocks via bitwise operations. For instance 

INITIAL_GLOBAL_PARAMETER =          INITIAL | _GLOBAL_PARAMETER | INDEPENDENT | DEPENDENT,

which I understand as: Something is selected via INITIAL_GLOBAL_PARAMETER if it is either INITIAL, _GLOBAL_PARAMETER, INDEPENDENT or DEPENDENT. Without a clear description of the basic building blocks which are later used in the bitwise calculation of more complex selection I have no idea what these selections will do.

Also: Isn't something either INDEPENDENT or DEPENDENT? Or is there some third option? Because the INDEPENDENT | DEPENDENT looks somehow strange.

It would help a lot to document this class much better:

/**
 * a way to find sbml model elements using the RoadRunner syntax.
 */
class RR_DECLSPEC SelectionRecord
....

For instance, how can I get the Selection from the SelectionRecord? Where are the (0x1 << 1), things coming from? What do all the basic building blocks for selections mean? What is the effect of sending a SelectionRecord.* to reset? (I understand that all symbols which are selected are reset, but nothing more. If the selection is a calculation, it is recalculated).

This is quit important, because it allows fine-grained manipulation of the underlying LLVM model. Sometimes I want to use the LLVM model mainly as a 'calculator' not as an 'integrator'. For instance to ask question like what would happen to the numerical values of the model variable if I change a parameter. I would than set the parameter and recalculate all the depending variables.

0u812 commented 8 years ago

The bug part is fixed. Here is some test code:

import roadrunner
from roadrunner import Config, SelectionRecord, Logger

#Logger.setLevel(Logger.LOG_DEBUG)

import tellurium as te

m = te.loada('''
var species x in c, y in c, z in c
compartment c = 1.0

x -> y ; k*x
y -> z; 1

x = 10
y = 0
z = 0

k = 0.2

''')
#at time>5: c=2.0

r = m.simulate(0,10,100,['time','[x]','[y]','[z]'])
print(r)
m.plot()

print('[x] at final timepoint: {}'.format(m.model.getValue('[x]')))
m.model.setValue('c', 2.)
print('[x] after vol change: {}'.format(m.model.getValue('[x]')))
print('c after vol change: {}'.format(m.model.getValue('c')))
m.reset(SelectionRecord.INITIAL_FLOATING_CONCENTRATION)

print('[x] after floating conc reset: {}'.format(m.model.getValue('[x]')))
print('x after floating conc reset: {}'.format(m.model.getValue('x')))

Produces the following output:

[x] at final timepoint: 1.35331946673
[x] after vol change: 0.676659733363
c after vol change: 2.0
[x] after floating conc reset: 10.0
x after floating conc reset: 20.0
matthiaskoenig commented 8 years ago

Thanks a lot. Works.

So do I understand correctly the meaning of the following:

# reset initial floating concentration for species 
# (if calculated via InitialAssignment or AssignmentRule the 
# respective rule is reavaluated with the current model values)
m.reset(SelectionRecord.INITIAL_FLOATING_CONCENTRATION)

# reset initial floating amounts for species 
# (if calculated via InitialAssignment or AssignmentRule the 
# respective rule is reavaluated with the current model values)
m.reset(SelectionRecord.INITIAL_FLOATING_AMOUNT)

# reset initial compartment sizes 
(if calculated via InitialAssignment or AssignmentRule the 
# respective rule is reavaluated with the current model values)
m.reset(SelectionRecord.INITIAL_COMPARTMENT)

# reset parameter values 
(if calculated via InitialAssignment or AssignmentRule the 
# respective rule is reavaluated with the current model values)
m.reset(SelectionRecord.INITIAL_GLOBAL_PARAMTERS)

What is the difference between INITIAL_AMOUNT and INITIAL_FLOATING_AMOUNT, and INITIAL_CONCENTRATION and INITIAL_FLOATING_CONCENTRATION, respectively? How do I get the list of selections from the SelectionRecord.* ?

kirichoi commented 7 years ago

Commit https://github.com/sys-bio/roadrunner/commit/e669357c7fc3765d9923843999f3d04e1bb46936 fixes typo. Changed CONSREVED_MOIETY to CONSERVED_MOIETY.

kirichoi commented 7 years ago

Commit https://github.com/sys-bio/roadrunner/commit/1554ef3626cccf290c51455e6b24d6ec5f908132 adds some documentations for all selection types. I would like to add more and also validate each and every selection types. Also there are few that does not seem to be used at all.

luciansmith commented 3 years ago

With the overhaul of the reset functions, the 'reset' function now has the following documentation. Closing this issue, though I'm happy to take more suggestions here!

By default, reset all floating species concentrations and all variables changed by rate rules to their CURRENT init(X) values.

It is possible to change the behavior of this function by providing a list of "or'ed" SelectionRecords. For example, to reset only time and floating species, use:

    reset(SelectionRecord.TIME | SelectionRecord.FLOATING)

The full list of recognized selection records are as follows. These selection records are used by default:

    SelectionRecord.TIME:  Resets the time to zero.
    SelectionRecord.FLOATING:  Resets all floating species.
    SelectionRecord.RATE: Resets any variable or parameter that is changed by a rate rule (whether species, compartment, or parameter)

The following selection records are added to the above when calling 'resetAll', and may be used separately or in concert with the above:

    SelectionRecord.BOUNDARY:  Resets the boundary species.
    SelectionRecord.COMPARTMENT:  Resets the compartments.
    SelectionRecord.GLOBAL_PARAMETER:  Resets the parameter objects.

All of the above will use the current 'init(x)' values, and will re-calculate any initial assignments in the model based on the reset (or not reset) values they reference. If one wishes to reset the model to its original state as defined in the SBML (resetting the 'init(x)' values as well), use:

    SelectionRecord.ALL:  Resets everything to as it was in the current SBML model.