OPGEE Core Classes¶

The OPGEE core classes are implemented in several Python modules, described below, and illustrated in the following figure.

`opgee.core`¶

This module contains core classes of the opgee package.

class opgee.core.A(name, value=None, pytype=None, unit=None, explicit=False)¶

The <A> element represents the value of an attribute previously defined in attributes.xml or a user-provided file. Note that this class is not instantiated using from_xml() approach since values are merged with metadata from attributes.xml.

set_value(value)¶

Sets the instances’ value to the value given, using the stored pytype for type conversion and unit to define a pint.Quantity, if given.

Parameters:: value – (str, numerical, or pint.Quantity) the value to possibly convert
Returns:: the value, converted to pytype, and with unit, if specified.

str_value()¶

Return the value of an attribute as a string.

Returns:: (str) string representation of the attribute value

class opgee.core.TemperaturePressure(T, P)¶: Stores temperature and pressure together for convenience.

class opgee.core.XmlInstantiable(name, parent=None)¶

This is the superclass for all classes that are instantiable from XML. The requirements of such classes are:

They subclass from XmlInstantiable or its subclasses
They define __init__(self, name, **kwargs) and call super().__init__(name)
They define @classmethod from_xml(cls, element, parent=None) to create an instance from XML.
Subclasses of Container and Process implement run(self) to perform any required operations.

adopt(objs, asDict=False)¶

Set the parent of each object to self. This is used to create back pointers up the hieararchy so Processes and Streams can find their Field and Analysis containers. Return the objects either as a list or dict.

Parameters:

objs – (None or list of XmlInstantiable)
asDict – (bool) if True, return a dict of objects keyed by their name, otherwise return a list of the objects.

Returns:

(list) If objs is None, return an empty list or dict (per asDict), otherwise return the objs either in a list or dict.

find_container(cls)¶

Ascend the parent links in the object hierarchy until an object of class cls is found, or an object with a parent that is None.

Parameters:: cls – (type or str name of type) the class of the parent sought
Returns:: (XmlInstantiable or None) the desired parent instance or None

opgee.core.dict_from_list(objs)¶

Create a dictionary of XMLInstantiable objects by their name attribute, but raise an error if any name is repeated.

Parameters:: objs – (list of XMLInstantiable instances) the object to create dict from.
Returns:: (dict) objects keyed by name
Raises:: OpgeeException if a any name is repeated

opgee.core.instantiate_subelts(elt, cls, parent=None, as_dict=False, include_names=None)¶

Return a list of instances of cls (or of its indicated subclass of Process).

Parameters:

elt – (lxml.etree.Element) the parent element
cls – (type) the class to instantiate. If cls is Process, the class will be that indicated instead in the element’s “class” attribute.
parent – (XmlInstantiable) the parent to record in each object instantiated
as_dict – (bool) if True, return a dictionary of subelements, keyed by name
include_names – (list of str) Names of elements to include (i.e., the element’s attrib dict must have a “name” item, whose value is compared to the list). If include_names is not None, then elements with names not in the list are ignored.

Returns:

(list) instantiated objects

opgee.core.magnitude(value, units=None)¶

Return the magnitude of value. If value is a pint.Quantity and units is not None, check that value has the expected units and return the magnitude of value. If value is not a pint.Quantity, just return it.

Parameters:

value – (float or pint.Quantity) the value for which we return the magnitude.
units – (None or pint.Unit) the expected units

Returns:

the magnitude of value

opgee.core.validate_unit(unit)¶

Return the pint.Unit associated with the string unit, or None if unit is None or not in the unit registry.

Parameters:: unit – (str) a string representation of a pint.Unit
Returns:: (pint.Unit or None)

`opgee.analysis`¶

class opgee.analysis.Analysis(name, parent=None, attr_dict=None, field_names=None, groups=None)¶

Describes a single Analysis, which can contain multiple Fields, including several attributes common to an analysis, including:

functional unit (oil or gas),
system boundary (e.g., Production, Distribution),
time horizon for GWPs (20 or 100 year), and
which IPCC assessment report to use for CO2-equivalence values (AR4, AR5, AR5 with C-cycle feedback, or AR6).

`opgee.attributes`¶

class opgee.attributes.AttrDef(name, parent=None, value=None, pytype=None, option_set=None, unit=None, constraints=None, exclusive=None, synchronized=None)¶

classmethod from_xml(elt, parent=None)¶

Instantiate an instance from an XML element

Parameters:

elt – (etree.Element) representing an <AttrDef> element
parent – (None) ignored for this class

Returns:

(AttrDef) instance of class AttrDef

class opgee.attributes.AttrDefs(root)¶

Parse and provide access to attributes.xml metadata file. This is a singleton class: use AttrDefs.get_instance() rather than calling AttrDefs() directly.

class_attrs(classname, raiseError=True)¶

Return the ClassAttrs instance for the named class. If not found: if raise_error is True, a KeyError will be raised; if raise_error is False, None will be returned.

Parameters:

classname – (str) the name of the class to find attributes for
raiseError – (bool) whether failure to find class should raise an error

Returns:

(ClassAttrs) the instance defining attributes for classname.

Raises:

OpgeeError if raiseError is True and classname is not in the dict.

class opgee.attributes.AttributeMixin(attr_dict=None)¶

Consolidates attribute-related code shared by Container and Process classes. Note: must be mixed into classes that have both self.attr_dict and self.attr_defs.

attrs_with_prefix(prefix)¶

Collect a group of similarly-prefixed attributes into a dictionary keyed by the portion of the name after the prefix.

Parameters:: prefix – (str) a common prefix shared by multiple attributes
Returns:: (dict) attribute objects keyed by the portion of the name after the prefix.

classmethod instantiate_attrs(elt, is_process=False)¶

Instantiate the attributes defined in XML for class cls. To avoid an import loop, we don’t import Process from process.py, so the caller tells us whether cls is a subclass of Process.

Parameters:

elt – (lxml.etree.Element) the element under which to find attribute defs.
is_process – (bool) True if cls is a subclass of Process.

Returns:

none

set_attr(attr_name, value)¶: Set attr_name, which must be a known attribute, to value.

class opgee.attributes.ClassAttrs(name, attr_dict, option_dict)¶

Support for parsing attributes.xml metadata

classmethod from_xml(elt, parent=None)¶

Instantiate an instance from an XML element

Parameters:

elt – (etree.Element) representing an <ClassAttrs> element
parent – (None) ignored for this class

Returns:

(ClassAttrs) instance of class ClassAttrs

class opgee.attributes.Options(name, default, options)¶

`opgee.container`¶

class opgee.container.Container(name, attr_dict=None, parent=None)¶

Generic hierarchical node element, has a name and contains other Containers and/or Processes (and subclasses thereof).

children(include_disabled=False)¶

Return all directly contained Process and Container objects below this Container. See also self.descendant_procs() and`self.descendant_aggs()`.

Parameters:: include_disabled – (bool) whether to include disabled nodes.
Returns:: (list of Containers and/or Processes)

descendant_aggs()¶

Return a list of all descendent Container instances.

Returns:: (list of opgee.Container)

descendant_procs(include_disabled=False)¶

Return all Processes contained in the current Container or its sub-Containers.

Parameters:: include_disabled – (bool) whether to include disabled nodes.
Returns:: (list of Processes)

get_emission_rates(analysis, procs_to_exclude=None)¶

Return the emission rates (Series) including the calculated GHG values based on the current choice of GWP values in the enclosing Model.

Returns:: (pandas.Series) the emissions Series.

get_energy_rates()¶: Return the energy consumption rates by summing those of our children nodes, recursively working our way down the Container hierarchy, and storing each result at each container level.

get_net_imported_product()¶: Return a energy rate (water is mass rate) of net imported product. The positive value means the amount needs imported, while the negative value mean the amount needs exported

`opgee.emissions`¶

class opgee.emissions.Emissions¶

Emissions is an object wrapper around a pandas.Series holding emission flow rates for a pre-defined set of substances, defined in Emissions.emissions.

add_from_series(category, series)¶

Add emission flow rates from a Series instance to the given emissions’ category.

Parameters:

category – (str) one of the defined emissions categories
series – (Series)

Returns:

none

add_from_stream(category, stream)¶

Add emission flow rates from a Stream instance to the given emissions’ category.

Parameters:

category – (str) one of the defined emissions categories
stream – (Stream)

Returns:

none

add_rate(category, gas, rate)¶

Add to the stored rate of emissions for a single gas.

Parameters:

category – (str) one of the defined emissions categories
gas – (str) one of the defined emissions (values of Emissions.emissions)
rate – (float) the increment in rate in the Process’ flow units (e.g., mmbtu (LHV) of fuel burned)

Returns:

none

add_rates(category, **kwargs)¶

Add emissions to those already stored, for the given emissions category, of one or more gases, given as keyword arguments, e.g., add_rates(‘Venting’, CO2=100, CH4=30, N2O=6).

Parameters:

category – (str) one of the defined emissions categories
kwargs – (dict) the keyword arguments

Returns:

none

add_rates_from(emissions)¶

Add rates from emissions instance

Parameters:: emissions –
Returns:

compute_GHG(gwp)¶

Compute and store total CO2-eq GHGs using the given Series of GWP values.

Parameters:: gwp – (pandas.Series) the GWP values to use, expected to have the same index as self.data (i.e., Emissions.emissions)
Returns:: none

classmethod create_emissions_matrix()¶

Create a pandas DataFrame to hold emissions.

Returns:: (pandas.DataFrame) Zero-filled emissions DataFrame

emissions = ['VOC', 'CO', 'CH4', 'N2O', 'CO2']¶: Emissions.emissions defines the set of substances tracked by this class. In addition, the Model class computes CO2-equivalent GHG emission using its current settings for GWP values and stored in a row with index ‘GHG’.

rates(gwp=None)¶

Return the emission rates, and optionally, the calculated GHG value.

Parameters:: gwp – (pandas.Series or None) the GWP values to use to compute GHG
Returns:: (pandas.DataFrame) If gwp is none, the ‘GHG’ row of the DataFrame will contain zeroes, otherwise CO2-equivalents will be computed using the Series gwp.

reset_GHG()¶

Reset all GHG values to zeroes.

Returns:: none

set_from_series(category, series)¶

Set emission flow rates from a Series instance to the given emissions’ category.

Parameters:

category – (str) one of the defined emissions categories
series – (Series)

Returns:

none

set_from_stream(category, stream)¶

Set emission flow rates from a Stream instance to the given emissions’ category.

Parameters:

category – (str) one of the defined emissions categories
stream – (Stream)

Returns:

none

set_rate(category, gas, rate)¶

Set the rate of emissions for a single gas.

Parameters:

category – (str) one of the defined emissions categories
gas – (str) one of the defined emissions (values of Emissions.emissions)
rate – (float) the rate in the Process’ flow units (e.g., mmbtu (LHV) of fuel burned)

Returns:

none

set_rates(category, **kwargs)¶

Set the emissions rate for a single emissions category of one or more gases, given as keyword arguments, e.g., set_rates(EM_FUGITIVES, CO2=100, CH4=30, N2O=6).

Parameters:

category – (str) one of the defined emissions categories
kwargs – (dict) the keyword arguments

Returns:

none

exception opgee.emissions.EmissionsError(func_name, category, gas)¶

`opgee.energy`¶

class opgee.energy.Energy¶

Energy is an object wrapper around a pandas.Series holding energy consumption rates for a pre-defined set of energy carriers, defined in Energy.carriers.

add_rate(carrier, rate)¶

Add to the rate of energy use for a single carrier.

Parameters:

carrier – (str) one of the defined energy carriers (values of Energy.carriers)
rate – (float) the increment in rate of use (e.g., mmbtu/day (LHV) for all but electricity, which is in units of kWh/day.

Returns:

none

add_rates(dictionary)¶

Add to the energy use rate for one or more carriers.

Parameters:: dictionary – (dict) the carriers and rates
Returns:: none

add_rates_from(energy)¶

Add rates from energy instance

Parameters:: energy –
Returns:

carriers = ['Natural gas', 'Upgrader proc. gas', 'NGL', 'Crude oil', 'Diesel', 'Residual fuel', 'Pet. coke', 'Electricity']¶: carriers defines the energy carriers tracked by this class. Note that when used in the code, the defined variables (EN_NATURAL_GAS, EN_UPG_PROC_GAS, EN_NGL, EN_CRUDE_OIL, EN_DIESEL, EN_RESID, EN_PETCOKE, EN_ELECTRICITY) should be used to avoid dependencies on the specific strings.

classmethod create_energy_series()¶

Create a pandas Series to hold energy consumption rates.

Returns:: (pandas.Series) Zero-filled energy carrier Series

get_rate(carrier)¶

Get the rate of energy use for a single carrier

Parameters:: carrier – (str) one of the defined energy carriers (values of Energy.carriers)
Returns:: (float) the rate of use (e.g., mmbtu/day (LHV) for all but electricity, which is in units of kWh/day.

rates()¶

Return the energy use data.

Returns:: (pandas.Series) energy use data.

reset()¶

Reset energy instance

Returns:

set_rate(carrier, rate)¶

Set the rate of energy use for a single carrier.

Parameters:

carrier – (str) one of the defined energy carriers (values of Energy.carriers)
rate – (float) the rate of use (e.g., mmbtu/day (LHV) for all but electricity, which is in units of kWh/day.

Returns:

none

set_rates(dictionary)¶

Set the energy use rate of one or more carriers.

Parameters:: dictionary – (dict) the carriers and rates
Returns:: none

`opgee.field`¶

class opgee.field.Field(name, attr_dict=None, parent=None, group_names=None)¶

A Field contains all the Process instances associated with a single oil or gas field, and the Stream instances that connect them. It also holds an instance of Reservoir, which is a source (it has outputs only), in the process structure.

Fields can contain mutually exclusive process choice sets that group processes to be enabled or disabled together as a coherent group. The “active” set is determimed by the value of attributes named the same as the <ProcessChoice> element.

See {opgee}/etc/attributes.xml for attributes defined for the <Field>. See also OPGEE XML documentation

all_processes()¶

Gets all instances of subclasses of Process for this Field, including disabled Processes.

Returns:: (iterator of Process (subclasses) instances) in this Field

boundary_energy_flow_rate(analysis, raiseError=True)¶

Return the energy flow rate for the user’s chosen system boundary, functional unit (oil vs gas)

Parameters:

analysis – (Analysis) the analysis this field is part of
raiseError – (bool) whether to raise an error if the energy flow is zero at the boundary

Returns:

(pint.Quantity) the energy flow at the boundary

boundary_process(analysis) → Process¶

Return the currently chosen boundary process.

Returns:: (opgee.Process) the currently chosen boundary process

check_enabled_processes()¶: Iterate all processes and allow them to check if they should be disabled before they run.

collect_processes()¶

Recursively descend the Field’s Aggregators to create a list of all processes defined for this field. Includes Field’s builtin processes.

Returns:: (list of instances of Process subclasses) the processes defined for this field

static comp_fugitive_loss(loss_mat_ave, assignment)¶

Given assignment, find the loss rate in the loss rate table

Parameters:

loss_mat_ave –
assignment –

Returns:

static comp_fugitive_productivity(prod_mat_gas, mean)¶

Given field mean, find the value in the gas productivity table

Parameters:

mean –
prod_mat_gas –

Returns:

compute_carbon_intensity(analysis)¶

Compute carbon intensity by summing emissions from all processes within the selected system boundary and dividing by the flow of the functional unit across that boundary stream.

Parameters:: analysis – (Analysis) the analysis this field is part of
Returns:: (pint.Quantity) carbon intensity in units of g CO2e/MJ

defined_boundaries()¶: Return the names of all boundaries defined in configuration system)

dump()¶

Print out a representation of the field’s processes and streams for debugging.

Returns:: none

finalize_process_graph()¶

Apply Smart Defaults and resolve process choices, which may depend on values of Smart Defaults. This can modify the process structure by including or excluding process groups, so we do this before computing the process network graph.

Returns:: nothing

find_process(name, raiseError=True)¶

Find the Process of class name in this Field. If not found: if raiseError is True, an error is raised, else None is returned.

Parameters:

name – (str) the name of the subclass of Process to find
raiseError – (bool) whether to raise an error if the Process is not found.

Returns:

(Process or None) the requested Process, or None if not found and raiseError is False.

Raises:

OpgeeException if name is not found and raiseError is True

find_stream(name, raiseError=True)¶

Find the Stream with name in this Field. If not found: if raiseError is True, an error is raised, else None is returned.

Parameters:

name – (str) the name of the Stream to find
raiseError – (bool) whether to raise an error if the Stream is not found.

Returns:

(Stream or None) the requested Stream, or None if not found and raiseError is False.

Raises:

OpgeeException if name is not found and raiseError is True

classmethod from_xml(elt, parent=None)¶

Instantiate an instance from an XML element

Parameters:

elt – (etree.Element) representing a <Field> element
parent – (opgee.Analysis) the Analysis containing the new Field

Returns:

(Field) instance populated from XML

get_carbon_credit(byproduct_names, analysis)¶

Calculate carbon credit from byproduct used for displacement co-production method

Parameters:: net_import – (Pandas.Series) net import energy rates (water is mass rate)
Returns:: total emissions (units of g CO2)

get_completion_and_workover_C1_rate()¶

Calculate the total C1 rate for completion and workover events in a well system.

This function takes into account the attributes ‘is_flaring’, ‘is_REC’, and ‘frac_well_fractured’ to determine the C1 rates for completion and workover events. The calculation uses a dataframe containing C1 rates for different scenarios of hydraulic fracturing, well type, flaring, and REC.

Returns:: float: The total C1 rate for completion and workover events in the well system.

get_component_fugitive()¶

Calculate loss rate for downhole pump, separation, and crude oil storage using Jeff’s component fugitive model

Returns:: (Pandas.Series) Process unit loss rate

get_imported_emissions(net_import)¶

Calculate imported product emissions based on the upstream CI from GREET1_2016

Parameters:: net_import – (Pandas.Series) net import energy rates (water is mass rate)
Returns:: total emissions (units of g CO2)

get_process_data(name, raiseError=None)¶

Retrieve a stored value from the field’s process_data dictionary.

Parameters:: name – (str) the name of the data element (the dictionary key)
Returns:: (any) the value
Raises:: OpgeeException – if the name is not found in process_data.

instances_by_class(cls)¶

Find one or more instances of cls known to this Field instance. If cls is Field, just return self; if cls is a subclass of Process, find any instances in the field’s process_dict.

Parameters:: cls – (Class) the class to find
Returns:: (Field or list of instances of the Process subclass) if found, else None

processes()¶

Gets all instances of subclasses of Process for this Field.

Returns:: (iterator of Process (subclasses) instances) in this Field

report(include_streams=False)¶: Print a text report showing Streams, energy, and emissions.

resolve_process_choices(process_choice_dict=None)¶

Disable all processes referenced in a ProcessChoice, then enable only the processes in the selected ProcessGroup. The name of each ProcessChoice must also identify a field-level attribute, whose value indicates the user’s choice of ProcessGroup.

Parameters:: process_choice_dict – (dict) optional dictionary for nested process choices. Used in recursive calls only.
Returns:: None

run(analysis, compute_ci=True, trial_num=None)¶

Run all Processes defined for this Field, in the order computed from the graph characteristics, using the settings in analysis (e.g., GWP).

Parameters:

analysis – (Analysis) the Analysis to use for analysis-specific settings.
compute_ci – (bool) if False, CI calculation is not performed (used by some tests)

Returns:

None

save_process_data(**kwargs)¶

Allows a Process to store arbitrary data in the field’s process_data dictionary for access by other processes.

Parameters:

name – (str) the name of the data element (the dictionary key)
value – (any) the value to store in the dictionary

Returns:

none

streams()¶

Gets all enabled Stream instances for this Field.

Returns:: (iterator of Stream instances) streams in this Field

validate()¶

Perform logical checks on the field after loading the entire model to ensure the field is “well-defined”. This allows the processing code to avoid testing validity at run-time. Field conditions include:

Cycles cannot span the current boundary.
Aggregators cannot span the current boundary.
The chosen system boundary is defined for this field
Logical contradictions in attribute some settings

Returns:: none
Raises:: ModelValidationError – raised if any validation condition is violated.

`opgee.graph`¶

opgee.graph.write_class_diagram(pathname, show_process_subclasses=False)¶

Create and save a graph of the class hierarchy starting from OpgeeObject. If show_process_subclasses is True, all classes are shown, notably including the dozens of subclasses of Process; otherwise, subclasses of Process are excluded.

Parameters:

pathname – (str) the file to create
limit – (str) either ‘all’ or ‘core’)

Returns:

None

opgee.graph.write_model_diagram(model, pathname, levels=0)¶

Create a network graph from an OPGEE Model.

Parameters:

model – (Model) a populated Model instance
pathname – (str) the pathname of the PNG file to create
levels – (int) the number of levels of the hierarchy to display. A value of zero implies no limit.

Returns:

None

`opgee.model`¶

class opgee.model.Model(name, attr_dict=None, table_updates=None)¶

const(name)¶

Return the value of a constant declared in tables/constants.csv

Parameters:: name – (str) name of constant
Returns:: (float with unit) value of constant

classmethod from_xml(elt, parent=None, analysis_names=None, field_names=None)¶

Instantiate an instance from an XML element

Parameters:

elt – (etree.Element) representing a <Model> element
parent – (None) this argument should be None for Model instances.
field_names – (list of str) the names of fields to include. Any other fields are ignored when building the model from the XML.

Returns:

(Model) instance populated from XML

partial_ci_values(analysis, field, nodes)¶

Compute partial CI for each node in nodes, skipping boundary nodes, since these have no emissions and serve only to identify the endpoint for CI calculation.

Parameters:

analysis – (opgee.Analysis)
field – (opgee.Field)
nodes – (list of Processes and/or Containers)

Returns:

A list of tuples of (item_name, partial_CI)

save_results(tuples, csvpath, by_process=False)¶

Save the carbon intensity (CI) results for the indicated (field, analysis) tuples to the indicated CSV pathname, csvpath. By default, results are written for top-level processes and aggregators. If by_process is True, the results are written out for all processes, ignoring aggregators.

Parameters:

tuples – (sequence of tuples of (analysis, field) instances)
by_process – (bool) if True, write results by process. If False, write results for top-level processes and aggregators only.

Returns:

none

`opgee.process`¶

class opgee.process.Aggregator(name, attr_dict=None, parent=None)¶

classmethod from_xml(elt, parent=None)¶

Instantiate an instance from an XML element

Parameters:

elt – (etree.Element) representing a <Aggregator> element
parent – (XmlInstantiable) the parent in the Model object hierarchy for the object created here

Returns:

(Aggregator) instance populated from XML

class opgee.process.Boundary(*args, **kwargs)¶

Used to define system boundaries in XML, e.g., <Process class=”Boundary” name=”Production”>

run(analysis)¶

This method implements the behavior required of the Process subclass, when the Process is enabled. Subclasses of Process must implement this method.

Parameters:: analysis – (Analysis) the Analysis used to retrieve global settings
Returns:: None

class opgee.process.IntermediateValues¶

Stores “interesting” intermediate values from processes for display in GUI.

get(name)¶

Return the record associated with name.

Parameters:: name – (str) the name of an intermediate value
Returns:: (pd.Series) the row in the DataFrame of intermediate values for this process.

class opgee.process.Process(name, attr_dict=None, parent=None, desc=None, cycle_start=False, impute_start=False, boundary=None)¶

The “leaf” node in the container/process hierarchy. Process is an abstract superclass: actual runnable Process instances must be of subclasses of Process, defined either in opgee/processes/*.py or in the user’s files, provided in the configuration file in the variable OPGEE.ClassPath.

Each Process subclass must implement the run and bypass methods, described below.

If a model contains process loops (cycles), one or more of the processes can call the method set_iteration_value() to store the value(s) of a designated variable(s) to be checked on each call to see if the change from the prior iteration is <= the value of Model attribute “maximum_change”. If so, an OpgeeIterationConverged exception is raised to terminate the run.

In addition to testing for convergence, a “visit” counter in each Process is incremented each time the process is run (or bypassed) and if the count >= the Model’s “maximum_iterations” attribute, OpgeeMaxIterationsReached is likewise raised. Whichever limit is reached first will cause iterations to stop. Between model runs, the method field.reset() is called for all processes to clear the visited counters and reset the iteration value to None.

See also OPGEE XML documentation

add_emission_rate(category, gas, rate)¶

Add to the stored rate of emissions for a single gas.

Parameters:

category – (str) one of the defined emissions categories
gas – (str) one of the defined emissions (values of Emissions.emissions)
rate – (float) the increment in rate in the Process’ flow units (e.g., mmbtu (LHV) of fuel burned)

Returns:

none

add_emission_rates(category, **kwargs)¶

Add emissions to those already stored, for of one or more gases, given as keyword arguments, e.g., add_emission_rates(CO2=100, CH4=30, N2O=6).

Parameters:

category – (str) one of the defined emissions categories
kwargs – (dict) the keyword arguments

Returns:

none

add_energy_rate(carrier, rate)¶

Set the rate of energy use for a single carrier.

Parameters:

carrier – (str) one of the defined energy carriers (values of Energy.carriers)
rate – (float) the rate of use (e.g., mmbtu/day (LHV) for all but electricity, which is in units of kWh/day.

Returns:

none

add_energy_rates(dictionary)¶

Add to the energy use rate for one or more carriers.

Parameters:: dictionary – (dict) the carriers and rates
Returns:: none

all_streams_ready(input_stream_contents)¶

Check if all the streams to self, from enabled processes containing input_stream_contents, are ready (i.e., not uninitialized)

Parameters:: input_stream_contents – (str) name of input steam contents
Returns:: (bool) whether all indicated streams are initialized

beyond_boundary()¶: If self is a boundary Process, return the list of processes beyond the boundary. The boundary Process must not be in a cycle.

classmethod check_iterator_convergence()¶

Check whether the current process is the last of all process iterator values to converge. stop when one converges but others have yet to do so.

Returns:: none.
Raises:: OpgeeIterationConverged – if all processes have converged.

find_input_stream(stream_type, raiseError=True) → Optional[Stream]¶

Find exactly one input stream connected to a downstream Process that produces the indicated stream_type, e.g., ‘crude oil’, ‘raw water’ and so on.

Parameters:

stream_type – (str) the generic type of stream a process can handle.
raiseError – (bool) whether to raise an error if no handlers of stream_type are found.

Returns:

(Streams or None)

Raises:

OpgeeException if exactly one process producing stream_type is not found and raiseError is True

find_input_streams(stream_type, combine=False, as_list=False, raiseError=True) → Union[Stream, list, dict]¶

Convenience method to call _find_streams_by_type with direction “input”

Parameters:

stream_type – (str) the generic type of stream a process can handle.
combine – (bool) whether to (thermodynamically) combine multiple Streams into a single one
as_list – (bool) return results as a list rather than as a dict
raiseError – (bool) whether to raise an error if no handlers of stream_type are found.

Returns:

(Stream, list or dict of Streams) depends on various keyword args

Raises:

OpgeeException if no processes handling stream_type are found and raiseError is True

find_output_stream(stream_type, raiseError=True) → Optional[Stream]¶

Find exactly one output stream connected to a downstream Process that consumes the indicated stream_type, e.g., ‘crude oil’, ‘raw water’ and so on.

Parameters:

stream_type – (str) the generic type of stream a process can handle.
raiseError – (bool) whether to raise an error if no handlers of stream_type are found.

Returns:

(Streams or None)

Raises:

OpgeeException if exactly one process consuming stream_type is not found and raiseError is True

find_output_streams(stream_type, combine=False, as_list=False, raiseError=True) → Union[Stream, list, dict]¶

Convenience method to call _find_streams_by_type with direction “output”

Parameters:

stream_type – (str) the generic type of stream a process can handle.
combine – (bool) whether to (thermodynamically) combine multiple Streams into a single one
as_list – (bool) return results as a list rather than as a dict
raiseError – (bool) whether to raise an error if no handlers of stream_type are found.

Returns:

(Stream, list or dict of Streams) depends on various keyword args

Raises:

OpgeeException if no processes handling stream_type are found and raiseError is True

find_stream(name, raiseError=False) → Stream¶

Convenience function to find a named stream from a Process instance by calling find_stream() on the enclosing Field instance.

Parameters:

name – (str) the name of the Stream to find
raiseError – (bool) whether to raise an error if the Stream is not found.

Returns:

(Stream or None) the requested stream, or None if not found and raiseError is False.

Raises:

OpgeeException if name is not found and raiseError is True

classmethod from_xml(elt, parent=None)¶

Instantiate an instance from an XML element

Parameters:

elt – (etree.Element) representing a <Process> element
parent – (opgee.Analysis) the Analysis containing the new Process

Returns:

(Process) instance populated from XML

get_compressor_and_well_loss_rate(inlet_stream)¶

Get the compressor and well loss rate for a given inlet stream.

Args:: inlet_stream: A Stream object representing the inlet stream to the system.
Returns:: A Quantity object representing the compressor and well loss rate for the given inlet stream.

This function calculates the compressor and well loss rate for a given inlet stream based on the properties of the gas field and the loss matrix average data. The compressor and well loss rate is calculated based on the volume flow rate of gas at STP for each injection well, and the corresponding loss rate values from the loss matrix average data. If the system contains a compressor, the compressor loss rate is returned, otherwise the well loss rate is returned. The result is returned as a Quantity object with units of “frac”.

get_emission_rates(analysis, procs_to_exclude=None)¶

Return the emission rates and the calculated GHG value. Uses the current choice of GWP values in the Analysis containing this process.

Parameters:: procs_to_exclude – ignored here, but provided for API consistency with Container class method of same name
Returns:: ((pandas.Series, float)) a tuple containing the emissions Series and the GHG value computed using the model’s current GWP settings.

get_energy_rates()¶: Return the energy consumption rates.

get_intermediate_results()¶

This method will be overridden in the water treatment subprocess

Returns:: A dictionary of energy and emission instances or None

get_net_imported_product()¶: Return the net imported product energy rate (water is mass rate) :return:

get_process_EF()¶

Lookup emission factor for this process to calculate combustion emissions. For user-defined processes not listed in the process_EF table, the Process subclass must implement this method to override the lookup.

Returns:: (float) a pandas series of emission factor for natural gas, upgrader proc.gas, NGL, diesel, residual fuel, pet.coke (unit = gGHG/mmBtu)

impute()¶

Called for Process instances upstream of Stream with exogenous input data, allowing those nodes to impute their own inputs from the output Stream.

Returns:: none

init_intermediate_results(names)¶

Parameters:: names –
Returns:

predecessors() → set¶

Return a Process’s immediate precedent Processes.

Returns:: (set of Process) the Processes that are the sources of Streams connected to process.

required_inputs()¶: Return the names of required input stream contents

required_outputs()¶: Return the names of required output stream contents

classmethod reset_all_iteration()¶

Reset the iteration value and counter in all iterating processes.

Returns:: none

run(analysis)¶

This method implements the behavior required of the Process subclass, when the Process is enabled. Subclasses of Process must implement this method.

Parameters:: analysis – (Analysis) the Analysis used to retrieve global settings
Returns:: None

run_if_enabled(analysis)¶

If the Process is enabled, run the process, otherwise do nothing.

Parameters:: analysis – (Analysis) the repository of analysis-specific settings
Returns:: None

set_gas_fugitives(stream, loss_rate) → Stream¶

initialize the gas fugitives stream, get loss rate, copy..

Parameters:

loss_rate –
stream –

Returns:

set_iteration_value(value)¶

Store the value of one or more variables used to determine when an iteration loop has stabilized. When set, if the absolute value of the change in each value is less than the model’s maximum_change, the run loop is terminated by throwing an OpgeeStopIteration exception.

Parameters:: value – (float, list/tuple of floats, pandas.Series) the values of designated ‘change’ variables to compare each iteration. If a list, tuple, or Series is used, all values contained therein must be within maximum_change of the previously stored value.
Returns:: none
Raises:: OpgeeIterationConverged if the change in value (versus the previously stored value) is less than the maximum_change attribute for the model. If a list/tuple/Series of floats is passed in value, all of the contained values must pass this test.

successors() → set¶

Return a Process’s immediately following Processes.

Returns:: (set of Process) the Processes that are the destinations of Streams connected to process.

sum_intermediate_results()¶

Sum intermediate energy and emission results

Returns:

validate_proc()¶: Optional method to be implemented by subclasses of Process. Processes failing validation should raise ModelValidationError(msg) with an explanatory message. Note that required inputs and outputs are handled separately in validate_streams.

validate_streams()¶

Verify that each Process is connected to all required input and output streams.

Returns:: none
Raises:: ModelValidationError – if any required input or output streams are missing.

within_boundary()¶: If self is a boundary Process, return the list of processes upstream of the boundary. The boundary Process must not be in a cycle.

class opgee.process.Reservoir(parent=None)¶

Reservoir represents natural resources such as oil and gas reservoirs, and water sources in the subsurface. Each Field object holds a single Reservoir instance.

run(analysis)¶

This method implements the behavior required of the Process subclass, when the Process is enabled. Subclasses of Process must implement this method.

Parameters:: analysis – (Analysis) the Analysis used to retrieve global settings
Returns:: None

opgee.process.run_corr_eqns(x1, x2, x3, x4, x5, coef_df)¶

Generalized function to run a quadratic correlation equation of 5 coefficients.

Parameters:

x1-x5 – (float) the coefficients
coef_df – (pandas.DataFrame) data values

Returns:

pandas.Series

`opgee.stream`¶

class opgee.stream.Stream(name, tp, parent=None, API=None, comp_matrix=None, src_name=None, dst_name=None, contents=None, impute=True)¶

The Stream class represent the flow rates of single substances or mingled combinations of co-flowing substances in any of the three states of matter (solid, liquid, or gas). Streams and stream components are specified in mass flow rates (e.g., Mg per day). The default set of substances is defined by Stream.component_names but can be extended by the user to include other substances, by setting the configuration file variable OPGEE.StreamComponents.

Streams are defined within the <Field> element and are stored in a Field instance. The Field class tracks all Stream instances in a dictionary keyed by Stream name.

`opgee.table_manager`¶

class opgee.table_manager.TableDef(basename, index_col=None, index_row=None, has_units=None, fillna=None)¶: Holds meta-data for built-in tables (CSV files loaded into pandas.DataFrames).

class opgee.table_manager.TableManager(updates=None)¶

The TableManager loads built-in CSV files into DataFrames and stores them in a dictionary keyed by the root name of the table. When adding CSV files to the opgee “tables” directory, a corresponding entry must be added in the TableManager class variable TableManager.table_defs, which holds instances of TableDef class.

Users can add external tables using the add_table method.

add_table(pathname, index_col=None, skiprows=0)¶

Add a CSV file external to OPGEE to the TableManager.

Parameters:

pathname – (str) the pathname of a CSV file
index_col – (str, int, iterable of str or int, False, or None) see doc for pandas.read_csv()
skiprows – (int) the number of rows to skip before the table begins.

Returns:

none

get_table(name, raiseError=True)¶

Retrieve a dataframe representing CSV data loaded by the TableManager

Parameters:

name – (str) the name of a table
raiseError – (bool) whether to raise an error (or just return None) if the table isn’t found.

Returns:

(pandas.DataFrame) the corresponding data

Raises:

OpgeeException if the name is unknown and raiseError is True.

`opgee.table_update`¶

class opgee.table_update.Cell(row, col, value)¶: Defines a replacement for a value provided in a built-in CSV file.

class opgee.table_update.TableUpdate(name, cells)¶: Supports user-defined updates to built-in CSV data.

OPGEE Core Classes¶

opgee.core¶

opgee.analysis¶

opgee.attributes¶

opgee.container¶

opgee.emissions¶

opgee.energy¶

opgee.field¶

opgee.graph¶

opgee.model¶

opgee.process¶

opgee.stream¶

opgee.table_manager¶

opgee.table_update¶

`opgee.core`¶

`opgee.analysis`¶

`opgee.attributes`¶

`opgee.container`¶

`opgee.emissions`¶

`opgee.energy`¶

`opgee.field`¶

`opgee.graph`¶

`opgee.model`¶

`opgee.process`¶

`opgee.stream`¶

`opgee.table_manager`¶

`opgee.table_update`¶