Merge pull request #59 from BrainAnnex/dev

Dev Beta 29

Author: BrainAnnex

README.md

@@ -1,4 +1,4 @@
-### BETA 28.2 (v0.28.2)
+### BETA 29 (v0.29.0)
 
 
 

experiments/reactions_single_compartment/down_regulate_2.ipynb

@@ -39,7 +39,7 @@
     el: '#vue-root-1',
 
     data: {
-        graph_json: [{"id": 3, "label": "Reaction", "name": "RXN", "kF": "8", "kR": "2", "Delta_G": "-3,436.56", "K": "4"}, {"id": 2, "label": "Chemical", "name": "Y", "diff_rate": null, "stoich": 1, "rxn_order": 1}, {"id": 4, "source": 3, "target": 2, "name": "produces"}, {"id": 0, "label": "Chemical", "name": "A", "diff_rate": null, "stoich": 1, "rxn_order": 1}, {"id": 5, "source": 0, "target": 3, "name": "reacts"}, {"id": 1, "label": "Chemical", "name": "B", "diff_rate": null, "stoich": 2, "rxn_order": 1}, {"id": 6, "source": 1, "target": 3, "name": "reacts"}],
+        graph_json: [{"id": 3, "label": "Reaction", "name": "RXN", "kF": "8", "kR": "2", "delta_G": "-3,436.56", "K": "4"}, {"id": 2, "label": "Chemical", "name": "Y", "diff_rate": null, "stoich": 1, "rxn_order": 1}, {"id": 4, "source": 3, "target": 2, "name": "produces"}, {"id": 0, "label": "Chemical", "name": "A", "diff_rate": null, "stoich": 1, "rxn_order": 1}, {"id": 5, "source": 0, "target": 3, "name": "reacts"}, {"id": 1, "label": "Chemical", "name": "B", "diff_rate": null, "stoich": 2, "rxn_order": 1}, {"id": 6, "source": 1, "target": 3, "name": "reacts"}],
 color_mapping_json: {"Chemical": "neo4j_green", "Reaction": "neo4j_lightbrown"},
 component_id_json: 1
     }

experiments/reactions_single_compartment/down_regulate_2.log.htm

@@ -21,7 +21,7 @@
 #
 # See also 1D/reactions/down_regulation_1
 #
-# LAST REVISED: July 14, 2023
+# LAST REVISED: Nov. 4, 2023
 
 # %%
 import set_path      # Importing this module will add the project's home directory to sys.path
@@ -109,7 +109,7 @@
 # # 2. Now, let's suddenly increase [A]
 
 # %%
-dynamics.set_chem_conc(species_name="A", conc=40., snapshot=True)
+dynamics.set_single_conc(species_name="A", conc=40., snapshot=True)
 dynamics.describe_state()
 
 # %%
@@ -143,7 +143,7 @@
 # # 3. Let's again suddenly increase [A]
 
 # %%
-dynamics.set_chem_conc(species_name="A", conc=30., snapshot=True)
+dynamics.set_single_conc(species_name="A", conc=30., snapshot=True)
 dynamics.describe_state()
 
 # %%
@@ -178,7 +178,7 @@
 # Let's try it:
 
 # %%
-dynamics.set_chem_conc(species_name="A", conc=0., snapshot=True)   # Completely eliminate A
+dynamics.set_single_conc(species_name="A", conc=0., snapshot=True)   # Completely eliminate A
 dynamics.describe_state()
 
 # %%

experiments/reactions_single_compartment/down_regulate_2.py

@@ -14,9 +14,9 @@
 # ---
 
 # %% [markdown]
-# ## Comparing the reaction `A <-> B` with and without an enzyme
+# ## Comparing the reaction `A <-> B` , with and without an enzyme
 #
-# LAST REVISED: July 14, 2023
+# LAST REVISED: Nov. 3, 2023
 
 # %%
 import set_path      # Importing this module will add the project's home directory to sys.path
@@ -33,7 +33,8 @@
 # Initialize the system
 chem_data = ChemData(names=["A", "B"])
 
-# Reaction A <-> B , with 1st-order kinetics, and a forward rate that is slower than it would be with the enzyme of part 2
+# Reaction A <-> B , with 1st-order kinetics, favorable thermodynamics in the forward direction, 
+# and a forward rate that is much slower than it would be with the enzyme - as seen in part 2, below
 chem_data.add_reaction(reactants="A", products="B",
                        forward_rate=1., delta_G=-3989.73)
 
@@ -60,8 +61,8 @@
 dynamics.set_step_factors(upshift=1.5, downshift=0.5, abort=0.5)
 dynamics.set_error_step_factor(0.5)
 
-dynamics.single_compartment_react(initial_step=0.1, reaction_duration=3.0,
-                                  variable_steps=True, explain_variable_steps=False)
+dynamics.single_compartment_react(reaction_duration=3.0,
+                                  initial_step=0.1, variable_steps=True, explain_variable_steps=False)
 
 # %%
 #dynamics.explain_time_advance()
@@ -70,7 +71,7 @@
 dynamics.plot_curves(colors=['darkorange', 'green'], show_intervals=True, title_prefix="WITHOUT enzyme")
 
 # %% [markdown]
-# #### Note how the time steps get automatically adjusted, as needed by the amount of change - include a complete step abort/redo at time=0
+# #### Note how the time steps get automatically adjusted, as needed by the amount of change - including a complete step abort/redo at time=0
 
 # %%
 dynamics.curve_intersection("A", "B", t_start=0, t_end=1.0)
@@ -86,7 +87,7 @@
 # ### `A` + `E` <-> `B` + `E`
 
 # %% [markdown]
-# ### Note: for the sake of the demo, we'll completely ignore the concomitant reaction A <-> B
+# ### Note: for the sake of the demo, we'll completely ignore the concomitant (much slower) direct reaction A <-> B
 # This in an approximation that we'll drop in later experiments
 
 # %%
@@ -101,10 +102,10 @@
 chem_data.describe_reactions()  # Notice how the enzyme `E` is noted in the printout below
 
 # %% [markdown]
-# ### Notice how, while the ratio kF/kR is the same as it was without the enzyme (since it's dictated by the energy difference), the individual values of kF and kR are now each 10 times bigger
+# ### Notice how, while the ratio kF/kR is the same as it was without the enzyme (since it's dictated by the energy difference), the individual values of kF and kR now are each 10 times bigger than before
 
 # %% [markdown]
-# ### Set the initial concentrations of all the chemicals
+# ### Set the initial concentrations of all the chemicals (to what they originally were)
 
 # %%
 dynamics = ReactionDynamics(chem_data=chem_data)
@@ -124,8 +125,8 @@
 dynamics.set_step_factors(upshift=1.2, downshift=0.5, abort=0.4)
 dynamics.set_error_step_factor(0.25)
 
-dynamics.single_compartment_react(initial_step=0.1, reaction_duration=0.1,
-                                  variable_steps=True, explain_variable_steps=False)
+dynamics.single_compartment_react(reaction_duration=0.1,
+                                  initial_step=0.1, variable_steps=True, explain_variable_steps=False)
 
 # %% [markdown]
 # #### Note how the (proposed) initial step - kept the same as the previous run - is now _extravagantly large_, given the much-faster reaction dynamics.  However, the variable-step engine intercepts and automatically corrects the problem!

experiments/reactions_single_compartment/enzyme_1.ipynb

@@ -0,0 +1,116 @@
+# ---
+# jupyter:
+#   jupytext:
+#     formats: ipynb,py:percent
+#     text_representation:
+#       extension: .py
+#       format_name: percent
+#       format_version: '1.3'
+#       jupytext_version: 1.14.1
+#   kernelspec:
+#     display_name: Python 3 (ipykernel)
+#     language: python
+#     name: python3
+# ---
+
+# %% [markdown]
+# ## Coupled pair of reactions: `A <-> B` , and  `A` + `E` <-> `B` + `E`
+# A direct reaction and same reaction, catalyzed
+# ### Enzyme `E` initially zero, and then suddenly added mid-reaction
+#
+# LAST REVISED: Nov. 4, 2023
+
+# %%
+import set_path      # Importing this module will add the project's home directory to sys.path
+
+# %% tags=[]
+from src.modules.chemicals.chem_data import ChemData
+from src.modules.reactions.reaction_dynamics import ReactionDynamics
+
+# %%
+# Initialize the system
+chem_data = ChemData(names=["A", "B", "E"])
+
+# Reaction A <-> B , with 1st-order kinetics, favorable thermodynamics in the forward direction, 
+# and a forward rate that is much slower than it would be with the enzyme - as seen in the next reaction, below
+chem_data.add_reaction(reactants="A", products="B",
+                       forward_rate=1., delta_G=-3989.73)
+
+# Reaction A + E <-> B + E , with 1st-order kinetics, and a forward rate that is faster than it was without the enzyme
+# Thermodynamically, there's no change from the reaction without the enzyme
+chem_data.add_reaction(reactants=["A", "E"], products=["B", "E"],
+                       forward_rate=10., delta_G=-3989.73)
+
+chem_data.describe_reactions()     # Notice how the enzyme `E` is noted in the printout below
+
+# %% [markdown]
+# ### Set the initial concentrations of all the chemicals - starting with no enzyme
+
+# %%
+dynamics = ReactionDynamics(chem_data=chem_data)
+dynamics.set_conc(conc={"A": 20., "B": 0., "E": 0.},
+                  snapshot=True)      # Initially, no enzyme `E`
+dynamics.describe_state()
+
+# %% [markdown] tags=[]
+# ### Advance the reactions (for now without enzyme), but stopping well before equilibrium
+
+# %%
+dynamics.set_diagnostics()       # To save diagnostic information about the call to single_compartment_react()
+
+# All of these settings are currently close to the default values... but subject to change; set for repeatability
+dynamics.set_thresholds(norm="norm_A", low=0.5, high=0.8, abort=1.44)
+dynamics.set_thresholds(norm="norm_B", low=0.08, high=0.5, abort=1.5)
+dynamics.set_step_factors(upshift=1.2, downshift=0.5, abort=0.4)
+dynamics.set_error_step_factor(0.25)
+
+# Perform the reactions
+dynamics.single_compartment_react(reaction_duration=0.25,
+                                  initial_step=0.05, variable_steps=True, explain_variable_steps=False)
+
+# %%
+#dynamics.explain_time_advance()
+
+# %%
+dynamics.plot_curves(colors=['darkorange', 'green', 'violet'], show_intervals=True, title_prefix="WITH zero enzyme")
+
+# %% [markdown]
+# ### The reactions, lacking enzyme, are proceeding slowly towards equilibrium, like reaction that was discussed in part 1 of the experiment "enzyme_1"
+
+# %% [markdown]
+# # Now suddently add a lot of enzyme
+
+# %%
+dynamics.set_single_conc(30., species_name="E", snapshot=True)    # Plenty of enzyme `E`
+
+# %%
+dynamics.describe_state()
+
+# %% [markdown] tags=[]
+# ### Take the system to equilibrium
+
+# %%
+dynamics.single_compartment_react(reaction_duration=0.04, 
+                                  initial_step=0.005, variable_steps=True, explain_variable_steps=False)
+
+# %% [markdown]
+# #### Note how the (proposed) initial step - in spite of having been reduced from the earlier run - is now appearing _large_, given the much-faster reaction dynamics.  However, the variable-step engine intercepts and automatically corrects the problem!
+
+# %%
+#dynamics.explain_time_advance()
+
+# %%
+dynamics.plot_curves(colors=['darkorange', 'green', 'violet'], show_intervals=True, title_prefix="WITH enzyme added mid-reaction")
+
+# %% [markdown]
+# ## Notice the dramatic acceleration of the reaction as soon as the enzyme `E` is added at t = 0.275!
+# The reactions simulator automatically switches to small time steps is in order to handle the rapid amount of change
+
+# %%
+# Verify that the reaction has reached equilibrium
+dynamics.is_in_equilibrium()
+
+# %%
+dynamics.get_history()
+
+# %%

experiments/reactions_single_compartment/enzyme_1.py

@@ -16,7 +16,7 @@
 # %% [markdown]
 # ## Macromolecules : Binding Affinity and Fractional Occupancy
 #
-# LAST REVISED: July 14, 2023
+# LAST REVISED: Nov. 4, 2023
 
 # %%
 import set_path      # Importing this module will add the project's home directory to sys.path
@@ -51,7 +51,7 @@
 chem.set_binding_site_affinity("M2", site_number=2, ligand="A", Kd=0.01)
 
 # %%
-chem.show_binding_affinities()        # Review the values we have given for the binding affinities
+chem.show_binding_affinities()        # Review the values we have given for the dissociation constants
 
 # %%
 chem.get_binding_sites("M1")
@@ -135,7 +135,7 @@
 # ### Adjust the concentration of one ligand, [A], and update all the fractional occupancies accordingly
 
 # %%
-dynamics.set_chem_conc(conc=1000., species_name="A", snapshot=False)
+dynamics.set_single_conc(conc=1000., species_name="A", snapshot=False)
 
 # %%
 dynamics.update_occupancy()
@@ -171,7 +171,7 @@
 # %%
 # Set [A] to each of the above values in turn, and determine/store the applicable fractional occupancies (for the sites where A binds)
 for A_conc in log_values:
-    dynamics.set_chem_conc(conc=A_conc, species_name="A", snapshot=False)
+    dynamics.set_single_conc(conc=A_conc, species_name="A", snapshot=False)
     dynamics.update_occupancy()
     history.store(A_conc, {"M1 site 3": dynamics.get_occupancy(macromolecule="M1", site_number=3), 
                            "M1 site 15": dynamics.get_occupancy(macromolecule="M1", site_number=15),