UnitGroup

class UnitGroup(name=None, units=(), metrics=None, filter_savings=True, extend_feed_ends=True)

Create a UnitGroup object for generating biorefinery results.

Parameters:

• name (str, optional) – Name of group for bookkeeping.

• units (tuple[Unit], optional) – Unit operations.

• metrics=None (list[Metric], optional) – Metrics to generate results. These metrics are computed when generating results as dictionaries, pandas series, and data frames.

Examples

Create a UnitGroup from BioSTEAM’s example ethanol subsystem:

>>> from biorefineries.sugarcane import chemicals
>>> from biosteam import *
>>> settings.set_thermo(chemicals)
>>> water = Stream('water', Water=100., T=350.)
>>> sucrose = Stream('sucrose', Sucrose=3.)
>>> with System('example_sys') as example_sys:
...     P1 = Pump('P1', water)
...     T1 = MixTank('T1', (P1-0, sucrose))
...     H1 = HXutility('H1', T1-0, T=300.)
>>> example_sys.simulate()
>>> ugroup = UnitGroup('Example group', example_sys.units)

We can autofill metrics to evaluate:

>>> ugroup.autofill_metrics(electricity_production=True)
>>> ugroup.metrics
[<Metric: Installed equipment cost (MM$)>, <Metric: Cooling duty (GJ/hr)>, <Metric: Heating duty (GJ/hr)>, <Metric: Electricity consumption (MW)>, <Metric: Electricity production (MW)>, <Metric: Material cost (USD/hr)>]

Get all metric results:

>>> ugroup.to_dict()
{'Installed equipment cost [MM$]': 0.05, 'Cooling duty [GJ/hr]': 0.37, 'Heating duty [GJ/hr]': 0.0, 'Electricity consumption [MW]': 0.0, 'Electricity production [MW]': 0.0, 'Material cost [USD/hr]': 0.0}

Each result can be retrieved separately:

>>> ugroup.get_installed_cost()
0.05

>>> ugroup.get_cooling_duty()
0.37

The to_dict method also returns user-defined metrics:

>>> # First define metrics
>>> @ugroup.metric # Name of metric defaults to function name
... def moisture_content():
...     product = H1.outs[0]
...     return product.imass['Water'] / product.F_mass

>>> @ugroup.metric(units='kg/hr') # This helps for bookkeeping
... def sucrose_flow_rate():
...     return float(H1.outs[0].imass['Sucrose'])

>>> ugroup.show()
UnitGroup: Example group
 units: P1, T1, H1
 metrics: Installed equipment cost [MM$]
          Cooling duty [GJ/hr]
          Heating duty [GJ/hr]
          Electricity consumption [MW]
          Electricity production [MW]
          Material cost [USD/hr]
          Moisture content
          Sucrose flow rate [kg/hr]

>>> ugroup.to_dict()
{'Installed equipment cost [MM$]': 0.05, 'Cooling duty [GJ/hr]': 0.37, 'Heating duty [GJ/hr]': 0.0, 'Electricity consumption [MW]': 0.0, 'Electricity production [MW]': 0.0, 'Material cost [USD/hr]': 0.0, 'Moisture content': 0.63, 'Sucrose flow rate [kg/hr]': 1026.8}

name

[str] Name of group for bookkeeping

units

list[Unit] Unit operations

metrics

list[Metric] Metrics to generate results

filter_savings

[bool] Whether to only allow postive flows in utility results

extend_feed_ends

[bool] Whether to consider feeds past external storage, pumps, and heat exchangers for calculating material costs.

to_system(ID=None)

Return a System object of all units.

split(stream, upstream_name=None, downstream_name=None)

Split unit group in two; upstream and downstream.

Parameters:

• stream (Iterable[:class:~thermosteam.Stream], optional) – Stream where unit group will be split.

• upstream_name (str, optional) – Name of upstream UnitGroup object.

• downstream_name (str, optional) – Name of downstream UnitGroup object.

Examples

>>> from biorefineries.cornstover import cornstover_sys, M201
>>> from biosteam import default
>>> ugroup = cornstover_sys.to_unit_group()
>>> upstream, downstream = ugroup.split(M201-0)
>>> upstream.show()
UnitGroup: Unnamed
 units: U101, H2SO4_storage, T201, M201
>>> for i in upstream: assert i not in downstream.units
>>> assert set(upstream.units + downstream.units) == set(cornstover_sys.units)
>>> default() # Reset to biosteam defaults

metric(getter=None, name=None, units=None, element=None)

Define and register metric.

Parameters:

• getter (function, optional) – Should return metric.

• name (str, optional) – Name of parameter. If None, defaults to the name of the getter.

• units (str, optional) – Parameter units of measure

Notes

This method works as a decorator.

register_utility_agent(agent, basis='duty')

Register utility agent as a metric to UnitGroup.

property heat_utilities

[tuple] All HeatUtility objects.

property power_utilities

[tuple] All PowerUtility objects.

classmethod filter_by_types(name, units, types)

Create a UnitGroup object of given type(s).

classmethod filter_by_lines(name, units, lines)

Create a UnitGroup object of given line(s).

classmethod group_by_types(units, name_types=None)

Create a list of UnitGroup objects for each name-type pair.

classmethod group_by_lines(units, name_lines=None)

Create a list of UnitGroup objects for each name-line pair.

classmethod group_by_area(units)

Create a list of UnitGroup objects for each area available.

Examples

>>> from biosteam import *
>>> from biorefineries.cornstover import cornstover_sys
>>> areas = UnitGroup.group_by_area(cornstover_sys.units)
>>> areas[-1].show()
UnitGroup: 700
 units: T701, P701, T702, P702, M701,
        T703

>>> default() # Bring biosteam settings back to default

get_inlet_flow(units, key=None)

Return total flow across all inlets.

Parameters:

• units (str) – Units of measure.

• key (tuple[str] or str, optional) – Chemical identifiers. If none given, the sum of all chemicals returned

Examples

>>> from biosteam import Stream, Mixer, Splitter, UnitGroup, settings, main_flowsheet
>>> settings.set_thermo(['Water', 'Ethanol'])
>>> main_flowsheet.clear()
>>> S1 = Splitter('S1', Stream(Ethanol=10, units='ton/hr'), split=0.1)
>>> M1 = Mixer('M1', ins=[Stream(Water=10, units='ton/hr'), S1-0])
>>> sys = main_flowsheet.create_system(operating_hours=330*24)
>>> ugroup = UnitGroup('Example group', sys.units)
>>> ugroup.get_inlet_flow('ton/hr') # Sum of all chemicals
20.0
>>> ugroup.get_inlet_flow('ton/hr', 'Water') # Just water
10.0

get_outlet_flow(units, key=None)

Return total flow across all outlets.

Parameters:

• units (str) – Units of measure.

• key (tuple[str] or str, optional) – Chemical identifiers. If none given, the sum of all chemicals returned

Examples

>>> from biosteam import Stream, Mixer, Splitter, UnitGroup, settings, main_flowsheet
>>> settings.set_thermo(['Water', 'Ethanol'])
>>> main_flowsheet.clear()
>>> S1 = Splitter('S1', Stream(Ethanol=10, units='ton/hr'), split=0.1)
>>> M1 = Mixer('M1', ins=[Stream(Water=10, units='ton/hr'), S1-0])
>>> sys = main_flowsheet.create_system(operating_hours=330*24)
>>> sys.simulate()
>>> ugroup = UnitGroup('Example group', sys.units)
>>> ugroup.get_inlet_flow('ton/hr') # Sum of all chemicals
20.0
>>> ugroup.get_inlet_flow('ton/hr', 'Water') # Just water
10.0

get_material_cost()

Return the total material cost in USD/hr

get_utility_duty(agent)

Return the total utility duty for given agent in GJ/hr

get_utility_flow(agent)

Return the total utility flow for given agent in MT/hr

get_cooling_duty()

Return the total cooling duty in GJ/hr.

get_heating_duty()

Return the total heating duty in GJ/hr.

get_installed_cost()

Return the total installed equipment cost in million USD.

get_purchase_cost()

Return the total equipment purchase cost in million USD.

get_electricity_consumption()

Return the total electricity consumption in MW.

get_electricity_production()

Return the total electricity production in MW.

get_net_electricity_production()

Return the net electricity production in MW.

to_dict(with_units=True)

Return dictionary of results.

to_series(with_units=True)

Return a pandas.Series object of metric results.

classmethod df_from_groups(unit_groups, fraction=False, scale_fractions_to_positive_values=True)

Return a pandas DataFrame object of metric results from unit groups.

Parameters:

• unit_groups (Sequence[UnitGroup]) – Metric results will be calculated from unit groups.

• fraction (bool, optional.) – Whether to divide metric results by the total sum across all groups.

• scale_fractions_to_positive_values (bool, optional.) – Whether to compute fractions by dividing results by the sum of only positive results.

• s

Examples

Create a pandas DataFrame of the net eletricity production across all areas in the sugarcane biorefinery:

>>> import biosteam as bst
>>> from biorefineries import sugarcane as sc
>>> sc.load()
>>> unit_groups = bst.UnitGroup.group_by_area(sc.sys.units)
>>> for i in unit_groups:
...     metric = i.metric(i.get_net_electricity_production,
...                       'Net electricity production', 'kW')
>>> bst.UnitGroup.df_from_groups(
...     unit_groups, fraction=True,
...     scale_fractions_to_positive_values=True,
... )
     Net electricity production
0                           100
100                       -2.97
200                        -3.5
300                      -0.907
400                           0

>>> bst.UnitGroup.df_from_groups(
...     unit_groups, fraction=True,
...     scale_fractions_to_positive_values=False,
... )
     Net electricity production
0                           108
100                       -3.21
200                       -3.78
300                       -0.98
400                           0

>>> bst.default() # Reset to biosteam defaults