*This guide is for versions 1.0 Beta 38+*

Static methods about reactions kinetics

name | arguments | returns |
---|---|---|

solve_exactly | rxn :Reaction, A0 :float, B0 :float, t_arr | (np.array, np.array) |

Return the exact solution of the given reaction, PROVIDED that it is a 1st Order Reaction of the type A <=> B. Use the given initial conditions, and return the solutions sampled at the specified times. For details, see https://life123.science/reactions :param rxn: Object of type "Reaction", containing data for the reaction of interest :param A0: Initial concentration of the reactant A :param B0: Initial concentration of the product B :param t_arr: A Numpy array with the desired times at which the solutions are desired :return: A pair of Numpy arrays with, respectively, the concentrations of A and B |

name | arguments | returns |
---|---|---|

_exact_solution | kF, kR, A0, B0, t_arr :np.ndarray | (np.ndarray, np.ndarray) |

Return the exact solution of the 1st Order Reaction A <=> B, with the specified parameters, sampled at the given times. For details, see https://life123.science/reactions :param kF: Forward reaction rate constant :param kR: Reverse reaction rate constant :param A0: Initial concentration of the reactant A :param B0: Initial concentration of the product B :param t_arr: A Numpy array with the desired times at which the solutions are desired :return: A pair of Numpy arrays with, respectively, the concentrations of A and B at the times given by the argument t_arr |

name | arguments | returns |
---|---|---|

approx_solution_combination_rxn | kF, kR, A0, B0, C0, t_arr :np.ndarray | (np.ndarray, np.ndarray, np.ndarray) |

Return the approximate analytical solution, by way of exponentials, of the reversible 2nd Order Reaction A + B <=> C, with the specified parameters, sampled at the given times. :param kF: Forward reaction rate constant (cannot be zero) :param kR: Reverse reaction rate constant :param A0: Initial concentration of the 1st reactant A :param B0: Initial concentration of the 2nd reactant B :param C0: Initial concentration of the product C :param t_arr: A Numpy array with the desired times at which the solutions are desired :return: A pair of Numpy arrays with, respectively, the concentrations of A and B at the times given by the argument t_arr |

name | arguments | returns |
---|---|---|

exact_solution_combination_rxn | kF, kR, A0, B0, C0, t_arr | (np.ndarray, np.ndarray, np.ndarray) |

Return the exact solution of the reversible 2nd Order Reaction A + B <=> C, with the specified parameters, sampled at the given times. :param kF: Forward reaction rate constant :param kR: Reverse reaction rate constant :param A0: Initial concentration of the 1st reactant A :param B0: Initial concentration of the 2nd reactant B :param C0: Initial concentration of the product C :param t_arr: A Numpy array with the desired times at which the solutions are desired :return: A triplet of Numpy arrays with, respectively, the concentrations of A, B and C at the times given by the argument t_arr |

Methods for managing variable time steps during reactions

name | arguments | returns |
---|---|---|

__init__ | self | |

name | arguments | returns |
---|---|---|

set_thresholds | norm :str, low=None, high=None, abort=None | None |

Create or update a rule based on the given norm (simulation parameters that affect the adaptive variable step sizes.) If no rule with the specified norm was previously set, it will be added. All None values in the arguments are ignored. :param norm: The name of the "norm" (criterion) being used - either a previously-set one or not :param low: The value below which the norm is considered to be good (and the variable steps are being made larger); if None, it doesn't get changed :param high: The value above which the norm is considered to be excessive (and the variable steps get reduced); if None, it doesn't get changed :param abort: The value above which the norm is considered to be dangerously large (and the last variable step gets discarded and back-tracked with a smaller size) ; if None, it doesn't get changed :return: None |

name | arguments | returns |
---|---|---|

delete_thresholds | norm :str, low=False, high=False, abort=False | None |

Delete one or more of the threshold values associated to a rule using the specified norm. If none of the threshold values remains in place, the whole rule gets eliminated altogether. Attempting to delete something not present, will raise an Exception :param norm: The name of the "norm" (criterion) being used - for a previously-set rule :param low: If True, this threshold value will get deleted :param high: If True, this threshold value will get deleted :param abort: If True, this threshold value will get deleted :return: None |

name | arguments | returns |
---|---|---|

display_value_against_thresholds | all_norms | |

name | arguments | returns |
---|---|---|

display_value_against_thresholds_single_rule | rule :dict, value | str |

Examine how the specified value fits relatively to the 'low', 'high', and 'abort' stored in the given rule :param rule: A dict that must contain the key 'norm', and may contain the keys: 'low', 'high', and 'abort' (referring to 3 increasingly-high thresholds) :param value: Either None, or a number to compare to the thresholds :return: A string that visually highlights the relative position of the value relatively to the given thresholds |

name | arguments | returns |
---|---|---|

set_step_factors | upshift=None, downshift=None, abort=None, error=None | None |

Over-ride current values for simulation parameters that affect the adaptive variable step sizes. Values not explicitly passed will remain the same. :param upshift: Fraction by which to increase the variable step size :param downshift: Fraction by which to decrease the variable step size :param abort: Fraction by which to decrease the variable step size in cases of step re-do :param error: Fraction by which to decrease the variable step size in cases of error :return: None |

name | arguments | returns |
---|---|---|

show_adaptive_parameters | self | None |

Print out the current values for the adaptive time-step parameters :return: None |

name | arguments | returns |
---|---|---|

use_adaptive_preset | preset :str | None |

Lets the user choose a preset to use from now on, unless later explicitly changed, for use in ALL reaction simulations involving adaptive time steps. The preset will affect the degree to which the simulation will be "risk-taker" vs. "risk-averse" about taking larger steps. Note: for more control, use set_thresholds() and set_step_factors() For example, using the "mid" preset is the same as issuing: 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, error=0.25) :param preset: String with one of the available preset names; allowed values are (in generally-increasing speed): 'heavy_brakes', 'slower', 'slow', 'mid', 'fast' :return: None |

name | arguments | returns |
---|---|---|

adjust_timestep | n_chems: int, indexes_of_active_chemicals :[int], delta_conc: np.array, baseline_conc=None, prev_conc=None, | dict |

Computes some measures of the change of concentrations, from the last step, in the context of the baseline initial concentrations of that same step, and the concentrations in the step before that. Based on the magnitude of the measures, propose a course of action about what to do for the next step. :param n_chems: The total number of registered chemicals - exclusive of water and of macro-molecules :param indexes_of_active_chemicals: The ordered list (numerically sorted) of the INDEX numbers of all the chemicals involved in ANY of the registered reactions, but NOT counting chemicals that always appear in a catalytic role in all the reactions they participate in :param delta_conc: A numpy array of changes in concentrations for the chemicals of interest, across a simulation time step (typically, the current step a run in progress) :param baseline_conc: A numpy array of baseline concentration values for those same chemicals, prior to the above change, at the start of a simulation time step :param prev_conc: A numpy array of concentration values for those same chemicals, in the step prior to the current one (i.e. an "archive" value) :return: A dict: "action" - String with the name of the computed recommended action: either "low", "stay", "high" or "abort" "step_factor" - A factor by which to multiply the time step at the next iteration round; if no change is deemed necessary, 1 "norms" - A dict of all the computed norm name/values (any of the norms, except norm_A, may be missing) "applicable_norms" - The name of the norm that triggered the decision; if all norms were involved, it will be "ALL" |

name | arguments | returns |
---|---|---|

relative_significance | value :float, baseline :float | str |

Estimate, in a loose categorical fashion, the magnitude of the quantity "value" in proportion to the quantity "baseline". Both are assumed non-negative (NOT checked.) Return one of: "S" ("Small" ; up to 1/2 the size) "C" ("Comparable" ; from 1/2 to double) "L" ("Large" ; over double the size) This method is meant for large-scale computations, and on purpose avoids doing divisions. NOT IN CURRENT ACTIVE USAGE (in former use for the discontinued substep implementation) :param value: :param baseline: :return: An assessment of relative significance, as one of "S" ("Small"), "C" ("Comparable"), "L" ("Large") |

name | arguments | returns |
---|---|---|

reset_norm_usage_stats | self | |

Reset the count of the number of times that each norm got involved in step-size decision :return: None |

name | arguments | returns |
---|---|---|

increase_norm_count | norm_name :str | None |

:param norm_name: :return: None |

name | arguments | returns |
---|---|---|

norm_A | delta_conc :np.array | float |

Return a measure of system change, based on the average concentration changes of ALL the specified chemicals across a time step, adjusted for the number of chemicals. A square-of-sums computation (the square of an L2 norm) is used. :param delta_conc: A Numpy array with the concentration changes of the chemicals of interest across a time step :return: A measure of change in the concentrations across the simulation step |

name | arguments | returns |
---|---|---|

norm_B | baseline_conc: np.array, delta_conc: np.array | float |

Return a measure of system change, based on the max absolute relative concentration change of all the chemicals across a time step (based on an L infinity norm - but disregarding any baseline concentration that is very close to zero) :param baseline_conc: A Numpy array with the concentration of the chemicals of interest at the start of a simulation time step :param delta_conc: A Numpy array with the concentration changes of the chemicals of interest across a time step :return: A measure of change in the concentrations across the simulation step |

name | arguments | returns |
---|---|---|

norm_C | prev_conc: np.array, baseline_conc: np.array, delta_conc: np.array | float |

Return a measure of system short-period oscillation; larger values might be heralding onset of simulation instability :param prev_conc: A numpy array with the concentration of the chemicals of interest, in the step prior to the current one (i.e. an "archive" value) :param baseline_conc: A Numpy array with the concentration of the chemicals of interest at the start of a simulation time step :param delta_conc: A Numpy array with the concentration changes of the chemicals of interest across a time step :return: |

name | arguments | returns |
---|---|---|

norm_D | prev_conc: np.array, baseline_conc: np.array, delta_conc: np.array | float |

Return a measure of curvature in the concentration vs. time curves; larger values might be heralding onset of simulation instability :param prev_conc: A numpy array with the concentration of the chemicals of interest, in the step prior to the current one (i.e. an "archive" value) :param baseline_conc: A Numpy array with the concentration of the chemicals of interest at the start of a simulation time step :param delta_conc: A Numpy array with the concentration changes of the chemicals of interest across a time step :return: |