Process¶

class qsdsan.Process(ID, reaction, ref_component, rate_equation=None, components=None, conserved_for=('COD', 'N', 'P', 'charge'), parameters=())¶

Create a Process object which defines a stoichiometric process and its kinetics. A Process object is capable of reacting the component flow rates of a WasteStream object.

Parameters:

ID (str) – A unique identification.
reaction (dict, str, or numpy.ndarray) – A dictionary of stoichiometric coefficients with component IDs as keys, or a numeric array of stoichiometric coefficients, or a string of a stoichiometric equation written as: i1 R1 + … + in Rn -> j1 P1 + … + jm Pm. Stoichiometric coefficients can be symbolic or numerical. Unknown stoichiometric coefficients to solve for should be expressed as “?”.
ref_component (str) – ID of the reference Component object of the process rate.
rate_equation (str, optional) – The kinetic rate equation of the process. The default is None.
components=None (class:CompiledComponents, optional) – Components corresponding to each entry in the stoichiometry array, defaults to all components set in the system (i.e., through set_thermo()).
conserved_for (tuple[str], optional) – Materials subject to conservation rules, must be an ‘i_’ attribute of the components. The default is (“COD”, “N”, “P”, “charge”).
parameters (Iterable[str], optional) – Symbolic parameters in stoichiometry coefficients (both constant and dynamic) and/or rate equation. The default is None.

Examples

To create a Process object, basic information including stoichiometry, and reference component must be specified. Unknown stoichiometric coefficients can be solved automatically based on conservation of materials.

>>> import qsdsan as qs
>>> cmps = qs.processes.create_asm1_cmps()
>>> pc1 = qs.Process(ID='aerobic_hetero_growth',
...                  reaction='[1/Y_H]S_S + [1-1/Y_H]S_O + [?]S_NH + [?]S_ALK -> X_BH',
...                  ref_component='X_BH',
...                  rate_equation='mu_H*S_S/(K_S+S_S)*S_O/(K_O_H+S_O)*S_NH/(K_NH+S_NH)*X_BH',
...                  conserved_for=('COD', 'N', 'charge'),
...                  parameters=('Y_H', 'mu_H', 'K_S', 'K_O_H', 'K_NH'))
>>> pc1.show()
Process: aerobic_hetero_growth
[stoichiometry]      S_S: -1/Y_H
                     X_BH: 1.00
                     S_O: -1.0 + 1/Y_H
                     S_NH: -0.0860
                     S_ALK: -0.0737
[reference]          X_BH
[rate equation]      S_NH*S_O*S_S*X_BH*mu_H/((K_N...
[parameters]         Y_H: Y_H
                     mu_H: mu_H
                     K_S: K_S
                     K_O_H: K_O_H
                     K_NH: K_NH
[dynamic parameters]

If all stoichiometric coefficients and relevant parameters are specified, one can also check if materials are conserved. No returns when all materials are conserved.

>>> pc2 = qs.Process(ID='hydrolysis',
...                  reaction={'S_S':1, 'X_S':-1},
...                  ref_component='S_S',
...                  rate_equation='k_h*X_S/(K_X*X_BH+X_S)*(S_O/(K_O_H+S_O)+eta_h*K_O_H/(K_O_H+S_O)*S_NO/(K_NO+S_NO))*X_BH',
...                  conserved_for=(),
...                  parameters=('k_h', 'K_X', 'K_O_H', 'eta_h', 'K_NO'))
>>> pc2.show()
Process: hydrolysis
[stoichiometry]      S_S: 1
                     X_S: -1
[reference]          S_S
[rate equation]      X_BH*X_S*k_h*(K_O_H*S_NO*eta...
[parameters]         k_h: k_h
                     K_X: K_X
                     K_O_H: K_O_H
                     eta_h: eta_h
                     K_NO: K_NO
[dynamic parameters]

>>> pc2.conserved_for = ('COD', 'N')
>>> pc2.check_conservation()

Raise warning when materials are not strictly conserved based on the given stoichiometric coefficients with defined parameters. An error will be raised instead for stoichiometric coefficients that are purely numerical.

>>> pc3 = qs.Process(ID='decay_hetero',
...                  reaction='X_BH -> [f_P]X_P + [1-f_P]X_S + [0.05-0.05*f_P]X_ND',
...                  ref_component='X_BH',
...                  rate_equation='b_H*X_BH',
...                  conserved_for=('COD', 'N'),
...                  parameters=('f_P', 'b_H'))
>>> pc3.check_conservation() 
UserWarning: The following materials aren't strictly conserved by the stoichiometric coefficients.
A positive value means the material is created, a negative value means the material is destroyed:
  N: 0.01*f_P - 0.036

Parameter values can be set. Changes will be reflected in the stoichiometry and/or the rate equation:

>>> pc2.set_parameters(eta_h = 0.8)
>>> pc2.parameters
{'k_h': k_h, 'K_X': K_X, 'K_O_H': K_O_H, 'eta_h': 0.8, 'K_NO': K_NO}

>>> str(pc2.rate_equation)
'X_BH*X_S*k_h*(0.8*K_O_H*S_NO/((K_NO + S_NO)*(K_O_H + S_O)) + S_O/(K_O_H + S_O))/(K_X*X_BH + X_S)'

An reversed process can be easily created:

>>> pc2_reversed = pc2.copy('hydrolysis_reversed')
>>> pc2_reversed.reverse()
>>> pc2_reversed.show()
Process: hydrolysis_reversed
[stoichiometry]      S_S: -1
                     X_S: 1
[reference]          S_S
[rate equation]      -X_BH*X_S*k_h*(K_O_H*S_NO*et...
[parameters]         k_h: k_h
                     K_X: K_X
                     K_O_H: K_O_H
                     eta_h: 0.8
                     K_NO: K_NO
[dynamic parameters]

Processes¶

class qsdsan.Processes(processes)¶

Create a Processes object that contains Process objects as attributes.

Parameters:: processes (Iterable[Process])

Examples

>>> import qsdsan as qs
>>> cmps = qs.processes.create_asm1_cmps()
>>> pc1 = qs.Process(ID='aerobic_hetero_growth',
...                  reaction='[1/Y_H]S_S + [1-1/Y_H]S_O + [?]S_NH + [?]S_ALK -> X_BH',
...                  ref_component='X_BH',
...                  rate_equation='mu_H*S_S/(K_S+S_S)*S_O/(K_O_H+S_O)*S_NH/(K_NH+S_NH)*X_BH',
...                  conserved_for=('COD', 'N', 'charge'),
...                  parameters=('Y_H', 'mu_H', 'K_S', 'K_O_H', 'K_NH'))
>>> pc2 = qs.Process(ID='hydrolysis',
...                  reaction={'S_S':1, 'X_S':-1},
...                  ref_component='S_S',
...                  rate_equation='k_h*X_S/(K_X*X_BH+X_S)*(S_O/(K_O_H+S_O)+eta_h*K_O_H/(K_O_H+S_O)*S_NO/(K_NO+S_NO))*X_BH',
...                  conserved_for=(),
...                  parameters=('k_h', 'K_X', 'K_O_H', 'eta_h', 'K_NO'))
>>> pcs = qs.Processes([pc1, pc2])
>>> pcs.show()
Processes([aerobic_hetero_growth, hydrolysis])

>>> pcs.hydrolysis.show()
Process: hydrolysis
[stoichiometry]      S_S: 1
                     X_S: -1
[reference]          S_S
[rate equation]      X_BH*X_S*k_h*(K_O_H*S_NO*eta...
[parameters]         k_h: k_h
                     K_X: K_X
                     K_O_H: K_O_H
                     eta_h: eta_h
                     K_NO: K_NO
[dynamic parameters]

>>> pc3 = qs.Process(ID='decay_hetero',
...                  reaction='X_BH -> [f_P]X_P + [1-f_P]X_S + [?]X_ND',
...                  ref_component='X_BH',
...                  rate_equation='b_H*X_BH',
...                  conserved_for=('COD', 'N'),
...                  parameters=('f_P', 'b_H'))
>>> pcs.append(pc3)
>>> pcs.compile()
>>> pcs.show()
CompiledProcesses([aerobic_hetero_growth, hydrolysis, decay_hetero])

Once the processes are compiled, corresponding attributes become accessible:

>>> pcs.parameters
{'Y_H': Y_H,
  'mu_H': mu_H,
  'K_S': K_S,
  'K_O_H': K_O_H,
  'K_NH': K_NH,
  'k_h': k_h,
  'K_X': K_X,
  'eta_h': eta_h,
  'K_NO': K_NO,
  'f_P': f_P,
  'b_H': b_H}

>>> pcs.production_rates.rate_of_production.loc['X_S']
-1.0*X_BH*X_S*k_h*(K_O_H*S_NO*eta_h/((K_NO + S_NO)*(K_O_H + S_O)) + S_O/(K_O_H + S_O))/(K_X*X_BH + X_S) + X_BH*b_H*(1 - f_P)

append(process)¶: Append a Process.

compile(skip_checks=False, to_class=None)¶: Cast as a CompiledProcesses object unless otherwise specified.

copy()¶: Return a copy.

extend(processes)¶: Extend with more Process objects.

insert(index, process)¶: Insert a Process object at a given index.

classmethod load_from_file(path='', components=None, conserved_for=('COD', 'N', 'P', 'charge'), parameters=(), use_default_data=False, store_data=False, compile=True, **compile_kwargs)¶

Create CompiledProcesses object from a table of process IDs, stoichiometric coefficients, and rate equations stored in a .tsv, .csv, or Excel file.

Parameters:

path (str, optional) – File path.
components (CompiledComponents, optional) – Components corresponding to the columns in the stoichiometry matrix, to all components set in the system (i.e., through set_thermo()).
conserved_for (tuple[str], optional) – Materials subject to conservation rules, must have corresponding ‘i_’ attributes for the components. Applied to all processes. The default is (‘COD’, ‘N’, ‘P’, ‘charge’).
parameters (Iterable[str], optional) – Symbolic parameters in stoichiometry coefficients and/or rate equation.
use_default_data (bool, optional) – Whether to use default data. The default is False.
store_data (bool, optional) – Whether to store the file as default data. The default is False.
compile (bool, optional) – Whether to compile processes. The default is True.
note:: (..) –
[1] First column of the table should be process IDs, followed by stoichiometric coefficient matrix with corresponding component IDs as column names, and rate equations as the last column.

[2] Entries of stoichiometric coefficients can be symbolic or numerical. Blank cells are considered zero.

[3] Unknown stoichiometric coefficients to solve for using conservation rules should be uniformly written as ‘?’.

[4] For each process, the first component with stoichiometric coefficient of -1 or 1 is considered the reference component. If none of the components has -1 or 1 stoichiometric coefficient, the first component with non-zero coefficient is considered the reference.

subgroup(IDs)¶

Create a new subgroup of processes.

Parameters:: IDs (Iterable[str]) – Process IDs.

CompiledProcesses¶

class qsdsan.CompiledProcesses(processes)¶

Create a CompiledProcesses object that contains Process objects as attributes.

Parameters:: processes (Iterable[Process])

append(*args, **kwargs)¶: Append a Process.

append_parameters(*new_pars)¶: Append new symbolic parameters

compile(skip_checks=False)¶: Do nothing, CompiledProcesses objects are already compiled.

copy()¶: Return a copy.

dynamic_parameter(function=None, symbol=None, params={})¶: Add a function for the evaluation of a dynamic parameter in the stoichiometry of the process. Creates a DynamicParameter object.

extend(*args, **kwargs)¶: Extend with more Process objects.

index(ID)¶: Return index of specified process.

indices(IDs)¶: Return indices of multiple processes.

property parameters¶: [dict] All symbolic stoichiometric and kinetic parameters.

params_eval(state_arr)¶: Evaluate the dynamic parameters in the stoichiometry given an array of state variables.

property production_rates¶: [pandas.DataFrame] The rates of production of the components.

production_rates_eval(state_arr)¶: Return the rates of production or consumption of the components.

property rate_equations¶: [pandas.DataFrame] Rate equations.

property rate_function¶: [MultiKinetics] The function to evaluate the kinetic rates of the processes.

set_parameters(**parameters)¶: Set values to stoichiometric and/or kinetic parameters.

stoichio_eval()¶: Return the stoichiometric coefficients.

property stoichiometry¶: [pandas.DataFrame] Stoichiometric coefficients.

subgroup(IDs)¶: Create a new subgroup of CompiledProcesses objects.

DynamicParameter¶

class qsdsan.DynamicParameter(symbol, function=None, params={})¶

Create a DynamicParameter object which defines a parameter in a Process’s stoichiometry that dynamically depends on the state variables.

Parameters:

symbol (str) – The symbol of the dynamic parameter in the stoichiometric coefficient.
function (Callable or float or int, optional) – The function that returns the value of the dynamic parameter when given the array of state variables and additional parameters as positional arguments. The default is None.
params (dict, optional) – Additional parameters input to the function for the calculation of the dynamic parameters. The default is {}.

Examples

None.

property function¶: [Callable] Function that evaluates the dynamic parameter.

property params¶: [dict] Additional parameters input to the function.

set_params(**params)¶

Set values for the parameters needed for the evaluation of the dynamic parameter.

Parameters:: **params (float or int) – Parameters and values.

property symbol¶: [sympy.Symbol] Symbol of the dynamic parameter in stoichiometric coefficients.

Kinetics¶

class qsdsan.Kinetics(process, function=None, params={})¶

Create a Kinetics object which defines a Process object’s kinetic rate. It is a subclass of DynamicParameter.

Parameters:

process (Process) – The process that features this kinetics.
function (Callable or float or int, optional) – The function that evaluates the kinetic rate of reaction when given the array of state variables and additional parameters as positional arguments. The default is None.
params (dict, optional) – Additional parameters input to the function for the calculation of the kinetic rate of reaction. The default is {}.

Examples

None.

copy(new_process=None)¶: Return a copy.

MultiKinetics¶

class qsdsan.MultiKinetics(processes, function=None, params={})¶

Create a MultiKinetics object which defines a Processes object’s kinetic rates.

Parameters:

processes (Processes) – The process that features this kinetics.
function (Callable or Iterable[float or int], optional) – The function that returns the array of kinetic rates of the processes when given the array of state variables and additional parameters as positional arguments. The default is None.
params (dict, optional) – Additional parameters input to the function for the calculation of the kinetic rates. The default is {}.

Examples

None.

property function¶: [Callable] Function that evaluates the kinetic rates.

property params¶: [dict] Additional parameters input to the function.

set_params(**params)¶

Set values for the parameters needed for the evaluation of the kinetic rates.

Parameters:: **params (float or int) – Parameters and values.