eqtk.eqcheck

eqtk.eqcheck(c, c0=None, N=None, K=None, logK=None, A=None, G=None, names=None, units='unspecified', G_units=None, solvent_density=None, T=293.15, c_as_log='unspecified', normal_A=True, eq_rtol=1e-05, eq_atol=1e-08, tol=1e-07, tol_zero=1e-12, return_detailed=False)

Check the satisfaction of equilibrium expressions and conservation laws.

Parameters

  • c (array or DataFrame, shape c0.shape) – Equilibrium concentrations of all species. c[i, j] is the equilibrium concentration of species j for initial concentrations given by c0[i, :] in units given by units.

  • c0 (array_like, dict, Series, or DataFrame, shape (n_points, n_compounds) or (n_compounds, ), or None) – Each row contains the total “initial” concentration of all possible chemical species in solution. The equilibrium concentration of all species is computed for each row in c0. c0[i, j] is the initial concentration of compound j for calculation i. c0 may also be passed as a Pandas Series where the indices contain the name of the chemical species and each value is the “initial concentration.” c0 may also be passed as a Pandas DataFrame where each row contains the total “initial” concentration of all possible compounds in solution and the column names are the names of the chemical species. If c0 is passed as a dict, the dict must be convertible to a Pandas Series or DataFrame as pd.Series(c0) or pd.DataFrame(c0). If c is inputted as a Series or DataFrame and has initial concentrations, c0 may be None.

  • N (array_like or DataFrame, default None) – Stoichiometic matrix. N[r, j] = the stoichiometric coefficient of compound j in chemical reaction r. All rows of N must be linearly independent. If entered as a DataFrame, the name of chemical species j is N.columns[j]. Optionally, column ‘equilibrium constant’ contains the equilibrium constants for each reaction in units commensurate with those of c0. If N is given, A and G cannot be given.

  • K (array_like, shape (n_reactions,), default None) – K[r] is the equilibrium constant for chemical reaction r in units commensurate with those of c0. If N is given as a DataFrame with an ‘equilibrium constant’ column, K should not be supplied. If K`is given, `A and G cannot be given.

  • logK (array_like, shape (n_reactions,), default None) – logK[r] is the natural logarithm of the equilibrium constant for chemical reaction r. If logK is specified, the concentrations must all be dimensionless (units=None). If N is given as a DataFrame with a ‘log equilibrium constant’ column, logK should not be supplied. If K is given, A, G, and K cannot be given.

  • A (array_like or DataFrame, n_compounds columns) – Conservation matrix. If c is the output, then A @ c0 = A @ c. All entries must be nonnegative and the rows of A must be linearly independent. If entered as a DataFrame, the name of chemical species j is A.columns[j]. If A is given, G must be given, and N and K cannot be given.

  • G (array_like, shape (n_compounds, ), default None) – G[j] is the free energy of chemical species j in units specified by G_units. If G is given, A must be given, and N and K cannot be given.

  • names (list or tuple of str, default None, optional) – The names of the chemical species. Names are inferred if N or A is given as a DataFrame, in which case names is unnecessary.

  • units (string or None, default ‘unspecified’) – The units of the concentrations. Allowable values are {None, ‘mole fraction’, ‘molar’, ‘M’, ‘millimolar’, ‘mM’, ‘micromolar’, ‘uM’, ‘µM’, ‘nanomolar’, ‘nM’, ‘picomolar’, ‘pM’}. If ‘unspecified’, units are inferred from other inputs. If the c is a Numpy array, units are considered None if ‘unspecified’. The equilibrium constants given by K must have corresponding units.

  • G_units (string, default None) – Units in which free energy is given. If None or ‘kT’, the free energies are specified in units of of the thermal energy kT. Allowable values are {None, ‘kT’, kcal/mol’, ‘J’, ‘J/mol’, ‘kJ/mol’, ‘pN-nm’}.

  • solvent_density (float, default None) – The density of the solvent in units commensurate with the units keyword argument. Default (None) assumes the solvent is water, and its density is computed at the temperature specified by the T keyword argument.

  • T (float, default = 293.15) – Temperature, in Kelvin, of the solution. When N and K are given, T is ignored if solvent_density is given or if units is None. If A and G are given, T is ignored when units and G_units are both None.

  • c_as_log (str or bool, default 'unspecified') – If True, c is given with computed concentrations as the natural logarithm of their value, as would be returned by eqtk.solve() with the return_log=True keyword argument. If ‘unspecified’, logarithmic c is inferred from the input. If c is a Numpy array and c_as_log is ‘unspecified’, the inputted c is assumed to be concentrations and not their natural logarithms.

  • normal_A (bool, default True) – If True, perform a transformation on A such that its rows are normal vectors when checking conservation laws. If False, use inputted A directly as the conservation matrix. This is ignored if A is not specified; the resulting conservation matrix in that case has orthonormal rows by construction. This parameter should be chosen to match what was used in the calculation being checked because the convergence criteria change slightly depending on the particular values in A.

  • eq_atol (float, default 1e-8) – Absolute tolerance parameter to check closeness of equilibrium as used in numpy.isclose().

  • eq_rtol (float, default 1e-5) – Relative tolerance parameter to check closeness of equilibrium condition as used in numpy.isclose().

  • tol (float, default 1e-7) – Tolerance for conservation law. The absolute tolerance for a given initial concentration c0 (a one-dimensional array) for the conservation conditions are tol * np.dot(A, c0) except when an entry in np.dot(A, c0) is zero. If that is the case for entry i, then the absolute tolerance is tol * np.max(A[i] * c0). If all entries in A[i] * c0 are zero, which only happens with c0 = 0, the absolute tolerance is tol_zero.

  • tol_zero (float, default 1e-12) – Absolute tolerance for convergence when the initial concentrations are all zero. This cannot really be set a priori; it depends on the scale of the dimensionless concentrations. By default, assume an absolute tolerance consistent with tol and millimolar mole fractions.

  • return_detailed (bool, default False) – If True, return detailed quantitative checks (see return values below). If False, only a boolean is returned, True if all equilibrium and conservation conditions are met and False otherwise.

Returns

  • output (bool) – True is all equilibrium and conservation conditions are met. False otherwise.

  • equilibrium_check (Numpy array, shape (n_points, n_reactions) or (n_reactions, )) – equilibrium_check[i, r] is the ratio of the left and right hand sides of the mass action expression for equilibrium for calculation i. This is defined as (prod_j c[j]**N[r][j]) / K[r]. If N or K is not given, they are calculated from A and G. This is only returned if return_detailed is True.

  • equilibrium_satisfied (Numpy array, shape (n_points, n_reactions) or (n_reactions, )) – equilibrium_satisfied[i, r] is True if the equilibrium condition for reaction r in calculation i is satisfied. is met and False otherwise. This is only returned if return_detailed is True.

  • cons_check (Numpy array, shape (n_points, n_compounds - n_reactions), or (n_compounds - n_reactions,)) – cons_check[i, k] is the difference between the calculated value of a conserved quantity and the actual value for calculation i. It is defined as cons_check = np.dot(A, c) - np.dot(A, c0). If A is not given, A is calculated as the null space of N. This is only returned if return_detailed is True.

  • cons_satisfied (Numpy array, shape (n_points, n_reactions) or (n_reactions, )) – cons_satisfied[i, k] is True if the conservation condition k for calculation i is met and False otherwise. This is only returned if return_detailed is True.