add new features for reporting and diagrams

Author: yoelcortes

biosteam/_system.py

@@ -2149,6 +2149,10 @@ def _thorough_digraph(self, graph_attrs):
     def _cluster_digraph(self, graph_attrs):
         return digraph_from_system(self, **graph_attrs)
 
+    def _stage_digraph(self, graph_attrs):
+        with self.stage_configuration(aggregated=False) as conf:
+            return digraph_from_units(conf.stages, conf.streams, **graph_attrs)
+
     def diagram(self, kind: Optional[int|str]=None, file: Optional[str]=None, 
                 format: Optional[str]=None, display: Optional[bool]=True,
                 number: Optional[bool]=None, profile: Optional[bool]=None,
@@ -2163,9 +2167,10 @@ def diagram(self, kind: Optional[int|str]=None, file: Optional[str]=None,
         ----------
         kind :
             * 0 or 'cluster': Display all units clustered by system.
-            * 1 or 'thorough': Display every unit within the path.
+            * 1 or 'thorough': Display every unit within the system.
             * 2 or 'surface': Display only elements listed in the path.
-            * 3 or 'minimal': Display a single box representing all units.
+            * 3 or 'minimal': Display a single box representing the system.
+            * 4 or 'stage': Display every stage within the system.
         file : 
             File name to save diagram. 
         format:
@@ -2203,6 +2208,8 @@ def diagram(self, kind: Optional[int|str]=None, file: Optional[str]=None,
                 f = self._surface_digraph(graph_attrs)
             elif kind == 3 or kind == 'minimal':
                 f = self._minimal_digraph(graph_attrs)
+            elif kind == 4 or kind == 'stage':
+                f = self._stage_digraph(graph_attrs)
             else:
                 raise ValueError("kind must be one of the following: "
                                  "0 or 'cluster', 1 or 'thorough', 2 or 'surface', "
@@ -3486,7 +3493,14 @@ def results(self, with_units=True):
             return series
 
     # Report summary
-    def save_report(self, file: Optional[str]='report.xlsx', dpi: Optional[str]='900', **stream_properties): 
+    def save_report(
+            self, 
+            file: Optional[str]='report.xlsx', 
+            dpi: Optional[str]='900', 
+            sheets=None,
+            stage=False,
+            **stream_properties
+        ): 
         """
         Save a system report as an xlsx file.
         
@@ -3500,83 +3514,108 @@ def save_report(self, file: Optional[str]='report.xlsx', dpi: Optional[str]='900
             Additional stream properties and units as key-value pairs (e.g. T='degC', flow='gpm', H='kW', etc..)
             
         """
+        if sheets is None:
+            sheets = {
+                'Flowsheet',
+                'Itemized costs',
+                'Stream table',
+                'Utilities',
+                'Design requirements',
+                'Reactions',
+                # 'Specifications'
+            }
         writer = pd.ExcelWriter(file)
         units = sorted(self.units, key=lambda x: x.line)
         cost_units = [i for i in units if i._design or i._cost]
-        try:
-            with bst.preferences.temporary() as p:
-                p.reset()
-                p.light_mode()
-                self.diagram('thorough', file='flowsheet', dpi=str(dpi), format='png')
-        except:
-            diagram_completed = False
-            warn(RuntimeWarning('failed to generate diagram through graphviz'), stacklevel=2)
-        else:
-            import PIL.Image
+        if 'Flowsheet' in sheets:
             try:
-                # Assume openpyxl is used
-                worksheet = writer.book.create_sheet('Flowsheet')
-                flowsheet = openpyxl.drawing.image.Image('flowsheet.png')
-                worksheet.add_image(flowsheet, anchor='A1')
-            except PIL.Image.DecompressionBombError:
-                PIL.Image.MAX_IMAGE_PIXELS = int(1e9)
-                flowsheet = openpyxl.drawing.image.Image('flowsheet.png')
-                worksheet.add_image(flowsheet, anchor='A1')
+                with bst.preferences.temporary() as p:
+                    p.reset()
+                    p.light_mode()
+                    kind = 'stage' if stage else 'thorough'
+                    self.diagram(kind, file='flowsheet', dpi=str(dpi), format='png')
             except:
-                # Assume xlsx writer is used
+                diagram_completed = False
+                warn(RuntimeWarning('failed to generate diagram through graphviz'), stacklevel=2)
+            else:
+                import PIL.Image
                 try:
-                    worksheet = writer.book.add_worksheet('Flowsheet')
+                    # Assume openpyxl is used
+                    worksheet = writer.book.create_sheet('Flowsheet')
+                    flowsheet = openpyxl.drawing.image.Image('flowsheet.png')
+                    worksheet.add_image(flowsheet, anchor='A1')
+                except PIL.Image.DecompressionBombError:
+                    PIL.Image.MAX_IMAGE_PIXELS = int(1e9)
+                    flowsheet = openpyxl.drawing.image.Image('flowsheet.png')
+                    worksheet.add_image(flowsheet, anchor='A1')
                 except:
-                    warn("problem in saving flowsheet; please submit issue to BioSTEAM with"
-                         "your current version of openpyxl and xlsx writer", RuntimeWarning)
-                worksheet.insert_image('A1', 'flowsheet.png')
-            diagram_completed = True
+                    # Assume xlsx writer is used
+                    try:
+                        worksheet = writer.book.add_worksheet('Flowsheet')
+                    except:
+                        warn("problem in saving flowsheet; please submit issue to BioSTEAM with"
+                             "your current version of openpyxl and xlsx writer", RuntimeWarning)
+                    worksheet.insert_image('A1', 'flowsheet.png')
+                diagram_completed = True
 
-        tea = self.TEA
-        if tea:
+        if 'Itemized costs' in sheets:
             tea = self.TEA
-            cost = report.cost_table(tea)
-            cost.to_excel(writer, 'Itemized costs')
-            tea.get_cashflow_table().to_excel(writer, 'Cash flow')
-        else:
-            warn(f'Cannot find TEA object in {repr(self)}. Ignoring TEA sheets.',
-                 RuntimeWarning, stacklevel=2)
-        
-        # Stream tables
-        # Organize streams by chemicals first
-        streams_by_chemicals = {}
-        for i in self.streams:
-            if not i: continue
-            chemicals = i.chemicals
-            if chemicals in streams_by_chemicals:
-                streams_by_chemicals[chemicals].append(i)
+            if tea:
+                tea = self.TEA
+                cost = report.cost_table(tea)
+                cost.to_excel(writer, 'Itemized costs')
+                tea.get_cashflow_table().to_excel(writer, 'Cash flow')
             else:
-                streams_by_chemicals[chemicals] = [i]
-        stream_tables = []
-        for chemicals, streams in streams_by_chemicals.items():
-            stream_tables.append(report.stream_table(streams, chemicals=chemicals, T='K', **stream_properties))
-        report.tables_to_excel(stream_tables, writer, 'Stream table')
+                warn(f'Cannot find TEA object in {repr(self)}. Ignoring TEA sheets.',
+                     RuntimeWarning, stacklevel=2)
 
-        # Heat utility tables
-        heat_utilities = report.heat_utility_tables(cost_units)
-        n_row = report.tables_to_excel(heat_utilities, writer, 'Utilities')
+        if 'Stream table' in sheets:
+            if stage:
+                with self.stage_configuration() as conf:
+                    stream_tables = report.stream_tables(conf.streams, **stream_properties)
+            else:
+                stream_tables = report.stream_tables(self.streams, **stream_properties)
+            report.tables_to_excel(stream_tables, writer, 'Stream table')
 
-        # Power utility table
-        power_utility = report.power_utility_table(cost_units)
-        n_row = report.tables_to_excel([power_utility], writer, 'Utilities', n_row=n_row)
+        if 'Utilities' in sheets:
+            # Heat utility tables
+            heat_utilities = report.heat_utility_tables(cost_units)
+            n_row = report.tables_to_excel(heat_utilities, writer, 'Utilities')
 
-        # Fees table
-        other_utilities = report.other_utilities_table(cost_units)
-        n_row = report.tables_to_excel(other_utilities, writer, 'Utilities', n_row=n_row)
+            # Power utility table
+            power_utility = report.power_utility_table(cost_units)
+            n_row = report.tables_to_excel([power_utility], writer, 'Utilities', n_row=n_row)
+            
+            # Fees table
+            other_utilities = report.other_utilities_table(cost_units)
+            n_row = report.tables_to_excel(other_utilities, writer, 'Utilities', n_row=n_row)
 
-        # General desing requirements
-        results = report.unit_result_tables(cost_units)
-        report.tables_to_excel(results, writer, 'Design requirements')
+        if 'Design requirements' in sheets:
+            # General desing requirements
+            results = report.unit_result_tables(cost_units)
+            report.tables_to_excel(results, writer, 'Design requirements')
 
-        # Reaction tables
-        reactions = report.unit_reaction_tables(units)
-        report.tables_to_excel(reactions, writer, 'Reactions')
+        if 'Reactions' in sheets:
+            # Reaction tables
+            reactions = report.unit_reaction_tables(units)
+            report.tables_to_excel(reactions, writer, 'Reactions')
 
+        if 'Specifications' in sheets:
+            if stage:
+                with self.stage_configuration() as conf:
+                    specifications = [
+                        u._mass_and_energy_balance_specifications_table()
+                        for u in conf.stages
+                    ]
+            else:
+                specifications = [
+                    u._mass_and_energy_balance_specifications_table()
+                    for u in units
+                ]
+            report.tables_to_excel(
+                specifications, writer, 
+                'Specifications'
+            )
         writer.close()
         if diagram_completed: os.remove("flowsheet.png")
 

biosteam/_unit.py

@@ -1327,6 +1327,22 @@ def simulate(self,
             self.run()
         self._summary(design_kwargs, cost_kwargs)
 
+    def _mass_and_energy_balance_specifications(self):
+        return (self.line, ())
+
+    def _mass_and_energy_balance_specifications_table(self):
+        title, specs = self._mass_and_energy_balance_specifications()
+        index = []
+        values = []
+        for name, value, units in specs:
+            index.append(name)
+            values.append([value, units])
+        df = pd.DataFrame(
+            values, index, ('Values', 'Units')
+        )
+        df.columns.name = f"{title} - {self.ID}"
+        return df
+
     def results(self, with_units=True, include_utilities=True,
                 include_total_cost=True, include_installed_cost=False,
                 include_zeros=True, external_utilities=None, key_hook=None,

biosteam/report/system_stages.json

@@ -0,0 +1 @@
+{"acetic_acid_simple": 13, "acetic_acid_complex_decoupled": 21, "acetic_acid_complex": 44, "butanol_purification": 4, "ethanol_purification": 2, "haber_bosch_process": 4}

biosteam/report/table.py

@@ -16,7 +16,8 @@
 DataFrame = pd.DataFrame
 ExcelWriter = pd.ExcelWriter
 
-__all__ = ('stream_table', 'cost_table', 'unit_reaction_tables',
+__all__ = ('stream_table', 'stream_tables', 
+           'cost_table', 'unit_reaction_tables',
            'unit_result_tables', 'heat_utility_tables',
            'power_utility_table', 'tables_to_excel', 'voc_table',
            'other_utilities_table', 
@@ -700,6 +701,20 @@ def other_utilities_table(units):
 
 # %% Streams
 
+def stream_tables(streams, **stream_properties):
+    streams_by_chemicals = {}
+    stream_tables = []
+    for i in streams:
+        if not i: continue
+        chemicals = i.chemicals
+        if chemicals in streams_by_chemicals:
+            streams_by_chemicals[chemicals].append(i)
+        else:
+            streams_by_chemicals[chemicals] = [i]
+    for chemicals, streams in streams_by_chemicals.items():
+        stream_tables.append(stream_table(streams, chemicals=chemicals, T='K', **stream_properties))
+    return stream_tables
+
 def stream_table(streams, flow='kg/hr', percent=True, chemicals=None, **props):
     """
     Return a stream table as a pandas DataFrame object.

biosteam/system_stages.json

@@ -0,0 +1 @@
+{"acetic_acid_simple": 13, "acetic_acid_complex_decoupled": 21, "acetic_acid_complex": 44, "butanol_purification": 4, "ethanol_purification": 2, "haber_bosch_process": 4}

biosteam/units/_flash.py

@@ -331,6 +331,7 @@ def _cost_vacuum(self):
     def _design_parameters(self):
         # Retrieve run_args and properties
         vap, liq, *_ = self._outs
+        if self.has_vapor_condenser: vap = self.vapor_condenser.outs[0]
         rhov = vap.get_property('rho', 'lb/ft3')
         rhol = liq.get_property('rho', 'lb/ft3')
         P = liq.get_property('P', 'psi')  # Pressure (psi)

biosteam/units/compressor.py

@@ -567,6 +567,12 @@ def _run(self):
         if self.system and self.system.algorithm == 'Phenomena oriented':
             self._coeffs = {self: feed.T, feed.source: out.T} # dT_out = (T_out/T_in) * dT_in
 
+    def _mass_and_energy_balance_specifications(self):
+        return 'Compressor', [
+            ('Isentropic efficiency', 100 * self.eta, '%'),
+            ('P', self.P, 'Pa'),
+        ]
+        
     def _design(self):
         super()._design()
         self._set_power(self.design_results['Ideal power'] / self.eta)
@@ -585,24 +591,27 @@ def _update_nonlinearities(self):
         source = feed.source
         if source is None or source._energy_variable != 'T': return []
         data = product.get_data()
+        T_product = product.T
         self._run()
-        self._coeffs = {self: feed.T, source: product.T} # dT_out = (T_out/T_in) * dT_in
+        # self._coeffs = {self: feed.T, source: T_product} # dT_out = (T_out/T_in) * dT_in
         product.set_data(data)
+        product.T = T_product
 
     def _create_energy_departure_equations(self): 
+        return []
         # Special case where T_out = f(T_in)
         # 0 = Cp * log(T/T0) - R * log(P/P0)
         # log(T/T0) = R / Cp * log(P/P0)
         # T = T0 * exp(R / Cp * log(P/P0))
         # T = T0 * P/P0 * exp(R/Cp)
-        feed = self.ins[0]
-        product = self.outs[0]
-        if len(product.phases) > 1:
-            raise NotImplementedError('energy departure equation with multiple phase not yet implemented for isentropic compressors')
-        source = feed.source
-        # TODO: add method <Stream>.energy_variable -> 'T'|'B'
-        if source is None or source._energy_variable != 'T': return []
-        return [(self._coeffs, 0)]
+        # feed = self.ins[0]
+        # product = self.outs[0]
+        # if len(product.phases) > 1:
+        #     raise NotImplementedError('energy departure equation with multiple phase not yet implemented for isentropic compressors')
+        # source = feed.source
+        # # TODO: add method <Stream>.energy_variable -> 'T'|'B'
+        # if source is None or source._energy_variable != 'T': return []
+        # return [(self._coeffs, 0)]
 
     def _create_material_balance_equations(self, composition_sensitive):
         fresh_inlets, process_inlets, equations = self._begin_equations(composition_sensitive)
@@ -621,8 +630,8 @@ def _create_material_balance_equations(self, composition_sensitive):
         )
         return equations
 
-    def _update_energy_variable(self, departure):
-        self.outs[0].T += departure
+    # def _update_energy_variable(self, departure):
+    #     self.outs[0].T += departure
 
 
 class PolytropicCompressor(Compressor, new_graphics=False):

biosteam/units/distillation.py

@@ -346,7 +346,36 @@ def _init(self,
         self.vacuum_system_preference = vacuum_system_preference
         self._load_components(partial_condenser, condenser_thermo, reboiler_thermo)
         self.LHK = LHK
-        
+      
+    def _mass_and_energy_balance_specifications(self):
+        spec = self.product_specification_format
+        specs = []
+        if spec == 'Composition':
+            self._Lr = self._Hr = None
+        elif spec == 'Recovery':
+            self._y_top = self._x_bot = None
+        specs.append( 
+            ('Partial condenser', self._partial_condenser, '-'),
+        )
+        if spec == 'Composition':
+            specs.extend([
+                ('Distillate light key fraction', 100 * self._y_top, '%'),
+                ('Bottoms product heavy key fraction', 100 * self._x_bot, '%'),
+            ])
+        elif spec == 'Recovery':
+            specs.extend([
+                ('Light key recovery', 100 * self._Lr, '%'),
+                ('Heavy key recovery', 100 * self._Hr, '%'),
+            ])
+        else:
+            raise RuntimeError('invalid product specification format')
+        if isinstance(self, ShortcutColumn):
+            return 'Shortcut column', specs
+        elif isinstance(self, BinaryDistillation):
+            return 'Binary distillation', specs
+        else:
+            raise NotImplementedError('unknown name for distillation class')
+            
     def _reset_thermo(self, thermo):
         super()._reset_thermo(thermo)
         self.LHK = self._LHK
@@ -1947,6 +1976,8 @@ def _estimate_mean_volatilities_relative_to_heavy_key(self):
         alpha_mean = compute_mean_volatilities_relative_to_heavy_key(
             K_distillate, K_bottoms, HK_index
         )
+        distillate.T = dp.T
+        bottoms.T = bp.T
         return alpha_mean
 
     def _estimate_distillate_recoveries(self):