| 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
at the times given by the argument t_arr
|
| name | arguments | returns |
|---|
| exact_solution_unimolecular_reversible | kF, kR, A0, B0, t_arr :np.ndarray | (np.ndarray, np.ndarray) |
Return the exact solution of the reversible 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 to be determined
: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_unimolecular_irreversible | kF, A0, B0, t_arr :np.ndarray | (np.ndarray, np.ndarray) |
Return the exact solution of the irreversible 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 (the reverse one is taken to be zero)
: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 to be determined
: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_synthesis_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_synthesis_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
|
| name | arguments | returns |
|---|
| estimate_rate_constants_simple | t :np.ndarray,
A_conc :np.ndarray, B_conc :np.ndarray,
reactant_name="Reactant", product_name="Product" | |
Estimate the rate constants for a 1-st order reaction of the type A <-> B,
given time evolution of [A] and [B] on a grid of time points (don't need to be equally spaced)
IMPORTANT : This is for reactions with a 1:1 stoichiometry between the given reactant and product
:param t: A numpy array of time grid points where the other functions are specified
:param A_conc: A numpy array of the concentrations of the reactant, at the times in the array t
:param B_conc: A numpy array of the concentrations of the product, at the times in the array t
:param reactant_name: [OPTIONAL] The name of the reactant (for display purposes)
:param product_name: [OPTIONAL] The name of the product (for display purposes)
:return: A plotly "Figure" object. The estimated rate constants are printed out
|
| name | arguments | returns |
|---|
| estimate_rate_constants_synthesis | t :np.ndarray,
A_conc :np.ndarray, B_conc :np.ndarray, C_conc :np.ndarray,
reactants :[str, str], product :str | |
Estimate the rate constants for a 1-st order association (synthesis) reaction of the type A + B <-> C,
given time evolution of [A], [B] and [C] on a grid of time points (don't need to be equally spaced)
IMPORTANT : This is for reactions with a 1:1:1 stoichiometry
:param t: A numpy array of time grid points where the other functions are specified
:param A_conc: A numpy array of the concentrations of the reactant, at the times in the array t
:param B_conc:
:param C_conc:
:param reactants: [OPTIONAL] A list with the names of the 2 reactants, in order (for display purposes)
:param product: [OPTIONAL] The name of the product (for display purposes)
:return: A plotly "Figure" object. The estimated rate constants are printed out
|
| name | arguments | returns |
|---|
| compute_reaction_rate | rxn, conc_array :np.ndarray, name_mapping :dict | float |
For the SINGLE given reaction, and the specified concentrations of chemicals,
compute its initial reaction's "rate" (aka "velocity"),
i.e. its "forward rate" minus its "reverse rate",
at the start of the time step.
This function is to be used for elementary, or non-elementary, reactions that follow the familiar "Rate Laws",
with forward and reverse rate constants stored in the passed "Reaction" object,
and with reaction orders, for the various Reactants and Products, also stored in that "Reaction" object.
For background info: https://life123.science/reactions
:param rxn: An object of type "Reaction", with the details of the reaction
:param conc_array: Numpy array of concentrations of ALL chemical, in their index order
:param name_mapping:A dict with all the mappings of the chemical names to the registered index
:return: The differences between the reaction's forward and reverse rates
|
| 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 | None |
:param all_norms:
:return: None
|
| 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:
ReactionKinetics.set_thresholds(norm="norm_A", low=0.5, high=0.8, abort=1.44)
ReactionKinetics.set_thresholds(norm="norm_B", low=0.08, high=0.5, abort=1.5)
ReactionKinetics.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:
|