Merge pull request #124 from QSD-Group/dev

New process models and units for WRRF plant-wide simulations

.github/workflows/build-dev.yml

@@ -0,0 +1,37 @@
+# This workflow will install Python dependencies, run tests with a variety of Python versions, and report coverage
+
+name: build-dev
+
+on:
+  push:
+    branches: [dev]
+  pull_request:
+    branches: [dev]
+
+jobs:
+  build:
+
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        # os: [ubuntu-latest, macos-latest, windows-latest] if want multiple os
+        python-version: ["3.9", "3.10"]
+
+    steps:
+    - uses: actions/checkout@v4
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v4
+      with:
+        python-version: ${{ matrix.python-version }}
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        python -m pip install pytest nbval
+        pip install --no-cache-dir git+https://github.com/BioSTEAMDevelopmentGroup/thermosteam.git@qsdsan
+        pip install --no-cache-dir git+https://github.com/BioSTEAMDevelopmentGroup/biosteam.git@qsdsan
+        pip install --no-cache-dir git+https://github.com/QSD-Group/EXPOsan.git@bsm2
+        pip install --no-cache-dir -r requirements.txt
+    - name: Test with pytest
+      run: |
+        pytest

CHANGELOG.rst

@@ -4,6 +4,32 @@ Change Log
 This document records notable changes to `QSDsan <https://github.com/QSD-Group/QSDsan>`_. We aim to follow `Semantic Versioning <https://semver.org/>`_.
 
 
+`1.4.0`_
+--------
+- A lot of the updates have been focused on the dynamic simulation, now the open-loop Benchmark Simulation Model No. 2 (`BSM2 <https://github.com/QSD-Group/EXPOsan/tree/main/exposan/bsm2>`_) configuration has been implemented with new process models and unit operation including
+
+	- :class:`qsdsan.processes.ADM1p`
+	- :class:`qsdsan.processes.ADM1_p_extension`
+	- :class:`qsdsan.processes.ModifiedADM1`
+	- :class:`qsdsan.processes.mASM2d`
+	- :class:`qsdsan.sanunits.IdealClarifier`
+	- :class:`qsdsan.sanunits.PrimaryClarifier`
+	- :class:`qsdsan.sanunits.PrimaryClarifierBSM2`
+	- :class:`qsdsan.sanunits.GasExtractionMembrane`
+	- :class:`qsdsan.sanunits.Thickener`
+	- :class:`qsdsan.sanunits.Centrifuge`
+	- :class:`qsdsan.sanunits.Incinerator`
+	- :class:`qsdsan.sanunits.BatchExperiment`
+	- :class:`qsdsan.sanunits.PFR`
+	- :class:`qsdsan.sanunits.BeltThickener`
+	- :class:`qsdsan.sanunits.SludgeCentrifuge`
+	- :class:`qsdsan.sanunits.SludgeThickener`
+
+- New publications
+
+	- Feng et al., *Environmental Science & Technology*, on the sustainability of `hydrothermal liquefaction (HTL) <https://doi.org/10.1021/acs.est.3c07394>`_ for resource recovery from a range of wet organic wastes.
+
+
 `1.3.0`_
 --------
 - Enhance and use QSDsan's capacity for dynamic simulation for emerging technologies and benchmark configurations (see EXPOsan METAB and PM2 (on the algae branch, still under development) modules).
@@ -185,6 +211,7 @@ Official release of ``QSDsan`` v1.0.0!
 .. _Trimmer et al.: https://doi.org/10.1021/acs.est.0c03296
 
 .. Commit links
+.. _1.4.0: https://github.com/QSD-Group/QSDsan/releases/tag/v1.4.0
 .. _1.3.0: https://github.com/QSD-Group/QSDsan/releases/tag/v1.3.0
 .. _1.2.0: https://github.com/QSD-Group/QSDsan/releases/tag/v1.2.0
 .. _1.1.0: https://github.com/QSD-Group/QSDsan/releases/tag/v1.1.0

docs/source/api/processes/ADM1p.rst

@@ -0,0 +1,7 @@
+Anaerobic Digestion Model No.1 with P extension (ADM1 P/Extension)
+==================================================================
+.. autoclass:: qsdsan.processes.ADM1_p_extension
+   :members:
+
+.. autoclass:: qsdsan.processes.ADM1p
+:members:

docs/source/api/processes/ASM2d.rst

@@ -1,4 +1,7 @@
 Activated Sludge Model No.2d (ASM2d)
 ====================================
 .. autoclass:: qsdsan.processes.ASM2d
+   :members:
+
+.. autoclass:: qsdsan.processes.mASM2d
    :members:

docs/source/api/processes/_index.rst

@@ -11,12 +11,18 @@ List of Biological Kinetic Models
 | ADM1     | `adm`_           | `Batstone`_ et al., 2002    |
 |          |                  | `Rosen and Jeppsson`_, 2006 |
 +----------+------------------+-----------------------------+
+| ADM1p    | `bsm2`_          | `Alex`_ et al., 2008        |
++----------+------------------+-----------------------------+
+| mADM1    |                  |                             |
++----------+------------------+-----------------------------+
 | ASM1     | `asm`_ & `bsm1`_ | `Henze`_ et al., 2006       |
 +----------+------------------+-----------------------------+
 | ASM2d    | `asm`_ & `bsm1`_ | `Henze`_ et al., 2006       |
 +----------+------------------+-----------------------------+
-| PM2      | `pm2_ecorecover`_| N/A                         |
-|          | & `pm2_batch`_   |				    |
+| mASM2d   | `bsm2`_          | `Alex`_ et al., 2008        |
++----------+------------------+-----------------------------+
+| PM2      | `pm2_ecorecover`_|                             |
+|          | & `pm2_batch`_   |                             |
 +----------+------------------+-----------------------------+
 
 
@@ -41,10 +47,12 @@ List of Other Kinetic Modules
 .. _adm: https://github.com/QSD-Group/EXPOsan/tree/main/exposan/adm
 .. _asm: https://github.com/QSD-Group/EXPOsan/tree/main/exposan/asm
 .. _bsm1: https://github.com/QSD-Group/EXPOsan/tree/main/exposan/bsm1
+.. _bsm2: https://github.com/QSD-Group/EXPOsan/tree/main/exposan/bsm2
 .. _bwaise: https://github.com/QSD-Group/EXPOsan/tree/main/exposan/bwaise
 .. _pm2_batch: https://github.com/QSD-Group/EXPOsan/tree/main/exposan/pm2_batch
 .. _pm2_ecorecover: https://github.com/QSD-Group/EXPOsan/tree/main/exposan/pm2_ecorecover
 
+.. _Alex: http://iwa-mia.org/wp-content/uploads/2022/09/TR3_BSM_TG_Tech_Report_no_3_BSM2_General_Description.pdf
 .. _Batstone: https://iwaponline.com/ebooks/book/152/Anaerobic-Digestion-Model-No-1-ADM1
 .. _EPA design manual: https://nepis.epa.gov/Exe/ZyPURL.cgi?Dockey=3000464S.TXT
 .. _Henze: https://iwaponline.com/ebooks/book/96/
@@ -59,9 +67,11 @@ Links to docs
    :maxdepth: 1
 
    ADM1
+   ADM1p
    Aeration
    ASM1
    ASM2d
    Decay
    KineticReaction
+   mADM1
    PM2

docs/source/api/processes/mADM1.rst

@@ -0,0 +1,4 @@
+Modified Anaerobic Digestion Model No.1 (MADM1)
+===============================================
+.. autoclass:: qsdsan.processes.ModifiedADM1
+   :members:

docs/source/api/sanunits/MembraneGasExtraction.rst

@@ -0,0 +1,4 @@
+Membrane Gas Extraction
+=======================
+.. automodule:: qsdsan.sanunits._membrane_gas_extraction
+    :members:

docs/source/api/sanunits/_index.csv

@@ -38,12 +38,15 @@ Lagoon,No,No,Completed
 LiquidTreatmentBed,No,No,Completed
 LumpedCost,No,No,Completed
 MembraneDistillation,No,No,Completed
+MembraneGasExtraction,No,No,Completed
 MixTank,No,No,Completed
 Mixer,Yes,Yes,Completed
 MURT (multi-unit reinvented toilet),No,No,Completed
+PFR (plug flow reactor),Yes,No,Under development
 PhaseChanger,No,Yes,Completed
 PitLatrine,No,No,Completed
 PolishingFilter,No,No,Completed
+PrimaryClarifier,Yes,No,Completed
 Pump,Yes,No,Completed
 Reactor,No,No,Completed
 ReversedSplitter,No,Yes,Completed

docs/source/api/sanunits/_index.rst

@@ -49,15 +49,17 @@ Individual Unit Operations
    Lagoon
    membrane_bioreactor
    MembraneDistillation
+   MembraneGasExtraction
    non_reactive
    PolishingFilter
    pumping
    Reactor
    Screening
    Sedimentation
    SepticTank
-   sludge_thickening
    SludgePasteurization
+   sludge_thickening
+   sludge_treatment   
    suspended_growth_bioreactor
    tank
    toilet

docs/source/api/sanunits/sludge_treatment.rst

@@ -0,0 +1,4 @@
+Sludge Treatment
+================
+.. automodule:: qsdsan.sanunits._sludge_treatment
+    :members:

qsdsan/_component.py

@@ -561,6 +561,8 @@ def i_NOD(self, i):
         if i == None:
             if self.degradability in ('Readily', 'Slowly') or self.formula in ('H3N', 'NH4', 'NH3', 'NH4+', 'H4N+'):
                 i = self.i_N * molecular_weight({'O':4}) / molecular_weight({'N':1})
+            elif self.formula == 'N2':
+                i = self.i_N * molecular_weight({'O':5}) / molecular_weight({'N':2})
             elif self.formula in ('NO2-', 'HNO2'):
                 i = self.i_N * molecular_weight({'O':1}) / molecular_weight({'N':1})
             else:

qsdsan/_components.py

@@ -154,8 +154,10 @@ def extend(self, components):
     def compile(self, skip_checks=False):
         '''Cast as a :class:`CompiledComponents` object.'''
         components = tuple(self)
+        tmo._chemicals.prepare(components, skip_checks)
         setattr(self, '__class__', CompiledComponents)
-        try: self._compile(components, skip_checks)
+
+        try: self._compile(components)
         except Exception as error:
             setattr(self, '__class__', Components)
             setattr(self, '__dict__', {i.ID: i for i in components})
@@ -614,11 +616,11 @@ def compile(self, skip_checks=False):
         pass
 
 
-    def _compile(self, components, skip_checks=False):
+    def _compile(self, components):
         dct = self.__dict__
         tuple_ = tuple # this speeds up the code
         components = tuple_(dct.values())
-        CompiledChemicals._compile(self, components, skip_checks)
+        CompiledChemicals._compile(self, components)
         for component in components:
             missing_properties = component.get_missing_properties(_key_component_properties)
             if not missing_properties: continue

qsdsan/_process.py

@@ -694,6 +694,7 @@ def _rate_eq2func(self):
         def f(state_arr, params={}):
             states = dict(zip(var_kw, state_arr))
             return lamb(**states, **params)
+
         self.kinetics(function=f, parameters=self.parameters)
 
     def _normalize_stoichiometry(self, new_ref):
@@ -975,13 +976,14 @@ def __repr__(self):
     _default_data = None
 
     @classmethod
-    def load_from_file(cls, path='', components=None,
+    def load_from_file(cls, path='', components=None, data=None,
                        conserved_for=('COD', 'N', 'P', 'charge'), parameters=(),
                        use_default_data=False, store_data=False, compile=True,
                        **compile_kwargs):
         """
         Create :class:`CompiledProcesses` object from a table of process IDs, stoichiometric
-        coefficients, and rate equations stored in a .tsv, .csv, or Excel file.
+        coefficients, and rate equations stored in a .tsv, .csv, or Excel file, or as 
+        a `DataFrame`.
 
         Parameters
         ----------
@@ -990,6 +992,8 @@ def load_from_file(cls, path='', components=None,
         components : :class:`CompiledComponents`, optional
             Components corresponding to the columns in the stoichiometry matrix,
             to all components set in the system (i.e., through :func:`set_thermo`).
+        data : :class:`pandas.DataFrame`, optional
+            Data frame of the Petersen matrix.
         conserved_for : tuple[str], optional
             Materials subject to conservation rules, must have corresponding 'i\_'
             attributes for the components. Applied to all processes.
@@ -1022,16 +1026,18 @@ def load_from_file(cls, path='', components=None,
         """
         if use_default_data and cls._default_data is not None:
             data = cls._default_data
+        elif path:
+            data = load_data(path=path, index_col=0, na_values=0)
         else:
-            data = load_data(path=path, index_col=None, na_values=0)
-
+            if data is None: return None
+        
         cmps = _load_components(components)
 
         cmp_IDs = [i for i in data.columns if i in cmps.IDs]
         data.dropna(how='all', subset=cmp_IDs, inplace=True)
         new = cls(())
         for i, proc in data.iterrows():
-            ID = proc[0]
+            ID = i
             stoichio = proc[cmp_IDs]
             if data.columns[-1] in cmp_IDs: rate_eq = None
             else:
@@ -1223,7 +1229,7 @@ def f():
                 stoichio_arr = self.stoichiometry.to_numpy(dtype=float)
             except TypeError:
                 isa = isinstance
-                undefined = [k for k, v in dct_vals if not isa(v, (float, int))]
+                undefined = [k for k, v in dct_vals.items() if not isa(v, (float, int))]
                 raise TypeError(f'Undefined static parameters: {undefined}')
             self.__dict__['_stoichio_lambdified'] = lambda : stoichio_arr
 

qsdsan/_sanunit.py

@@ -215,7 +215,7 @@ def __init__(self, ID='', ins=None, outs=(), thermo=None, init_with='WasteStream
 
         if not kwargs.get('skip_property_package_check'):
             self._assert_compatible_property_package()
-            
+
         self._utility_cost = None
 
         ##### qsdsan-specific #####
@@ -274,7 +274,8 @@ def _convert_stream(self, strm_inputs, streams, init_with, ins_or_outs):
             elif v == 'ss':
                 converted.append(SanStream.from_stream(stream=s))
             else:
-                converted.append(WasteStream.from_stream(stream=s))
+                if isa(s, WasteStream): converted.append(s)
+                else: converted.append(WasteStream.from_stream(stream=s))
 
         diff = len(converted) + len(missing) - len(streams)
         if diff != 0: