diff --git a/README.md b/README.md index 8554e4ffa..566db3d28 100644 --- a/README.md +++ b/README.md @@ -15,7 +15,7 @@ * [**Documentation**](https://equinor.github.io/subscript) * [**Installation**](#installation) * [**Usage**](#usage) -* [**Contribution**](https://equinor.github.io/subscript/contribution.html) +* [**Contributing**](https://equinor.github.io/subscript/contributing.html) --- @@ -38,10 +38,10 @@ Note that some of these utilities may depend upon commercial third-party software. -## Developing & Contribution +## Developing & Contributing All contributions are welcome. Please see the -[Contribution document](https://equinor.github.io/subscript/contribution.html) +[Contributing document](https://equinor.github.io/subscript/contributing.html) for more details and instructions for getting started. diff --git a/docs/conf.py b/docs/conf.py index a5776f4aa..f29c9b356 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -19,7 +19,7 @@ # -- Project information ----------------------------------------------------- project = "subscript" -copyright = "2020, Equinor" +copyright = "Equinor" author = "Equinor" import subscript # noqa @@ -47,6 +47,7 @@ # ones. extensions = [ "autoapi.sphinx", + "sphinx_copybutton", "sphinx.ext.autodoc", "sphinx.ext.autosummary", "sphinx.ext.inheritance_diagram", diff --git a/docs/contributing.rst b/docs/contributing.rst new file mode 100644 index 000000000..84d50c9e7 --- /dev/null +++ b/docs/contributing.rst @@ -0,0 +1,111 @@ +Contributing +============ + +Thanks for considering contributing to subscript! All contributions are +welcome. This document is meant to help you get started and contains some +guidelines that must be met before a contribution can be accepted. + + +Getting started +--------------- + +We recommend developing from a personal fork rather than branches on the +upstream repository. Create a fork from the repository and then clone it +to your machine: + +.. code-block:: console + + git clone git@github.com:/subscript + cd subscript + +Then add the upstream repository: + +.. code-block:: console + + git remote add upstream git@github.com:equinor/subscript + +After cloning, you need a Python virtual environment in which you install +subscript and its dependencies. If you develop on an Equinor computer you +should use ``komodoenv``; instructions for how to do this can be found +`here ` +(internal). Otherwise, set up a normal virtual environment. + +.. code-block:: console + + python3 -m venv venv-subscript + source venv-subscript/bin/activate # append ".csh" if c-shell + +and then upgrade and install the dependencies with ``pip``: + +.. code-block:: console + + pip install -U pip + pip install -e ".[tests,docs]" + +to install subscript in "edit"-mode together will all the dependencies for +subscript, its test suite, and documentation dependencies. + +A good start is to verify that all tests pass after having cloned the +repository, which you can do by running: + +.. code-block:: console + + pytest -n auto + +If you want to run the full test-suite within the Equinor Linux environment +you can invoke the test run in the following manner. This will include +running tests that rely upon a black oil simulation. + +.. code-block:: console + + pytest -n --flow-simulator="/project/res/x86_64_RH_7/bin/flowdaily" --eclipse-simulator="runeclipse" + + +Code style +---------- + +Before making a pull request you should verify that your changes will pass +the linting done in CI: + + .. code-block:: console + + isort --check-only --profile black src tests + black --check *.py src tests + flake8 src tests + mypy src/subscript + rstcheck -r docs + + +Documentation +------------- + +Ensure the documentation is up-to-date with your changes. You can build and +view the documentation like so: + + .. code-block:: console + + sphinx-build -b html docs build/docs/html + firefox build/docs/html/index.html + + +Repository conventions +---------------------- + +* Each tool has its own subdirectory under ``src/subscript``. +* Use ``pyproject.toml`` for installing endpoints that users should have in + their ``$PATH`` +* Use ``argparse``, and with a specific ``get_parser()`` function to facilitate + ``sphinx-argparse`` +* Always use the ``if __name__ = "__main__"`` idiom. Scripts should not start + if they are imported, this is to facilitate testing. +* There must be at least test code that directly test that the endpoint is + installed and that it does at least something to a standard input. Preferably + unit test code for isolated parts of the code as well. +* Docstrings on all functions. Docstrings can include RST formatting and will + be checked for compliance with sphinx on every pull request. Warnings from + sphinx must be fixed. +* For a new script, write a new file ``docs/scripts/scriptname.rst`` describing + the script, its usage, and examples. Use sphinx-argparse to document the + command line syntax. +* Type hinting is encouraged. If type hinting is included in the source, it has + to pass mypy. diff --git a/docs/contribution.rst b/docs/contribution.rst deleted file mode 100644 index aa3395456..000000000 --- a/docs/contribution.rst +++ /dev/null @@ -1,149 +0,0 @@ - -Contributing to subscript -========================= - -Getting started on Equinor Linux computers ------------------------------------------- - -On Equinor Linux computers, is is recommended to run with the Komodo -environment, which will provide an analogue to ``virtualenv`` for making a -virtual environment. - -Follow instructions on -https://fmu-docs.equinor.com/docs/komodo/equinor_komodo_usage.html for -activating a Komodo release, and perform the instructions for extending Komodo -in order a functioning ``pip`` tool. - -Getting started as a developer ------------------------------- - -The first thing to do, is to create a fork of subscript to your personal github -account. Go to https://github.com/equinor/subscript and click the "Fork" -button. - -Clone your fork to your local computer: - -.. code-block:: console - - git clone git@github.com:/subscript - cd subscript - -Then add the upstream repository: - -.. code-block:: console - - git remote add upstream git@github.com:equinor/subscript - -This requires a valid login setup with SSH keys for you github account, needed -for write access. - -After cloning, you need a Python virtual environment in which you install -subscript and its dependencies. If you develop on an Equinor computer you -should use `komodoenv` as outlined above, if not, you can create a new virtual -environment for subscript using the commands: - -.. code-block:: console - - python3 -m venv venv-subscript - source venv-subscript/bin/activate # append ".csh" if c-shell - -and then run ``pip`` : - -.. code-block:: console - - pip install -e ".[tests,docs]" - -to install subscript in "edit"-mode together will all the dependencies for -subscript, its test suite and documentation. - -A good start is to verify that all tests pass after having cloned the -repository, which you can do by running: - -.. code-block:: console - - pytest -n auto - - -Repository conventions ----------------------- - -* Each tool has its own subdirectory under ``src/subscript``. -* Use ``setup.py`` for installing endpoints that users should have in their ``$PATH`` -* Use ``argparse``, and with a specific ``get_parser()`` function to facilitate ``sphinx-argparse`` -* Always use the ``if __name__ = "__main__"`` idiom. Scripts should not start if they are - imported, this is to facilitate testing. -* There must be at least test code that directly test that the endpoint is installed and - that it does at least something to a standard input. Preferably unit test code for - isolated parts of the code as well. -* Docstrings on all functions. Docstrings can include RST formatting and will - be checked for compliance with sphinx on every pull request. Warnings from sphinx - must be fixed. -* For a new script, write a new file ``docs/scripts/scriptname.rst`` describing - the script. Use sphinx-argparse to document the command line syntax. -* Type hinting is encouraged. If type hinting is included in the source, it has to pass - mypy. - - -Maintenance responsibility --------------------------- - -* Equinor (PETEC Reservoir Toolbox) maintains the repository infrastructure, - monitors that automated tests pass on updated dependencies, and ensures - deploy to Komodo is active. -* Maintenance responsibility for each admitted script (response to bug reports - and adaptations to changes in dependencies) belongs to the Product Owner - in Equinor. -* Scripts/changes admitted from actors external to Equinor will be maintained - by Equinor. -* Unmaintained scripts that fail to pass tests will be removed. - -Open source ------------ - -Subscript is both open source and closed source. The twin repository -``subscript-internal`` holds similar infrastructure but with scripts that are -exempted from the Open Source requirement in TR1621. Internal or confidental -data should never be submitted to subscript. For each open script, there must -be accompanying public test data. - -Code style ----------- - -* PEP8 is the rule for naming of files, functions, classes, etc. Exception to - PEP8 is maximum width at 88 instead of PEP8's 79; as 88 is the ``black`` - default - -* Use the black formatter to format your code - - * ``pip install black`` - * ``black ``, must be done prior to any pull request. - -* Use flake8 code checker - - * ``pip install flake8`` - * ``flake8 src tests`` must pass before any pull request is accepted - * Exceptions are listed in ``setup.cfg`` - -* Use pylint to improve coding - - * ``pip install pylint`` - * Then run ``pylint src`` - * Deviations from default (strict) pylint are stored in ``.pylintrc`` at root level, - or as comments in the file e.g. ``# pylint: disable=broad-except``. - * Only use deviations when e.g. black and pylint are in conflict, or if conformity with - pylint would clearly make the code worse or not work at all. Do not use it to - increase pylint score. - -* Use "pre-commit" to enforce compliance before commit. Install using ``pip install pre-commit`` - and then run ``pre-commit install`` in the repository root. This will save you from - pushing code that will fail the code style tests required before merge. - -Building documentation ----------------------- - -Assuming the developer instructions above, run the following command to to -build the documentation for subscript:: - - sphinx-build -b html docs build/docs/html - -and then point your browser to the file ``build/docs/index.html``. diff --git a/docs/index.rst b/docs/index.rst index 3bd2aa6f0..e02d0afa3 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,8 +1,8 @@ ********* -Subscript +subscript ********* -Subscript is an Equinor collection of scripts used for subsurface reservoir +subscript is Equinor's collection of scripts used for subsurface reservoir modelling. .. include:: @@ -12,7 +12,8 @@ modelling. :glob: :maxdepth: 1 - contribution.rst + overview.rst + contributing.rst history.rst .. toctree:: diff --git a/docs/overview.rst b/docs/overview.rst new file mode 100644 index 000000000..62b77714b --- /dev/null +++ b/docs/overview.rst @@ -0,0 +1,43 @@ +Overview +======== + +Here is a summary of the scripts included in this package and how they can +be used. + +======================== === ================= ============ +Script CLI ERT Forward Model ERT Workflow +======================== === ================= ============ +bjobsusers ✅ ⛔️ ⛔️ +casegen_upcars ✅ ⛔️ ⛔️ +check_swatinit ✅ ✅ ⛔️ +co2_containment ✅ ⛔️ ⛔️ +convert_grid_format [*]_ ✅ ✅ ⛔️ +csv2ofmvol ✅ ✅ ⛔️ +csv_merge ✅ ⛔️ ✅ +csv_stack ✅ ✅ ✅ +eclcompress ✅ ✅ ⛔️ +ecldiff2roff ✅ ✅ ⛔️ +fmu_copy_revision ✅ ⛔️ ⛔️ +fmuobs ✅ ⛔️ ✅ +interp_relperm ✅ ✅ ⛔️ +merge_rft_ertobs ✅ ✅ ⛔️ +ofmvol2csv ✅ ✅ ⛔️ +pack_sim ✅ ⛔️ ⛔️ +params2csv ✅ ✅ ✅ +presentvalue ✅ ⛔️ ⛔️ +prtvol2csv ✅ ✅ ⛔️ +restartthinner ✅ ⛔️ ⛔️ +ri_wellmod ✅ ✅ ⛔️ +rmsecl_volumetrics ✅ ⛔️ ⛔️ +runrms ✅ ⛔️ ⛔️ +sector2fluxnum ✅ ⛔️ ⛔️ +summaryplot ✅ ⛔️ ⛔️ +sw_model_utilities ✅ ⛔️ ⛔️ +sunsch ✅ ✅ ⛔️ +vfp2csv ✅ ⛔️ ⛔️ +welltest_dpds ✅ ✅ ⛔️ +======================== === ================= ============ + +.. [*] ``convert_grid_format`` is the script that contains functionality + for the ``ECLGRID2ROFF``, ``ECLINIT2ROFF``, and ``ECLRST2ROFF`` forward + models. diff --git a/docs/usage.rst b/docs/usage.rst index a02240e5e..a91dfaecf 100644 --- a/docs/usage.rst +++ b/docs/usage.rst @@ -2,13 +2,13 @@ Using subscript =============== In Equinor, all subscript utilities are installed on all Linux -computers, and are available in every users path when Komodo is activated:: +computers and are available in every user's path when Komodo is activated:: source /prog/res/komodo/stable/enable.csh Remove the ``.csh`` from the line above if you are using *bash* (recommended). -For installation on non-Equinor computers, create and activate a Python3 +For installation on non-Equinor computers, create and activate a Python virtual environment and run:: - pip install git+https://github.com/equinor/subscript + pip install subscript diff --git a/pyproject.toml b/pyproject.toml index 036baa8db..c41e33545 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -80,6 +80,7 @@ docs = [ "sphinx<7", "sphinx-argparse", "sphinx-autodoc-typehints", + "sphinx-copybutton", "sphinx_rtd_theme", ] diff --git a/src/subscript/co2_containment/calculate.py b/src/subscript/co2_containment/calculate.py index f70c01d7f..9bcdb8814 100644 --- a/src/subscript/co2_containment/calculate.py +++ b/src/subscript/co2_containment/calculate.py @@ -54,14 +54,13 @@ def calculate_co2_containment( Args: co2_data (Co2Data): Information of the amount of CO2 at each cell in - each time step + each time step containment_polygon (Union[Polygon,Multipolygon]): The polygon that defines - the containment area + the containment area hazardous_polygon (Union[Polygon,Multipolygon]): The polygon that defines - the hazardous area + the hazardous area calc_type (CalculationType): Which calculation is to be performed - (mass / volume_extent / volume_actual / - volume_actual_simple) + (mass / volume_extent / volume_actual / volume_actual_simple) Returns: List[ContainedCo2]