.. |check| unicode:: U+2713 .. contents:: .. _json_rep: ******************* JSON Representation ******************* The PyPES JSON file format is broken into four categories at the top level: 1. String ``Node`` ID list 2. String ``Connection`` ID list 3. String ``VirtualTag`` ID list 4. Key-value entries for each of actual :ref:`node` or :ref:`connection` objects (see :ref:`node_rep` and :ref:`conn_rep`), where keys are the string IDs from 1-3 Here is the simplest example of this structure, with two nodes, one connection, and no virtual tags: .. code-block:: json { "nodes": ["PowerGrid", "WWTP"], "connections": ["GridToPlant"], "virtual_tags": {}, "PowerGrid": { "type": "Network", "contents": ["Electricity", "NaturalGas"], "tags": {}, "nodes": [], "connections": [] }, "WWTP": { "input_contents": ["UntreatedSewage", "Electricity"], "output_contents": ["TreatedSewage"], "tags": {}, "nodes": [], "connections": [] }, "GridToPlant": { "type": "Wire", "source": "PowerGrid", "destination": "WWTP", "contents": "Electricity", "bidirectional": true, "tags": {} } } For integration with data-driven modeling applications, ``Tag`` objects that represent real-world sensors can be added to any other object. As a basica example, if there was an electrical meter with a database column name "grid_to_plant_kW", then we would add the following tag specification to the connection: .. code-block:: json "GridToPlant": { "type": "Wire", "source": "PowerGrid", "destination": "WWTP", "contents": "Electricity", "bidirectional": true, "tags": { "grid_to_plant_kW": { "type": "Flow", "units": "kWh", "contents": "Electricity", "totalized": false } } } One other thing to note about this connection is that "bidirectional" is set to ``true``. In the real world this means that electricity exports are allowed. PyPES will also take this into account (e.g., when querying all connections entering a node, it will return conncections that leave the node with "bidirectional"=``true``). Certain types of nodes, like the "WWTP" ``Facility`` and "PowerGrid" ``Network`` objects above, can have nodes and connections nested inside them. They take on the same structure as the top level. For example we could fill in the wastewater treatment facility with some basic processes: .. code-block:: json "WWTP": { "nodes": ["ProcessA", "ProcessB"], "connections": ["AtoB"], "ProcessA": { "type": "Clarification", "input_contents": "UntreatedSewage", "output_contents": "PrimaryEffluent", } "ProcessB": { }, "AtoB": { "type": "Pipe", "source": "ProcessA", "destination": "ProcessB", "contents": "Electricity" } } The following sections will detail how to represent different types of nodes (:ref:`node_rep`), connections (:ref:`conn_rep`), and tags (:ref:`tag_rep`) so that the meaning of fields such as "type", "num_units", "contents", etc. is clear. Putting all the above together, we have the following valid PyPES JSON representation: .. code-block:: json { "nodes": ["PowerGrid", "WWTP"], "connections": ["GridToPlant"], "virtual_tags": {}, "PowerGrid": { "type": "Network", "contents": ["Electricity", "NaturalGas"], "tags": {}, "nodes": [], "connections": [] }, "WWTP": { "input_contents": ["UntreatedSewage", "Electricity"], "output_contents": ["TreatedSewage"], "nodes": ["ProcessA", "ProcessB"], "connections": ["AtoB"], "ProcessA": { "type": "Clarification", "input_contents": "UntreatedSewage", "output_contents": "PrimaryEffluent", "num_units": 4, "flowrate": { "min": null, "max": null, "avg": 2, "units": "MGD" } } "ProcessB": { "type": "Aeration", "contents": ["PrimaryEffluent", "WasteActivatedSludge"], "num_units": 8, "flowrate": { "min": null, "max": null, "avg": 1.5, "units": "MGD" } }, "AtoB": { "type": "Pipe", "source": "ProcessA", "destination": "ProcessB", "contents": "Electricity" }, "tags": {} }, "GridToPlant": { "type": "Wire", "source": "PowerGrid", "destination": "WWTP", "contents": "Electricity", "bidirectional": true, "tags": { "grid_to_plant_kW": { "type": "Flow", "units": "kWh", "contents": "Electricity", "totalized": false } } } } A more complex example is avaiable at `wrrf_sample.json `_. .. _node_rep: Representing Nodes ================== The most generic structure of a node is outlined above in :ref:`json_rep`, but that just scratches the surface. There are numerous types of nodes, and each one has a number attributes. For example, a ``Digestion`` object must have ``id``, ``tags``, ``input_contents``, ``output_contents``, ``flowrate``, ``num_units``, and ``digester_type``. And a complete JSON representation of a digester might be: .. code-block:: json "AnaerobicDigester": { "type": "Digestion", "input_contents": "ThickenedSludgeBlend", "output_contents": "Biogas", "digester_type": "Anaerobic", "volume (cubic meters)": 2500, "num_units": 3, "flowrate": { "min": null, "max": null, "avg": null, "units": "MGD" }, "tags": {} } Some of the attributes can be left null (as we see in the above example with ``flowrate``). Optional attributes have default values (in the case of ``flowrate`` the default is ``null``), so it would be equally correct to leave ``flowrate`` out of the JSON file entirely. Below are two tables: first is all the ``Node`` subclasses and the second the attributes of each subclass. .. table:: Description of all potential attributes of ``Node`` class and subclasses +------------------------+-----------------------------------+---------------------------------------------------------------------+ | Attribute | Type | Description | +========================+===================================+=====================================================================+ | id | str | unique global identifier for the node in the WRRF database | +------------------------+-----------------------------------+---------------------------------------------------------------------+ | tags | dict of Tag or VirtualTag | dictionary of all tags directly associated with this node. | +------------------------+-----------------------------------+---------------------------------------------------------------------+ | input_contents | list of ContentsType | Contents entering the node (e.g., biogas or waste activated sludge) | +------------------------+-----------------------------------+---------------------------------------------------------------------+ | output_contents | list of ContentsType | Contents leaving the node (e.g., biogas or waste activated sludge) | +------------------------+-----------------------------------+---------------------------------------------------------------------+ | nodes | dict of Node | dictionary of all nodes that are children of this node | +------------------------+-----------------------------------+---------------------------------------------------------------------+ | connections | dict of Connection | dictionary of all connections that are children of this node | +------------------------+-----------------------------------+---------------------------------------------------------------------+ | elevation | Quantity [1]_ | facility/process elevation above sea level | +------------------------+-----------------------------------+---------------------------------------------------------------------+ | flow_rate | tuple of Quantity [1]_ | min, max, and average flow rate of a single unit | +------------------------+-----------------------------------+---------------------------------------------------------------------+ | num_units | int | number of identical parallel processes | +------------------------+-----------------------------------+---------------------------------------------------------------------+ | volume | Quantity [1]_ | volume of a single unit of the process | +------------------------+-----------------------------------+---------------------------------------------------------------------+ | horsepower | Quantity [1]_ | maximum horsepower of a single pump | +------------------------+-----------------------------------+---------------------------------------------------------------------+ | pump\_type | PumpType [2]_ | type of pump (either constant or variable frequency drive (VFD)) | +------------------------+-----------------------------------+---------------------------------------------------------------------+ | pump\_curve | func | function for the efficiency curve of a pump | +------------------------+-----------------------------------+---------------------------------------------------------------------+ | electrical\_efficiency | func | function for the electrical efficiency of a cogenerator | +------------------------+-----------------------------------+---------------------------------------------------------------------+ | thermal\_efficiency | func | function for the thermal efficiency of a boiler or cogenerator | +------------------------+-----------------------------------+---------------------------------------------------------------------+ | digester\_type | DigesterType [3]_ | type of digester (either aerobic or anaerobic) | +------------------------+-----------------------------------+---------------------------------------------------------------------+ | gen\_capacity | tuple of Quantity [1]_ | min, max, and average generation capacity of a single engine | +------------------------+-----------------------------------+---------------------------------------------------------------------+ | capacity | Quantity [1]_ | maximum battery storage capacity | +------------------------+-----------------------------------+---------------------------------------------------------------------+ | discharge\_rate | Quantity [1]_ | maximum discharge rate of the battery | +------------------------+-----------------------------------+---------------------------------------------------------------------+ .. table:: Matrix of attributes for each ``Node`` subclass +---------------+--------------------+----------------------+---------------------------------+----------------------------------+-----------------------+-----------------------------+---------------------------+----------------------------+----------------------------+------------------------+----------------------------+----------------------------+----------------+--------------------------+-------------------------+-------------------------------+--------------------------+--------------------------+--------------------------+ | | id | tags | input\_contents | output\_contents | nodes | connections | elevation | flow\_rate | num\_units | volume | horsepower | pump\_type | pump\_curve | electrical\_efficiency | thermal\_efficiency | digester\_type | gen\_capacity | capacity | discharge\_rate | +===============+====================+======================+=================================+==================================+=======================+=============================+===========================+============================+============================+========================+============================+============================+================+==========================+=========================+===============================+==========================+==========================+==========================+ | Node | |check| | |check| | |check| | |check| | | | | | | | | | | | | | | | | +---------------+--------------------+----------------------+---------------------------------+----------------------------------+-----------------------+-----------------------------+---------------------------+----------------------------+----------------------------+------------------------+----------------------------+----------------------------+----------------+--------------------------+-------------------------+-------------------------------+--------------------------+--------------------------+--------------------------+ | Network | |check| | |check| | |check| | |check| | |check| | |check| | | | | | | | | | | | | | | +---------------+--------------------+----------------------+---------------------------------+----------------------------------+-----------------------+-----------------------------+---------------------------+----------------------------+----------------------------+------------------------+----------------------------+----------------------------+----------------+--------------------------+-------------------------+-------------------------------+--------------------------+--------------------------+--------------------------+ | Facility | |check| | |check| | |check| | |check| | |check| | |check| | |check| | |check| | | | | | | | | | | | | +---------------+--------------------+----------------------+---------------------------------+----------------------------------+-----------------------+-----------------------------+---------------------------+----------------------------+----------------------------+------------------------+----------------------------+----------------------------+----------------+--------------------------+-------------------------+-------------------------------+--------------------------+--------------------------+--------------------------+ | Pump | |check| | |check| | |check| | |check| | | | |check| | |check| | |check| | | |check| | |check| | |check| | | | | | | | +---------------+--------------------+----------------------+---------------------------------+----------------------------------+-----------------------+-----------------------------+---------------------------+----------------------------+----------------------------+------------------------+----------------------------+----------------------------+----------------+--------------------------+-------------------------+-------------------------------+--------------------------+--------------------------+--------------------------+ | Tank | |check| | |check| | |check| | |check| | | | |check| | | | |check| | | | | | | | | | | +---------------+--------------------+----------------------+---------------------------------+----------------------------------+-----------------------+-----------------------------+---------------------------+----------------------------+----------------------------+------------------------+----------------------------+----------------------------+----------------+--------------------------+-------------------------+-------------------------------+--------------------------+--------------------------+--------------------------+ | Reservoir | |check| | |check| | |check| | |check| | | | |check| | | | |check| | | | | | | | | | | +---------------+--------------------+----------------------+---------------------------------+----------------------------------+-----------------------+-----------------------------+---------------------------+----------------------------+----------------------------+------------------------+----------------------------+----------------------------+----------------+--------------------------+-------------------------+-------------------------------+--------------------------+--------------------------+--------------------------+ | Screening | |check| | |check| | |check| | |check| | | | | |check| | |check| | | | | | | | | | | | +---------------+--------------------+----------------------+---------------------------------+----------------------------------+-----------------------+-----------------------------+---------------------------+----------------------------+----------------------------+------------------------+----------------------------+----------------------------+----------------+--------------------------+-------------------------+-------------------------------+--------------------------+--------------------------+--------------------------+ | Clarification | |check| | |check| | |check| | |check| | | | | |check| | |check| | |check| | | | | | | | | | | +---------------+--------------------+----------------------+---------------------------------+----------------------------------+-----------------------+-----------------------------+---------------------------+----------------------------+----------------------------+------------------------+----------------------------+----------------------------+----------------+--------------------------+-------------------------+-------------------------------+--------------------------+--------------------------+--------------------------+ | Aeration | |check| | |check| | |check| | |check| | | | | |check| | |check| | |check| | | | | | | | | | | +---------------+--------------------+----------------------+---------------------------------+----------------------------------+-----------------------+-----------------------------+---------------------------+----------------------------+----------------------------+------------------------+----------------------------+----------------------------+----------------+--------------------------+-------------------------+-------------------------------+--------------------------+--------------------------+--------------------------+ | Filtration | |check| | |check| | |check| | |check| | | | | |check| | |check| | |check| | | | | | | | | | | +---------------+--------------------+----------------------+---------------------------------+----------------------------------+-----------------------+-----------------------------+---------------------------+----------------------------+----------------------------+------------------------+----------------------------+----------------------------+----------------+--------------------------+-------------------------+-------------------------------+--------------------------+--------------------------+--------------------------+ | Chlorination | |check| | |check| | |check| | |check| | | | | |check| | |check| | |check| | | | | | | | | | | +---------------+--------------------+----------------------+---------------------------------+----------------------------------+-----------------------+-----------------------------+---------------------------+----------------------------+----------------------------+------------------------+----------------------------+----------------------------+----------------+--------------------------+-------------------------+-------------------------------+--------------------------+--------------------------+--------------------------+ | Thickening | |check| | |check| | |check| | |check| | | | | |check| | |check| | |check| | | | | | | | | | | +---------------+--------------------+----------------------+---------------------------------+----------------------------------+-----------------------+-----------------------------+---------------------------+----------------------------+----------------------------+------------------------+----------------------------+----------------------------+----------------+--------------------------+-------------------------+-------------------------------+--------------------------+--------------------------+--------------------------+ | Digestion | |check| | |check| | |check| | |check| | | | | |check| | |check| | |check| | | | | | | |check| | | | | +---------------+--------------------+----------------------+---------------------------------+----------------------------------+-----------------------+-----------------------------+---------------------------+----------------------------+----------------------------+------------------------+----------------------------+----------------------------+----------------+--------------------------+-------------------------+-------------------------------+--------------------------+--------------------------+--------------------------+ | Conditioning | |check| | |check| | |check| | |check| | | | | |check| | |check| | | | | | | | | | | | +---------------+--------------------+----------------------+---------------------------------+----------------------------------+-----------------------+-----------------------------+---------------------------+----------------------------+----------------------------+------------------------+----------------------------+----------------------------+----------------+--------------------------+-------------------------+-------------------------------+--------------------------+--------------------------+--------------------------+ | Cogeneration | |check| | |check| | |check| | |check| | | | | | |check| | | | | | |check| | |check| | | |check| | | | +---------------+--------------------+----------------------+---------------------------------+----------------------------------+-----------------------+-----------------------------+---------------------------+----------------------------+----------------------------+------------------------+----------------------------+----------------------------+----------------+--------------------------+-------------------------+-------------------------------+--------------------------+--------------------------+--------------------------+ | Boiler | |check| | |check| | |check| | |check| | | | | | |check| | | | | | | |check| | | |check| | | | +---------------+--------------------+----------------------+---------------------------------+----------------------------------+-----------------------+-----------------------------+---------------------------+----------------------------+----------------------------+------------------------+----------------------------+----------------------------+----------------+--------------------------+-------------------------+-------------------------------+--------------------------+--------------------------+--------------------------+ | Flaring | |check| | |check| | |check| | | | | | | | | | | | | | | | | | +---------------+--------------------+----------------------+---------------------------------+----------------------------------+-----------------------+-----------------------------+---------------------------+----------------------------+----------------------------+------------------------+----------------------------+----------------------------+----------------+--------------------------+-------------------------+-------------------------------+--------------------------+--------------------------+--------------------------+ | Battery | |check| | |check| | |check| | |check| | | | | | | | | | | | | | | |check| | |check| | +---------------+--------------------+----------------------+---------------------------------+----------------------------------+-----------------------+-----------------------------+---------------------------+----------------------------+----------------------------+------------------------+----------------------------+----------------------------+----------------+--------------------------+-------------------------+-------------------------------+--------------------------+--------------------------+--------------------------+ An example of how to define all the potential attributes is available in `wrrf_sample.json `_. .. _conn_rep: Representing Connections ======================== The most generic structure of a node is outlined above in :ref:`json_rep`, but that just scratches the surface. There are numerous types of connections, and each one has a number attributes. .. table:: Description of all potential attributes of ``Connection`` class and subclasses +------------------+-----------------------------------+---------------------------------------------------------------------------------+ | Attribute | Type | Description | +==================+===================================+=================================================================================+ | id | str | unique global identifier for the node in the WRRF database | +------------------+-----------------------------------+---------------------------------------------------------------------------------+ | tags | dict of Tag or VirtualTag | dictionary of all tags directly associated with this node. | +------------------+-----------------------------------+---------------------------------------------------------------------------------+ | contents | list of ContentsType | Contents moving through the connection (e.g., biogas or waste activated sludge) | +------------------+-----------------------------------+---------------------------------------------------------------------------------+ | source | Node | Starting point of the connection | +------------------+-----------------------------------+---------------------------------------------------------------------------------+ | destination | Node | Endpoint of the connection | +------------------+-----------------------------------+---------------------------------------------------------------------------------+ | bidirectional | bool | whether flow can go from destination to source. False by default | +------------------+-----------------------------------+---------------------------------------------------------------------------------+ | exit_point | Node | The child node from which this connection leaves its source. | +------------------+-----------------------------------+---------------------------------------------------------------------------------+ | entry_point | Node | The child node at which this connection enters its destination. | +------------------+-----------------------------------+---------------------------------------------------------------------------------+ | flow_rate | tuple of Quantity [1]_ | min, max, and average flow rate of a single unit | +------------------+-----------------------------------+---------------------------------------------------------------------------------+ | diameter | Quantity [1]_ | inner diameter of a pipe | +------------------+-----------------------------------+---------------------------------------------------------------------------------+ | friction_coeff | float | Friction coefficient for a pipe | +------------------+-----------------------------------+---------------------------------------------------------------------------------+ | pressure | Quantity [1]_ | Minimum, maximum, and average pressure in a pipe | +------------------+-----------------------------------+---------------------------------------------------------------------------------+ | heating_values | tuple of Quantity [1]_ | The lower and higher heating values of the gas in the pipe. | +------------------+-----------------------------------+---------------------------------------------------------------------------------+ .. table:: Matrix of attributes for each ``Connection`` subclass +------------+--------------------+----------------------+--------------------------+------------------------+-----------------------------+-------------------------------+-----------------------------+------------------------------+----------------------------+--------------------------+---------------------------------+--------------------------+---------------------------------+ | | id | tags | contents | source | destination | bidirectional | exit\_point | entry\_point | flow\_rate | diameter | friction\_coeff | pressure | heating\_values | +============+====================+======================+==========================+========================+=============================+===============================+=============================+==============================+============================+==========================+=================================+==========================+=================================+ | Connection | |check| | |check| | |check| | |check| | |check| | |check| | |check| | |check| | | | | | | +------------+--------------------+----------------------+--------------------------+------------------------+-----------------------------+-------------------------------+-----------------------------+------------------------------+----------------------------+--------------------------+---------------------------------+--------------------------+---------------------------------+ | Wire | |check| | |check| | |check| | |check| | |check| | |check| | |check| | |check| | | | | | | +------------+--------------------+----------------------+--------------------------+------------------------+-----------------------------+-------------------------------+-----------------------------+------------------------------+----------------------------+--------------------------+---------------------------------+--------------------------+---------------------------------+ | Pipe | |check| | |check| | |check| | |check| | |check| | |check| | |check| | |check| | |check| | |check| | |check| | |check| | |check| | +------------+--------------------+----------------------+--------------------------+------------------------+-----------------------------+-------------------------------+-----------------------------+------------------------------+----------------------------+--------------------------+---------------------------------+--------------------------+---------------------------------+ An example of how to define all the potential attributes is available in `wrrf_sample.json `_. .. _tag_rep: Representing Tags ================== Both nodes and connections can have tags nested inside them. These tags represent sensors or data points at the facility. Two types of tags exist in PyPES: ``Tag`` and ``VirtualTag`` objects. Basic ``Tag`` ************* As with other objects, the ``tags`` dictionary is nested within the corresponding ``Node`` or ``Connection``, and the keys are the string IDs for the facility's database column names. The JSON format to represent a single tag in PyPES is as follows: .. code-block:: json "TankVolume": { "type": "Volume", "units": "gallons", "contents": "FatOilGrease" } Where ``type`` is a string from :ref:`tag_type`, ``units`` is a `Pint `_ parseable string, and ``contents_type`` a string form :ref:`contents_type`. Multiple tags can be attached to a node. For example: .. code-block:: json "FOGTank": { "type": "Tank", "contents": "FatOilGrease", "tags": { "TankVolume": { "type": "Volume", "units": "gallons", "contents": "FatOilGrease" }, "TankLevel": { "type": "Level", "units": "feet", "contents": "FatOilGrease" } } } .. _vtag_rep: ``VirtualTag`` ************** The ``VirtualTag`` class provides users with a powerful way to combine data from existing sensors to create new "virtual" sensors. Specifically, a user can define their own function or lambda expression that takes in other ``Tag`` or ``VirtualTag`` objects and computes the resulting data. These combinations can be quite simple. For example, let's calculate the cogenerator efficiency from the following plant configuration: .. code-block:: json "WWTP": { "nodes": ["AnaerobicDigester", "Cogenerator", "VirtualDemand"], "connections": ["CogenElecToFacility", "DigesterToCogenerator"], "virtual_tags": {} "Cogenerator": { "Cogenerator": { "type": "Cogeneration", "num_units": 1, "input_contents": ["Biogas", "NaturalGas"], "output_contents": ["Electricity", "Heat"], "tags": {} }, "AnaerobicDigester": { "type": "Digestion", "input_contents": "ThickenedSludgeBlend", "output_contents": "Biogas", "digester_type": "Anaerobic", "volume (cubic meters)": 2500, "num_units": 2, "tags": {} }, "VirtualDemand": { "type": "Network", "contents": ["Electricity", "Heat"], "tags": {}, "nodes": [], "connections": [] }, "CogenElecToFacility": { "type": "Wire", "source": "Cogenerator", "destination": "VirtualDemand", "contents": "Electricity", "bidirectional": false, "tags": { "ElectricityGeneration": { "type": "Flow", "units": "kilowatt", "contents": "Electricity", "totalized": false } } }, "DigesterToCogenerator": { "type": "Pipe", "source": "AnaerobicDigester", "destination": "Cogenerator", "contents": "Biogas", "heating_values": { "lower": 600, "higher": 700, "units": "BTU/scf" }, "tags": { "Digester1GasFlow": { "type": "Flow", "units": "SCFM", "source_unit_id": 1, "dest_unit_id": "total", "contents": "Biogas", "totalized": false } "Digester2GasFlow": { "type": "Flow", "units": "SCFM", "source_unit_id": 2, "dest_unit_id": "total", "contents": "Biogas", "totalized": false } } } } First, we need to add a ``VirtualTag`` that sums the biogas flows into the cogenerator. Since the child ``Tag`` objects are all inside "DigesterToCogenerator" ``Pipe``, this can be done at the lowest level: .. code-block:: json "DigesterToCogenerator": { "type": "Pipe", "source": "AnaerobicDigester", "destination": "Cogenerator", "contents": "Biogas", "heating_values": { "lower": 600, "higher": 700, "units": "BTU/scf" }, "tags": { "Digester1GasFlow": { "type": "Flow", "units": "SCFM", "source_unit_id": 1, "dest_unit_id": "total", "contents": "Biogas", "totalized": false } "Digester2GasFlow": { "type": "Flow", "units": "SCFM", "source_unit_id": 2, "dest_unit_id": "total", "contents": "Biogas", "totalized": false }, "Digester3GasFlow": { "type": "Flow", "units": "SCFM", "source_unit_id": 3, "dest_unit_id": "total", "contents": "Biogas", "totalized": false } }, "virtual_tags": { "BiogasProductionCombined": { "tags": ["Digester1GasFlow", "Digester2GasFlow", "Digester3GasFlow"], "operations": "lambda x, y, z: x + y + z", "units": "SCFM" } } } Then, another ``VirtualTag`` could be used to divide the biogas production by electricity generation. This tag would be located at the facility level since it is combining data from two different ``Connection`` objects. .. code-block:: json "WWTP": { "nodes": ["AnaerobicDigester", "Cogenerator", "VirtualDemand"], "connections": ["CogenElecToFacility", "DigesterToCogenerator"], "virtual_tags": { "ElectricalEfficiency": { "tags": ["BiogasProductionCombined", "ElectricityGeneration"], "operations": "lambda x, y: x / y", "units": "SCFM / kW" } } } .. table:: Members of ``VirtualTag`` class +--------------------+----------------------+--------------------------------------------------------------------------------------------------------+ | Attribute | Type | Description | +====================+======================+========================================================================================================+ | id | str | unique global identifier for the tag in the WRRF database | +--------------------+----------------------+--------------------------------------------------------------------------------------------------------+ | units | Unit [1]_ | Units for the tag. Can be null, e.g., if a Boolean variable. | +--------------------+----------------------+--------------------------------------------------------------------------------------------------------+ | tag\_type | TagType | Type of data saved under the tag. E.g., InfluentFlow or RunTime. | +--------------------+----------------------+--------------------------------------------------------------------------------------------------------+ | tags | list of Tag | tags to combine according to specified operations | +--------------------+----------------------+--------------------------------------------------------------------------------------------------------+ | unary\_operations | list of str | Unary operations to apply before combining tags | +--------------------+----------------------+--------------------------------------------------------------------------------------------------------+ | binary\_operations | list or str | Binary operations to apply before combining tags | +--------------------+----------------------+--------------------------------------------------------------------------------------------------------+ | parent\_id | str | Identifier for the parent object (either a Node or Connection) | +--------------------+----------------------+--------------------------------------------------------------------------------------------------------+ | totalized | bool | True if data is totalized, or a running summation reset periodically (usually daily). False otherwise. | +--------------------+----------------------+--------------------------------------------------------------------------------------------------------+ | contents | ContentsType | Contents measured by the tag (e.g., biogas or primary effluent) | +--------------------+----------------------+--------------------------------------------------------------------------------------------------------+ .. _tag_type: ``TagType`` Enum **************** .. table:: Members of ``TagType`` enum +---------------+-----------------------------------------------------------------------------------------------------+---------------------------------------------------------+ | Member | Description | Default Units | +===============+=====================================================================================================+=========================================================+ | Flow | flow of any contents (electricity, water, gas, sludge) | kW (electricity) `or` m\ :sup:`3` d\ :sup:`-1` (fluids) | +---------------+-----------------------------------------------------------------------------------------------------+---------------------------------------------------------+ | Volume | volume of fluid in a tank | m\ :sup:`3` | +---------------+-----------------------------------------------------------------------------------------------------+---------------------------------------------------------+ | Level | height of fluid in a tank | m | +---------------+-----------------------------------------------------------------------------------------------------+---------------------------------------------------------+ | Pressure | force per unit area | Pa | +---------------+-----------------------------------------------------------------------------------------------------+---------------------------------------------------------+ | Temperature | average kinetic energy of particles | K | +---------------+-----------------------------------------------------------------------------------------------------+---------------------------------------------------------+ | RunTime | binary variable indicating if equipment is on (1) or off (0) | unitless | +---------------+-----------------------------------------------------------------------------------------------------+---------------------------------------------------------+ | RunStatus | fraction of time equipment is on | unitless | +---------------+-----------------------------------------------------------------------------------------------------+---------------------------------------------------------+ | VSS | concentration of volatile suspended solids | mg L\ :sup:`-1` | +---------------+-----------------------------------------------------------------------------------------------------+---------------------------------------------------------+ | TSS | concentration of total suspended solids | mg L\ :sup:`-1` | +---------------+-----------------------------------------------------------------------------------------------------+---------------------------------------------------------+ | TDS | concentration of total dissolved solids | mg L\ :sup:`-1` | +---------------+-----------------------------------------------------------------------------------------------------+---------------------------------------------------------+ | COD | chemical oxygen demand | mg L\ :sup:`-1` | +---------------+-----------------------------------------------------------------------------------------------------+---------------------------------------------------------+ | BOD | biochemical oxygen demand | mg L\ :sup:`-1` | +---------------+-----------------------------------------------------------------------------------------------------+---------------------------------------------------------+ | pH | measure of acidity | unitless | +---------------+-----------------------------------------------------------------------------------------------------+---------------------------------------------------------+ | Conductivity | ease with which an electric charge moves | Siemens m\ :sup:`-1` | +---------------+-----------------------------------------------------------------------------------------------------+---------------------------------------------------------+ | Turbidity | the opaqueness of a fluid | NTU | +---------------+-----------------------------------------------------------------------------------------------------+---------------------------------------------------------+ | Rotation | number of revolutions (useful for motors/pumps) | RPM | +---------------+-----------------------------------------------------------------------------------------------------+---------------------------------------------------------+ | Efficiency | fraction of a quantity retained during a process (e.g., conversion of heat to electricity) | unitless | +---------------+-----------------------------------------------------------------------------------------------------+---------------------------------------------------------+ | StateOfCharge | fraction of max capacity currently available in a battery | unitless | +---------------+-----------------------------------------------------------------------------------------------------+---------------------------------------------------------+ | InFlow | flow into a node | kW (electricity) `or` m\ :sup:`3` d\ :sup:`-1` (fluids) | +---------------+-----------------------------------------------------------------------------------------------------+---------------------------------------------------------+ | OutFlow | flow out of a node | kW (electricity) `or` m\ :sup:`3` d\ :sup:`-1` (fluids) | +---------------+-----------------------------------------------------------------------------------------------------+---------------------------------------------------------+ | NetFlow | net flow (i.e., flow in minus flow out) of a node | kW (electricity) `or` m\ :sup:`3` d\ :sup:`-1` (fluids) | +---------------+-----------------------------------------------------------------------------------------------------+---------------------------------------------------------+ .. _contents_type: ``ContentsType`` Enum ===================== A fundamental facet of process engineering is the conversion of reactants to products. In PyPES, these changes are represented by the ``ContentsType`` enum. For consistency, both ``input_contents`` and ``output_contents`` are represented as lists even when there is only a single member. For example, a ``Cogeneration`` object typically has ``input_contents=[ContentsType.Biogas, ContentsType.NaturalGas]`` and ``output_contents=[ContentsType.Electricity]`` Each node has distinct input and output contents, while a connection is assumed to have a single ``ContentsType`` list since it is simply transporting the contents. As a shorthand, instead of specifying ``input_contents`` and ``output_contents`` separately, the user can simply enter ``contents`` and the value will be set to both attributes. I.e., the below are two ways to represent the same node in JSON format: .. code-block:: json "PowerGrid": { "type": "Network", "contents": ["Electricity", "NaturalGas"], "tags": {}, "nodes": [], "connections": [] } .. code-block:: json "PowerGrid": { "type": "Network", "input_contents": ["Electricity", "NaturalGas"], "output_contents": ["Electricity", "NaturalGas"], "tags": {}, "nodes": [], "connections": [] } Supported ``ContentsType`` values are shown in the table below. .. table:: Members of ``ContentsType`` enum +----------------------+-------------------------------------------------------------+ | \hline Member | Description | +======================+=============================================================+ | UntreatedSewage | raw wastewater before any treatment | +----------------------+-------------------------------------------------------------+ | PrimaryEffluent | liquid outflow from primary clarification | +----------------------+-------------------------------------------------------------+ | SecondaryEffluent | liquid outflow from secondary clarification | +----------------------+-------------------------------------------------------------+ | TertiaryEffluent | outflow from tertiary treatment | +----------------------+-------------------------------------------------------------+ | TreatedSewage | fully treated (i.e., disinfected) plant effluent | +----------------------+-------------------------------------------------------------+ | DrinkingWater | conventionally treated or desalinated water | +----------------------+-------------------------------------------------------------+ | PotableReuse | water recovered at potable standards | +----------------------+-------------------------------------------------------------+ | NonpotableReuse | water recovered at non-potable standards | +----------------------+-------------------------------------------------------------+ | Biogas | mix of CH\ :sub:`4` and CO\ :sub:`2` produced by digesters | +----------------------+-------------------------------------------------------------+ | NaturalGas | fossil CH\ :sub:`4` purchased from the grid | +----------------------+-------------------------------------------------------------+ | GasBlend | a blend of fossil natural gas and biogas | +----------------------+-------------------------------------------------------------+ | FatOilGrease | fats, oils, and greases (FOG) | +----------------------+-------------------------------------------------------------+ | PrimarySludge | settled solids from primary clarification | +----------------------+-------------------------------------------------------------+ | TPS | thickened primary sludge | +----------------------+-------------------------------------------------------------+ | WasteActivatedSludge | settled solids from secondary clarification | +----------------------+-------------------------------------------------------------+ | TWAS | thickened waste activated sludge | +----------------------+-------------------------------------------------------------+ | Scum | solids skimmed off the top of aeration basins | +----------------------+-------------------------------------------------------------+ | FoodWaste | organic food waste delivered to the facility | +----------------------+-------------------------------------------------------------+ | SludgeBlend | a mix of unthickened solids (e.g., scum and primary sludge) | +----------------------+-------------------------------------------------------------+ | ThickenedSludgeBlend | a mix of thickened solids (e.g., TPS and TWAS) | +----------------------+-------------------------------------------------------------+ | Electricity | includes grid purchases and on-site generation | +----------------------+-------------------------------------------------------------+ | Brine | saline waste stream from desalination process | +----------------------+-------------------------------------------------------------+ | Seawater | water from the ocean | +----------------------+-------------------------------------------------------------+ | SurfaceWater | water from rivers, streams, or lakes | +----------------------+-------------------------------------------------------------+ | Groundwater | water pumped from underground | +----------------------+-------------------------------------------------------------+ | Stormwater | stormwater runoff (for separated drainage systems) | +----------------------+-------------------------------------------------------------+ | Heat | heat energy generated by on-site processes | +----------------------+-------------------------------------------------------------+ | Oil | oil of any form (e.g., combustion or lubrication) | +----------------------+-------------------------------------------------------------+ | Grease | grease for any purpose (e.g., digestion or lubrication) | +----------------------+-------------------------------------------------------------+ .. _num_units: ``num_units`` Attribute ======================= There are often identical parallel processes in a treatment train. The ``num_units`` attribute exists to ease the effort needed to represent these identical objects. For example, the anaerobic digester from :ref:`vtag_rep` was specified with three digesters in parallel. That example shows how flow from the three digesters can be tracked separately by specifying a ``source_unit_id`` or ``dest_unit_id`` for each ``Tag``. .. code-block:: json "num_units": 3 By default ``num_units`` is set to 1, meaning there is only a single instance and no parallel processes. .. _elevation: ``elevation`` Attribute ======================= Elevations can be assigned to some nodes to help calculate the headloss or pressure drop throughout the system. Currently, elevation is only supported by ``Facility``, ``Pump``, ``Tank``, and ``Reservoir`` nodes, but that could easily be extended in the future. By default the ``elevation`` attribute is null. To assign an elevation to a node, simply add the following entry to its JSON dictionary: .. code-block:: json "elevation (meters)": 10 Currently, the units are hardcoded as meters, but this will soon be modified to match the dictionary-style unit-parsing from :ref:`flowrate` and :ref:`gen_capacity`. .. _volume: ``volume`` Attribute ==================== Elevations can be assigned to some nodes to help calculate the headloss or pressure drop throughout the system. Currently, elevation is only supported by ``Tank``, ``Reservoir``, ``Aeration``, ``Filtration``, ``Chlorination``, ``Thickening``, ``Digestion``, and ``Conditioning`` nodes, but that could easily be extended in the future. By default the ``volume`` attribute is null. To assign a volume to a node, simply add the following entry to its JSON dictionary: .. code-block:: json "volume (cubic meters)": 10 Currently, the units are hardcoded as cubic meters, but this will soon be modified to match the dictionary-style unit-parsing from :ref:`flowrate` and :ref:`gen_capacity`. .. _flowrate: ``flow_rate`` Attribute ======================= Flow rates in PyPES are defined as tuples of the form ``(min, max, avg)``. Any member of the tuple can be left as ``None``. For example, if there is only a minimum of maximum flow rate. Units must be specified (e.g., m\ :sup:`3` / day or ft\ :sup:`3` / min) as text strings. The average flow rate can also be used to keep track of design flow, which will be between min and max. Note that this is the flow rate for a **single** unit in a parallel process, so the combined flow rate would require multiplying by ``num_units``. Both `"flowrate"` and `"flow_rate"` are acceptable keys to use in the JSON representation. So the following two represent the same ``flow_rate`` attribute: .. code-block:: json "flowrate": { "min": 0, "max": 1000, "avg": 100, "units": "m3pd" } .. code-block:: json "flowrate": { "min": 0, "max": 1000, "avg": 100, "units": "m3pd" } Outside of JSON, `node.Node.set_flow_rate `_ can be used to change a ``Node`` or ``Connection`` objects ``flow_rate`` attribute. .. _gen_capacity: ``gen_capacity`` Attribute ========================== Generation capacity of a boiler or cogenerator is represented as a ``(min, max, avg)`` tuple just like the :ref:`flowrate`:. Note that this is the generation capacity for a **single** engine if there are multiple, so the combined flow rate would require multiplying by ``num_units``. Both `"generation_capacity"` and `"gen_capacity"` are acceptable keys to use in the JSON representation. .. code-block:: json "generation_capacity": { "min": 200, "max": 650, "avg": 450, "units": "kW" } Since both heat and electricity are forms of energy, the generation capacity for the ``Cogenerator`` is tied to the electricity generation and for the ``Boiler`` to heat generation. Then, for the ``Cogenerator`` the heat generation capacity can be calculated by converting from electricity to heat using ``electrical_efficiency`` and ``thermal_efficiency``. .. _heat_val: ``heating_values`` Attribute ============================ .. _capacity: ``capacity`` Attribute ====================== The ``capacity`` attribute provides the maximum storage capacity for a ``Battery`` object. To assign a value to the ``capacity`` in JSON: .. code-block:: json "capacity (kWh)": 2000 Currently, the units are hardcoded as kilowatt-hours, but this will soon be modified to match the dictionary-style unit-parsing from :ref:`flowrate` and :ref:`gen_capacity`. .. _discharge_rate: ``discharge_rate`` Attribute ============================ The ``discharge_rate`` attribute provides the maximum rate of discharge (and at the moment charge, but these will be separated in the future) for a ``Battery`` object. To assign a value to the ``discharge_rate`` in JSON: .. code-block:: json "discharge_rate (kW)": 10 Currently, the units are hardcoded as kilowatts, but this will soon be modified to match the dictionary-style unit-parsing from :ref:`flowrate` and :ref:`gen_capacity`. .. [1] from `Pint `_ .. [2] ``PumpType`` is an enum that contains two members: ``Constant`` or ``VFD`` .. [3] ``DigesterType`` is an enum that contains two members: ``Aerobic`` or ``Anaerobic``