From 87e7acfdfd165599e501d2822fe531e11c4a6d6c Mon Sep 17 00:00:00 2001 From: mferrera Date: Tue, 9 Jan 2024 14:40:46 +0100 Subject: [PATCH] DOC: Reorganize documentation --- CONTRIBUTING.md | 94 ++++++++---------- docs/authors.rst | 14 --- docs/conf.py | 4 +- docs/datamodels.rst | 5 +- docs/getting_started.rst | 56 +++++++++++ docs/index.rst | 35 ++++--- docs/installation.rst | 64 ++++-------- docs/readme.rst | 76 -------------- docs/{history.md => release_notes.md} | 12 ++- docs/{usage.rst => tutorial/examples.rst} | 24 ++--- .../examples_rms.rst} | 9 +- docs/{ => tutorial}/images/hybridgrid.png | Bin docs/tutorial/tutorial_index.rst | 13 +++ 13 files changed, 184 insertions(+), 222 deletions(-) delete mode 100644 docs/authors.rst create mode 100644 docs/getting_started.rst delete mode 100644 docs/readme.rst rename docs/{history.md => release_notes.md} (98%) rename docs/{usage.rst => tutorial/examples.rst} (92%) rename docs/{usextgeoroxar.rst => tutorial/examples_rms.rst} (98%) rename docs/{ => tutorial}/images/hybridgrid.png (100%) create mode 100644 docs/tutorial/tutorial_index.rst diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index c9eed1756..c6ad32af6 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,12 +1,10 @@ # Contributing Contributions are welcome and greatly appreciated! There are several ways to -contribute to `xtgeo`. - +contribute to XTGeo. ## Types of Contributions - ### Report Bugs Report bugs at @@ -14,30 +12,27 @@ Report bugs at If you are reporting a bug, please include: -* Your operating system name and version. -* Any details about your local setup that might be helpful in troubleshooting. -* Detailed steps to reproduce the bug. - +- Your operating system name and version. +- Any details about your local setup that might be helpful in troubleshooting. +- Detailed steps to reproduce the bug. ### Fix Bugs -Look through the Git issues for bugs. Anything tagged with "bug" -and "help wanted" is open to whoever wants to implement it. - +Look through the GitHub issues for bugs. Anything tagged with "bug", "help +wanted", or "good first issue" is open to whomever wants to fix it. ### Implement Features -Look through the Git issues for features. Anything tagged with "enhancement" -and "help wanted" is open to whoever wants to implement it. - +Look through the GitHub issues for features. Anything tagged with +"enhancement", "help wanted", or "good first issue" is open to whomever wants +to implement it. ### Write Documentation -Yes, `xtgeo` could always use more documentation, whether as part of the -official `xtgeo` docs, in docstrings, or even on the web in blog posts, +XTGeo could always use improved documentation, whether as part of the +official XTGeo docs, in docstrings, or even on the web in blog posts, articles, and such. - ### Submit Feedback The best way to send feedback is to file an issue at @@ -45,15 +40,14 @@ The best way to send feedback is to file an issue at If you are proposing a feature: -* Explain in detail how it would work. -* Keep the scope as narrow as possible, to make it easier to implement. - +- Explain in detail how it would work. +- Keep the scope as narrow as possible, to make it easier to implement. ## Get Started! -Ready to contribute? Here's how to set up `xtgeo` for local development. +Ready to contribute? Here's how to set up XTGeo for local development. -1. Fork the `xtgeo` repository from the Equinor repository to your GitHub +1. Fork the XTGeo repository from the Equinor repository to your GitHub user account. 2. Clone your fork locally: @@ -78,7 +72,7 @@ Ready to contribute? Here's how to set up `xtgeo` for local development. pip install -e ".[dev,docs]" # add -vv to see compilation output ``` -4. Install the test data one directory below your `xtgeo` directory and run +4. Install the test data one directory below your XTGeo directory and run the tests to ensure everything works: ```sh @@ -104,16 +98,16 @@ Ready to contribute? Here's how to set up `xtgeo` for local development. pytest tests ``` -7. If you want to edit the C/C++ contact the `xtgeo` authors for detailed - instructions. +7. If you want to contribute to the C/C++ code base contact the XTGeo authors + for detailed instructions. -8. Commit your changes - (see [Writing commit messages](#writing-commit-messages)) and push your +8. Commit your changes (see + [Writing commit messages](#writing-commit-messages)) and push your branch to GitHub: ```sh - git add . - git commit -m "ENH: Described changes made" + git add file1.py file2.py + git commit -m "ENH: Add some feature" git push origin name-of-your-bugfix-or-feature ``` @@ -131,7 +125,6 @@ sphinx-build -W -b html docs build/docs/html Then open `build/docs/html/index.html` in your browser. - ## Writing commit messages Commit messages should be clear and follow a few basic rules. Example: @@ -144,26 +137,26 @@ changes X, Y, Z which together completed feature ABC. With this change users can now do `vals = values.foo().bar()`. ``` -The first word of the commit message starts with a capitalized acronym -(options listed below) indicating what type of commit this is followed by a -brief description of the change. This line should strive to be less than or -equal to 50 characters. +The first word of the commit message starts with a capitalized acronym or +abbreviation. A list of these is available below. This prefixindicates what +type of commit this is and is followed by a brief description of the change. +This line should strive to be less than or equal to 50 characters. More explanation and context is often helpful to developers in the future. If this is the case you should add a blank link with a longer description giving some of these contextual details. This commit information can be as long as is needed but the individual lines shouldn't be longer than 72 characters. -See [Chris Beams hints on commit messages](https://chris.beams.io/posts/git-commit/) -for more expalanation of these guidelines. +See [Chris Beams How to Write a Git Commit Message](https://cbea.ms/git-commit/) +article for more explanation of these guidelines. Describing the motivation for a change, the nature of a bug for bug fixes or some details on what an enhancement does are also good to include in a commit message. Messages should be understandable without looking at the code changes. -A commit message like FIX: fix another one is an example of what not to do; +A commit message like `FIX: fix another one` is an example of what not to do; the reader has to go look for context elsewhere. -Standard acronyms to start the commit message with are: +Standard prefixes to start the commit message with are: ```text API: an (incompatible) API change (will be rare) @@ -183,11 +176,10 @@ TST: addition or modification of tests ### Type Hints -`xtgeo` requires the use of type annotations in all new feature +XTGeo requires the use of type annotations in all new feature developments, incorporating Python 3.10's enhanced syntax for type hints. This facilitates a more concise and readable style. - ### Style Guidelines - For Python versions prior to 3.10, include the following import for @@ -218,7 +210,6 @@ This facilitates a more concise and readable style. Note: These guidelines align with PEP 604 and are preferred for all new code submissions and when updating existing code. - ## Pull Request Guidelines Before you submit a pull request, check that it meets these guidelines: @@ -226,9 +217,9 @@ Before you submit a pull request, check that it meets these guidelines: 1. The pull request should include tests. 2. If the pull request adds functionality, the docs should be updated. Put - your new functionality into a function with a docstring, and add the - feature to the list in HISTORY.md. - + your new functionality into a function with a docstring and if it is a + public method make sure it displays helpful information in the + documentation. ## Tips @@ -239,9 +230,8 @@ Before you submit a pull request, check that it meets these guidelines: ``` - scikit-build-core offers some suggestions about building with editable - installs, see info here: - - https://scikit-build-core.readthedocs.io/en/latest/configuration.html#editable-installs + installs, see info + [here](https://scikit-build-core.readthedocs.io/en/latest/configuration.html#editable-installs) ## Working with RMS python @@ -250,12 +240,12 @@ The following is a special recipe when working with RMS' Python version, and it is targeted to Equinor usage using bash shell in Linux: ```sh -unset PYTHONPATH # to avoid potential issues # activate RMS python, e.g. RMS version 13.1.2 source /prog/res/roxapi/aux/roxenvbash 13.1.2 -# make a virtual env (once): -python -m venv ~/venv/py38_rms13.1.2 +# Make a venv with the libraries included by RMS +python -m venv ~/venv/py38_rms13.1.2 --system-site-packages source ~/venv/py38_rms13.1.2/bin/activate +unset PYTHONPATH # to avoid potential issues python -m pip install -U pip pip install -e ".[dev]" pytest @@ -264,7 +254,7 @@ pytest Now you have an editable install in your virtual environment that can be ran in RMS while testing. Hence open rms with ``rms`` command (not ``runrms``). -Inside RMS you can open a Python dialog and run your version of `xtgeo`. Theoretically, +Inside RMS you can open a Python dialog and run your version of XTGeo. Theoretically, you could now do changes in your editable install and RMS should see them. However, RMS will not load libraries updates once loaded, and ``importlib.reload`` will not help very much. One safe alternative is of course to close and @@ -285,8 +275,6 @@ import xtgeo grd = xgeo.grid_from_roxar(project, "Geogrid") ``` -This will work if you change python code in `xtgeo`. If you change C code in `xtgeo`, then +This will work if you change python code in XTGeo. If you change C code in XTGeo, then this hack will not work. The only solution is to close and re-open RMS everytime the C code is compiled. - - diff --git a/docs/authors.rst b/docs/authors.rst deleted file mode 100644 index e877a7890..000000000 --- a/docs/authors.rst +++ /dev/null @@ -1,14 +0,0 @@ -======= -Credits -======= - -Development Lead ----------------- - -* Dr. Jan C. Rivenæs, Equinor R&T - -Other contacts --------------- - -* Equinor SIB, Bergen -* Equinor R&T, Bergen diff --git a/docs/conf.py b/docs/conf.py index e07aa9837..7798a6f98 100755 --- a/docs/conf.py +++ b/docs/conf.py @@ -12,11 +12,11 @@ extensions = [ "autoclasstoc", "myst_parser", + "sphinx.ext.autodoc", + "sphinx.ext.autosummary", "sphinx.ext.napoleon", "sphinx.ext.viewcode", "sphinx.ext.mathjax", - "sphinx.ext.autosummary", - "sphinx.ext.autodoc", "sphinx_toolbox.more_autosummary", "sphinx_autodoc_typehints", ] diff --git a/docs/datamodels.rst b/docs/datamodels.rst index 21f5f94a1..270bb2168 100644 --- a/docs/datamodels.rst +++ b/docs/datamodels.rst @@ -1,6 +1,5 @@ -================================= -XTGeo data models and i/o formats -================================= +Data model and formats +====================== Here is a description of the internal datamodels used for various datatypes in XTGeo, and the input/output formats that are supported in the current version. diff --git a/docs/getting_started.rst b/docs/getting_started.rst new file mode 100644 index 000000000..836141119 --- /dev/null +++ b/docs/getting_started.rst @@ -0,0 +1,56 @@ +Getting started +=============== + +.. code-block:: python + + import xtgeo + +A first step is often to import some object from file. Here we create +an XTGeo :class:`xtgeo.RegularSurface` with the +:func:`xtgeo.surface_from_file` function. In this case it defaults to loading +the file as an IRAP binary file. + +.. code-block:: python + + mysurf = xtgeo.surface_from_file("myfile.gri") + +Having an existing file to load from is not required to create +XTGeo objects, in most cases. They may also be created with directly with +Python. + +.. code-block:: python + + mysurf = xtgeo.RegularSurface( + ncol=30, nrow=50, xori=1234.5, yori=4321.0, xinc=30.0, yinc=50.0, + rotation=30.0, values=vals, yflip=1, + ) + +The :class:`xtgeo.RegularSurface` class provides many methods to +retrieve information about the data contained in this object. Here we print +the mean of the values it contains; where ``values`` is a 2D masked numpy array. + +.. code-block:: python + + print(f"Mean is {mysurf.values.mean()}") + +Because values are stored internally as numpy arrays they can also be operated +on as you would any numpy array. + +.. code-block:: python + + mysurface.values[mysurface.values < 2000] = 2000 + +XTGeo also allows data to be operated on as a Pandas dataframe. A robust set +of convenience methods are given in XTGeo class objects for the operations +common to reservoir modelling. + +Once done you can save and export the modified file. XTGeo has support for +importing and exporting the most common file formats. + +.. code-block:: python + + mysurface.to_file("newfile.gri") + +XTGeo has many more capabilities beyond basic value manipulation. For more, +check out the examples in the +:doc:`Tutorial section `. diff --git a/docs/index.rst b/docs/index.rst index c1a8287f8..b8e577457 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,25 +1,36 @@ -Welcome to XTGeo's documentation! -================================= +Welcome to XTGeo's documentation +================================ .. figure:: images/xtgeo-logo.png - :alt: Logo - :width: 300 - :align: center + :alt: Logo + :width: 300 + :align: center + +XTGeo is a Python library with a C/C++ backend for efficient manipulation of +files and objects used in subsurface reservoir modelling. Typical users are +geoscientists and reservoir engineers working with reservoir modelling, +particularly with the geomodelling software RMS. + +XTGeo is developed and maintained by `Equinor `_. + +The repository is hosted on `GitHub `_. -Contents --------- .. toctree:: :maxdepth: 1 + :caption: About - history - readme installation contributing + release_notes + +.. toctree:: + :maxdepth: 1 + :caption: User guide + + getting_started + tutorial/tutorial_index datamodels - usage - usextgeoroxar xtgeo_4_migration - authors apireference Indices and tables diff --git a/docs/installation.rst b/docs/installation.rst index 4bff1c726..156077292 100644 --- a/docs/installation.rst +++ b/docs/installation.rst @@ -1,35 +1,25 @@ .. highlight:: shell -============ Installation ============ +XTGeo is a cross-platform library written in Python 3. + From pip -------- -For a selection of platforms (Linux/Windows/MacOS; all 64bit) and Python versions: +For a selection of platforms (Linux/Windows/MacOS; all 64bit). .. code-block:: console $ pip install xtgeo -Stable release in Equinor -------------------------- - -Within Equinor, the stable release is pre-installed, so all you have -to do is: - -.. code-block:: python - - import xtgeo - - -From github +From GitHub ------------ -You will need ``swig`` (version 3 or later) installed, in addition to a C -compiler (see below). +A C and C++ compiler are required to ``pip install`` directly from +the GitHub repository. .. code-block:: console @@ -39,13 +29,14 @@ compiler (see below). From downloaded sources ----------------------- -You will need `swig`_ (version 3 or later) installed, in addition to a C compiler. -Tested compilers are: +A C and C++ compiler are required to build XTGeo from source. -* gcc on Linux (Version 4 and later) +* gcc/g++ on Linux (Version 4 and later), or clang/clang++ +* clang/clang++ on macOS * Visual studio 2015 and 2017 on Windows -The sources for XTGeo can be downloaded from the `Equinor Github repo`_. +The sources for XTGeo can be downloaded from the repository on +`GitHub `_. You can either clone the public repository: @@ -55,34 +46,23 @@ You can either clone the public repository: Also you will need test data at the same folder level as the source: -.. code-block:: console - $ git clone git@github.com:equinor/xtgeo-testdata +Modifying and testing XTGeo +--------------------------- -Hence folder structure may look like +If you wish to make changes to the code or run the tests you can find +instructions and tips for how to do so in the +:doc:`Contributing document `. -.. code-block:: console - - /some/path/to/xtgeo - /some/path/to/xtgeo-testdata - -For required python packages, see the pyproject.toml file in the root folder. - -Once you have a copy of the source, and you have a `virtual environment`_, -then always run tests (run first compile and install with ``pip install .``): - -.. code-block:: console - $ pytest +Within Equinor +-------------- -Next you can install it with: +Within Equinor the stable release is pre-installed so all you have +to do is: -.. code-block:: console +.. code-block:: python - $ pip install . + import xtgeo -.. _Equinor Github repo: https://github.com/equinor/xtgeo -.. _virtual environment: http://docs.python-guide.org/en/latest/dev/virtualenvs/ -.. _manual install of Shapely: https://towardsdatascience.com/install-shapely-on-windows-72b6581bb46c -.. _swig: http://swig.org diff --git a/docs/readme.rst b/docs/readme.rst deleted file mode 100644 index aacf412db..000000000 --- a/docs/readme.rst +++ /dev/null @@ -1,76 +0,0 @@ - -Introduction -============ - -XTGeo is a `LGPL`_ licensed Python library with C backend to support -manipulation of (oil industry) subsurface reservoir modelling. Typical -users are geoscientist and reservoir engineers working with reservoir -modelling. - - -XTGeo main environment is as stand-alone Python script or notebook, but can -*optionally* be ran inside `RMS`_'s python. XTGeo is developed in `Equinor`_. - -Feature summary ---------------- - -- Python 3.8+ (Linux, Windows and MacOS). -- Focus on high speed, using `numpy`_ and `pandas`_ with C backend -- Regular surfaces, i.e. 2D maps with regular sampling and rotation -- 3D grids (corner-point), supporting several formats such as RMS and - Eclipse -- Support of seismic cubes, using `segyio`_ as backend for SEGY format -- Support of well data, line and polygons (still somewhat immature) -- Operations between the data types listed above; e.g. slice a surface - with a seismic cube -- Integration to ROXAR API python for several data types is supported - (see note later) - -Quick Installation ------------------- - -PYPI installation is enabled for all supported platforms: - -.. code:: bash - - pip install xtgeo - -For detailed installation instructions (implies C compiling), see -:doc:`installation`. - - -Getting started ---------------- - -.. code:: python - - import xtgeo - - # create an instance of a surface, read from file - mysurf = xtgeo.surface_from_file("myfile.gri") # Irap binary as default - - print(f"Mean is {mysurf.values.mean()}") - - # change date so all values less than 2000 becomes 2000 - # The values attribute gives the Numpy array - - mysurface.values[mysurface.values < 2000] = 2000 - - # export the modified surface: - mysurface.to_file("newfile.gri") - -Note on RMS Roxar API integration ---------------------------------- - -The following applies to the part of the XTGeo API that is connected to -Roxar API (RMS): - -*RMS is neither an open source software nor a free software and any use of it needs -a software license agreement in place.* - -.. _segyio: https://github.com/equinor/segyio -.. _Equinor: https://equinor.com -.. _pandas: https://pandas.pydata.org/ -.. _numpy: https://numpy.org/ -.. _LGPL: https://en.wikipedia.org/wiki/GNU_Lesser_General_Public_License -.. _RMS: https://www.emerson.com/no-no/automation/operations-business-management/reservoir-management-software diff --git a/docs/history.md b/docs/release_notes.md similarity index 98% rename from docs/history.md rename to docs/release_notes.md index 9fa41e7ec..40d1e59bc 100644 --- a/docs/history.md +++ b/docs/release_notes.md @@ -1,6 +1,12 @@ # Release notes -For version 2.21 and later, see https://github.com/equinor/xtgeo/releases ! +Go to the +[XTGeo GitHub releases page](https://github.com/equinor/xtgeo/releases) +to see new releases and their notes. + +This page contains releaes notes for XTGeo versions 2.21 and older and is kept +for preservation reasons. + ## Version 2.20 @@ -119,14 +125,14 @@ For version 2.21 and later, see https://github.com/equinor/xtgeo/releases ! - The names setter of `GridProperties` has been deprecated as its behavior was inconsistent. -# New features +### New features - Grid can now be imported from FEGRID (text formatted EGRID) files. #602 - Introduced unit parameter to Grid #602 - Grid get_dx and get_dy introduced as replacement for get_dxdy. #624 - Added explicit close function to plots. #632 -## Bugfixes +### Bugfixes - Fixed conversion of grid mapaxes when grid is already relative to map. #602 - Fixed inconsistent gridproperty initialization #659 diff --git a/docs/usage.rst b/docs/tutorial/examples.rst similarity index 92% rename from docs/usage.rst rename to docs/tutorial/examples.rst index 8e33fbb79..10a54f288 100644 --- a/docs/usage.rst +++ b/docs/tutorial/examples.rst @@ -1,15 +1,15 @@ .. highlight:: python -============================== -Examples in standalone scripts -============================== + +Examples +======== .. comments These examples are ran in Jupyter notebook... XTGeo is Python library to work with surfaces, grids, cubes, wells, etc, -possibly in combinations. It is easy to make small user scripts that runs from -the command line in Linux, Mac and Windows. +possibly in combination. It is easy to make small user scripts that run from +the command line in Linux, macOS, and Windows. ------------------ Surface operations @@ -72,13 +72,13 @@ of these properties can be changed, which actually changes the map Sample a surface from a 3D grid ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -.. literalinclude:: ../examples/surface_slice_grid3d.py +.. literalinclude:: ../../examples/surface_slice_grid3d.py :language: python Sample a surface or a window attribute from a cube ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -.. literalinclude:: ../examples/surface_slice_cube.py +.. literalinclude:: ../../examples/surface_slice_cube.py :language: python --------------- @@ -230,14 +230,14 @@ The root mean scquare (rms) value over a surface, +- 10 units Crop a 3D grid with properties ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -.. literalinclude:: ../examples/grid3d_crop.py +.. literalinclude:: ../../examples/grid3d_crop.py :language: python Extract Pandas dataframe from 3D grid and props ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -.. literalinclude:: ../examples/grid3d_get_df.py +.. literalinclude:: ../../examples/grid3d_get_df.py :language: python @@ -248,7 +248,7 @@ In this example, how to extract Mean ans Stddev from some geo properties, filtered on facies. An RMS inside version is also shown. -.. literalinclude:: ../examples/grid3d_properties_qc.py +.. literalinclude:: ../../examples/grid3d_properties_qc.py :language: python @@ -258,7 +258,7 @@ Compute a grid property average across realisations In this example, a technique that keeps memory usage under control when computing averages is also presented. -.. literalinclude:: ../examples/grid3d_compute_stats.py +.. literalinclude:: ../../examples/grid3d_compute_stats.py :language: python Make a CSV file from Eclipse INIT data (aka ERT ECL) @@ -268,5 +268,5 @@ Example on how to create a CSV file from all INIT properties. Example is for Eclipse format, but shall work also with ROFF input. -.. literalinclude:: ../examples/grid3d_print_init_csv.py +.. literalinclude:: ../../examples/grid3d_print_init_csv.py :language: python diff --git a/docs/usextgeoroxar.rst b/docs/tutorial/examples_rms.rst similarity index 98% rename from docs/usextgeoroxar.rst rename to docs/tutorial/examples_rms.rst index c1a42d5ae..78a06b068 100644 --- a/docs/usextgeoroxar.rst +++ b/docs/tutorial/examples_rms.rst @@ -1,12 +1,11 @@ .. highlight:: python -========================== -Examples on use inside RMS -========================== +Examples inside RMS +=================== -.. _RMS: https://www.emerson.com/no-no/automation/operations-business-management/reservoir-management-software +.. _RMS: https://www.aspentech.com/en/products/sse/aspen-rms -RMS_ is a licensed proprietary modeling software developed by Emerson. +RMS_ is a licensed proprietary modeling software developed by AspenTech. From version 10 it has its own python engine integrated, and XTGeo is designed to work inside this environment. The integration will be continuously improved. diff --git a/docs/images/hybridgrid.png b/docs/tutorial/images/hybridgrid.png similarity index 100% rename from docs/images/hybridgrid.png rename to docs/tutorial/images/hybridgrid.png diff --git a/docs/tutorial/tutorial_index.rst b/docs/tutorial/tutorial_index.rst new file mode 100644 index 000000000..873e47de7 --- /dev/null +++ b/docs/tutorial/tutorial_index.rst @@ -0,0 +1,13 @@ +Tutorial +======== + +These tutorials and examples are a work in progress. The code used in these +examples can be found as Python files in the +`examples directory in the GitHub repository `_. + +.. toctree:: + :maxdepth: 1 + :caption: Tutorials + + examples + examples_rms