Skip to content

Documentation #13

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
rjplevin wants to merge 4 commits into
base: main
Choose a base branch
from
Open

Documentation #13

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
0c4c2ab
Interim updates to documentation
rjplevin Mar 26, 2025
725f8be
More documentation additions.
rjplevin Mar 27, 2025
236e9b9
More doc updates
rjplevin Mar 27, 2025
96be8aa
Added documentation
rjplevin May 12, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
31 changes: 28 additions & 3 deletions docs/source/architecture.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -121,6 +121,8 @@ content names of which one or more must be present.
XML processing
----------------

.. note:: All XML elements are described further in :doc:`opgee-xml`.

AttrDef
~~~~~~~~~~
The XML element ``<AttrDef>`` defines metadata for an attribute of an OPGEE XML element.
Expand All @@ -134,13 +136,36 @@ is used for both validation and to generate the interactive user interface.

ProcessChoice and ProcessGroup
Copy link

@lloyd-rmi lloyd-rmi May 14, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should be consist on whether you always want to have <> brackets when referring to XML elements, or if you don't want to use them at all (or only use them the first time a new element is talked about/introduced). Right now it's not completely consistent.

Copy link
Collaborator Author

@rjplevin rjplevin May 14, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Good point! I will address.

Note, though, that there are many Python classes of the same name as the XML elements, so whether to include "" brackets depends on whether the element or class is being discussed.

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
A ``<ProcessGroup>`` describes a set of ``<ProcessRef>`` and ``<StreamRef>`` elements that
The ``<ProcessChoice>`` and ``<ProcessGroup>`` elements enable ``Fields`` to be used
as parameterized templates. A ``<ProcessGroup>`` encloses a set of ``<ProcessRef>``
and ``<StreamRef>`` elements that
can be enabled or disabled as a set. The ``<ProcessChoice>`` element encloses multiple
``<ProcessGroup>`` elements and selects among them based on the value of an attribute
``<ProcessGroup>`` elements and selects among them based on the value of a ``Field`` attribute
named in the ``<ProcessChoice>``, whose value must match the name of one of the enclosed
``<ProcessGroup>`` elements.
Comment on lines -137 to 145
Copy link

@mbarlow12 mbarlow12 May 15, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Would it be beneficial to add an example to show the 2 equivalent ways of creating the same input?

E.g.
Given the following in opgee.xml and attributes.xml:

<!-- opgee.xml or other template XML file -->
<Field name="my_template">
  <!-- ... other field elements -->
  <ProcessChoice name="gas_path">
    <ProcessGroup name="Minimal">
      <ProcessRef name="GasGathering" />
      <ProcessRef name="GasDehydration" />
      <StreamRef name="GasGathering => GasDehydration" />
      <StreamRef name="GasDehydration => GasPartition" />
    </ProcessGroup>
    <ProcessGroup name="Acid Wet Gas">
      <ProcessRef name="GasGathering" />
      <ProcessRef name="GasDehydration" />
      <ProcessRef name="AcidGasRemoval" />
      <ProcessRef name="Demethanizer" />
      <ProcessRef name="NGL" />
      <StreamRef name="GasGathering => GasDehydration" />
      <StreamRef name="GasDehydration => AcidGasRemoval" />
      <StreamRef name="AcidGasRemoval => Demethanizer" />
      <StreamRef name="Demethanizer => GasPartition" />
      <StreamRef name="Demethanizer => NGL" />
    </ProcessGroup>

    <ProcessGroup name="Acid Gas">
      <ProcessRef name="GasGathering" />
      <ProcessRef name="GasDehydration" />
      <ProcessRef name="AcidGasRemoval" />
      <StreamRef name="GasGathering => GasDehydration" />
      <StreamRef name="GasDehydration => AcidGasRemoval" />
      <StreamRef name="AcidGasRemoval => GasPartition" />
    </ProcessGroup>
  </ProcessChoice>
</Field>

<!-- attributes.xml -->
<ClassAttrs name="Field">
  <Options name="gas_path" default="Minimal">
    <Option desc="">None</Option>
    <Option desc="Dehydrator">Minimal</Option>
    <Option desc="Dehydrator + Amine Process">Acid Gas</Option>
    <Option desc="Dehydrator + Amine Process + Demethanizer">Acid Wet Gas</Option>
  </Options>
</ClassAttrs>

The 2 XML inputs below are equivalent.

<!-- using process choice attribute -->

<Field name="my_field" modifies="my_template">
  <A name="gas_path">Acid Gas</A>
</Field>

<!-- using explicit process/stream definitions -->

<Field name="my_field">
  <Process class="GasGathering"/>
  <Process class="GasDehydration"/>
  <Process class="AcidGasRemoval"/>
  <Stream src="GasGathering" dst="GasDehydration">
    <Contains>gas for gas dehydration</Contains>
  </Stream>
  <Stream src="GasDehydration" dst="AcidGasRemoval">
    <Contains>gas for AGR</Contains>
  </Stream>
  <Stream src="AcidGasRemoval" dst="GasPartition">
    <Contains>gas for gas partition</Contains>
  </Stream>
</Field>


All XML elements are described further in :doc:`opgee-xml`.
When the model is built, all the ``Streams`` and ``Processes`` identified by
``StreamRef`` and ``ProcessRef`` elements within the enclosed ``<ProcessGroup>>``
Copy link

@lloyd-rmi lloyd-rmi May 14, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Delete additional '>' around ProcessGroup

elements are disabled, then the ``Streams`` and ``Processes`` within the selected
``ProcessGroup`` are enabled. In this way, groups
of related ``Processes`` can be turned on and off.

The file ``etc/opgee.xml``, included in the OPGEE distribution,
defines a ``Field`` named ``template`` that provides the basis for common
oil and gas field configurations. The subcommand ``csv2xml`` allows a
user to define ``Fields`` using a small number of attributes by generating
Copy link

@lloyd-rmi lloyd-rmi May 14, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is there a limit on the # of attributes that can be used by the csv2xml script when creating fields?

Copy link
Collaborator Author

@rjplevin rjplevin May 14, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

No limit.

XML from the columns in the CSV file and combining these with the
``template`` field in ``etc/opgee.xml``. This system is used to generate XML
definitions for the 9,000 Fields used in testing OPGEE. See the schematic
figure below for an illustration of one such field.

.. figure:: images/gas_lifting.*
Copy link

@lloyd-rmi lloyd-rmi May 14, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't know if this is just an issue with how GitHub previews these files, but this currently doesn't show up correctly when reviewing on GitHub. I can see the image successfully in the images directory though, so it might just be a GitHub thing

Copy link

@mbarlow12 mbarlow12 May 15, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is a Sphinx/ReStrucutredText feature and goes beyond the basic Github rendering. You actually need to run sphinx-build to get the properly rendered content.

I just built the docs locally, and the image appears as expected.

:figclass: align-center

Schematic diagram of a "gas lifting field" from the "template" field
Copy link

@lloyd-rmi lloyd-rmi May 14, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is this text supposed to be tied to the figure in some way like as a sub-header? currently it just shows up as a "normal" paragraph in the preview after where the image is supposed to be.

Copy link
Collaborator Author

@rjplevin rjplevin May 14, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It appears as a caption because it's indented and "within" the ..figure. You can build the docs locally by changing to the OPGEEv4/docs directory and running "make html" (at least on a Mac or in Linux. There's also a make.bat there, which I assume works, but I've never used it.)

After building the docs, you can open docs/build/html/index.html to see the resulting files.

in ``etc/opgee.xml``, generated using OPGEE’s built-in “graph” command.
Rectangles indicate ``Process`` subclasses, and each arrow represents a
``Stream``. Labels on arrows show the declared ``Stream`` contents.


Assorted features
Expand Down
6 changes: 5 additions & 1 deletion docs/source/attributes.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,12 +3,16 @@ Attributes

In OPGEE the term "attributes" refers to a class of model parameters that are pre-defined
with metadata (attribute definitions) and are class-specific, i.e., they related to
Analysis, Field, Process, or subclasses of Process.
:py:class:`~opgee.analysis.Analysis`,
:py:class:`~opgee.field.Field`,
:py:class:`~opgee.process.Process`, or subclasses of ``Process``.

Attributes are central to the operation of both the "Smart Defaults" and Monte Carlo
simulation (MCS) subsystems. This page provides a brief overview of how attributes are
used in these subsystems. See the pages linked below for more information.

Attributes are defined by XML element, in the file ``etc/attributes.xml``.

See :obj:`opgee.attributes` for the Python API and more detailed documentation.

Attribute Definitions
Expand Down
28 changes: 18 additions & 10 deletions docs/source/calculation.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -25,15 +25,21 @@ The GHGs tracked by OPGEE processes are:
* N\ :sub:`2`\ O
* VOC (non-methane volatile organic compounds)

Per-process emissions are grouped into the following categories for reporting:

* Combustion
* Land-use
* Venting
* Flaring
* Fugitives
Emissions of carbon monoxide (CO), carbon dioxide (CO\ :sub:`2`), methane (CH\ :sub:`4`),
volatile organic compounds (VOC), and nitrous oxide (N\ :sub:`2`\ O) from each ``Process``
are tracked in units of Mg/day, subdivided into the following categories:

* Combustion – emissions resulting from fuel combustion for energy use
* Land-use – emissions resulting from land-use changes at the Field
* Venting – intentionally released gases
* Flaring – combustion of gases without energy use
* Fugitives – unintentional release of gases, e.g., from leaking valves or pipes
* Other


Emissions are stored in a pandas ``DataFrame`` in the :py:class:`Emissions <opgee.emissions>`
class in the file emissions.py.

Global Warming Potentials
~~~~~~~~~~~~~~~~~~~~~~~~~~~

Expand Down Expand Up @@ -107,18 +113,20 @@ The values associated with these choices are shown below.

Energy use
------------------

OPGEE tracks the consumption of energy by each process, including:
Each Process in OPGEE tracks its own energy consumption in units of million BTUs (mmbtu)
per day, subdivided into the following categories:

* Natural gas
* Upgrader proc. gas
* Natural gas liquids
* Crude oil
* Diesel
* Residual fuel
* Petroleum coke
* Petroleum coke (petcoke)
* Electricity

The structure is implemented as a pandas ``Series`` in the :py:class:`Energy <opgee.energy>` class in
the file energy.py.

System Boundaries
-------------------
Expand Down
8 changes: 5 additions & 3 deletions docs/source/conf.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,7 @@
# -- Project information -----------------------------------------------------

project = 'OPGEE'
copyright = '2022-2024, The Board of Trustees of the Leland Stanford Junior University'
copyright = '2022-2025, The Board of Trustees of the Leland Stanford Junior University'
author = 'Adam Brandt, Richard Plevin, Wennan Long'

# The short X.Y version.
Expand Down Expand Up @@ -78,5 +78,7 @@

# -- Options for intersphinx extension ---------------------------------------

# Example configuration for intersphinx: refer to the Python standard library.
intersphinx_mapping = {'python' : ('https://docs.python.org/3/', None)}
intersphinx_mapping = {
'python' : ('https://docs.python.org/3/', None),
# 'pint' : ('https://pint.readthedocs.io/', None),
}
Binary file added docs/source/images/gas_lifting.jpg
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Loading