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.