Skip to content

Commit e4a756e

Browse files
csshermancssherman
authored
Merge pull request #1 from GEOS-DEV/feature/sherman/migrateDocs
Migrating python tool docs
2 parents 958244e + b861b02 commit e4a756e

File tree

10 files changed

+540
-0
lines changed

10 files changed

+540
-0
lines changed

‎docs/_static/theme_overrides.css‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
/* override table width restrictions */
2+
@media screen and (min-width: 767px) {
3+
4+
.wy-table-responsive table td {
5+
/* !important prevents the common CSS stylesheets from overriding
6+
this as on RTD they are loaded after this stylesheet */
7+
white-space: normal !important;
8+
}
9+
10+
.wy-table-responsive {
11+
overflow: visible !important;
12+
}
13+
14+
.wy-nav-content {
15+
max-width: 1200px !important;
16+
}
17+
}

‎docs/conf.py‎

Lines changed: 115 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,115 @@
1+
# -*- coding: utf-8 -*-
2+
#
3+
# Configuration file for the Sphinx documentation builder.
4+
#
5+
# This file does only contain a selection of the most common options. For a
6+
# full list see the documentation:
7+
# http://www.sphinx-doc.org/en/master/config
8+
9+
# -- Path setup --------------------------------------------------------------
10+
11+
# If extensions (or modules to document with autodoc) are in another directory,
12+
# add these directories to sys.path here. If the directory is relative to the
13+
# documentation root, use os.path.abspath to make it absolute, like shown here.
14+
#
15+
import os
16+
import sys
17+
import shutil
18+
19+
# Add python modules to be documented
20+
python_root = '..'
21+
python_modules = ('geosx_mesh_tools_package',
22+
'geosx_xml_tools_package',
23+
'geosx_mesh_doctor',
24+
'hdf5_wrapper_package',
25+
'pygeosx_tools_package',
26+
'timehistory_package')
27+
for m in python_modules:
28+
sys.path.insert(0, os.path.abspath(os.path.join(python_root, m)))
29+
30+
31+
# -- Project information -----------------------------------------------------
32+
33+
project = u'GEOS Python Packages'
34+
copyright = u'2018-2021 Lawrence Livermore National Security, The Board of Trustees of the Leland Stanford Junior University, TotalEnergies, and GEOSX Contributors.'
35+
author = u'GEOS Contributors'
36+
37+
# The short X.Y version
38+
version = u''
39+
# The full version, including alpha/beta/rc tags
40+
release = u''
41+
42+
43+
# -- General configuration ---------------------------------------------------
44+
45+
# If your documentation needs a minimal Sphinx version, state it here.
46+
#
47+
# needs_sphinx = '1.0'
48+
49+
# Add any Sphinx extension module names here, as strings. They can be
50+
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
51+
# ones.
52+
extensions = [
53+
'sphinx_design',
54+
'sphinx.ext.todo',
55+
'sphinx.ext.autodoc',
56+
'sphinx.ext.doctest',
57+
'sphinx.ext.imgmath',
58+
'sphinxarg.ext',
59+
'sphinx.ext.napoleon',
60+
'sphinxcontrib.programoutput'
61+
]
62+
63+
64+
autodoc_mock_imports = ["pygeosx", "pylvarray", "meshio", "lxml", "mpi4py", "h5py"]
65+
66+
# The suffix(es) of source filenames.
67+
# You can specify multiple suffix as a list of string:
68+
#
69+
# source_suffix = ['.rst', '.md']
70+
source_suffix = '.rst'
71+
72+
# The master toctree document.
73+
master_doc = 'index'
74+
75+
# The language for content autogenerated by Sphinx. Refer to documentation
76+
# for a list of supported languages.
77+
#
78+
# This is also used if you do content translation via gettext catalogs.
79+
# Usually you set "language" from the command line for these cases.
80+
language = 'en'
81+
82+
# List of patterns, relative to source directory, that match files and
83+
# directories to ignore when looking for source files.
84+
# This pattern also affects html_static_path and html_extra_path .
85+
exclude_patterns = [u'_build', 'Thumbs.db', '.DS_Store', 'cmake/*']
86+
87+
todo_include_todos = True
88+
89+
# The name of the Pygments (syntax highlighting) style to use.
90+
pygments_style = 'sphinx'
91+
92+
93+
# -- Theme options ----------------------------------------------
94+
extensions += [
95+
'sphinx_rtd_theme',
96+
]
97+
98+
html_theme = "sphinx_rtd_theme"
99+
100+
html_theme_options = {
101+
'navigation_depth': -1,
102+
'collapse_navigation': False
103+
}
104+
105+
html_static_path = ['./_static']
106+
107+
html_css_files = [
108+
'theme_overrides.css',
109+
]
110+
111+
112+
# -- Options for HTMLHelp output ---------------------------------------------
113+
# Output file base name for HTML help builder.
114+
htmlhelp_basename = 'geosPythonPackagesDoc'
115+

‎docs/geosx_mesh_tools.rst‎

Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
1+
2+
GEOS Mesh Tools
3+
--------------------------
4+
5+
The `geosx_mesh_tools` python package includes tools for converting meshes from common formats (abaqus, etc.) to those that can be read by GEOS (gmsh, vtk).
6+
See :ref:`PythonToolsSetup` for details on setup instructions, and `External Mesh Guidelines <https://geosx-geosx.readthedocs-hosted.com/en/latest/coreComponents/mesh/docs/Mesh.html#using-an-external-mesh>`_ for a detailed description of how to use external meshes in GEOS.
7+
The available console scripts for this package and its API are described below.
8+
9+
10+
convert_abaqus
11+
^^^^^^^^^^^^^^
12+
13+
Compile an xml file with advanced features into a single file that can be read by GEOS.
14+
15+
.. argparse::
16+
:module: geosx_mesh_tools.main
17+
:func: build_abaqus_converter_input_parser
18+
:prog: convert_abaqus
19+
20+
21+
.. note::
22+
For vtk format meshes, the user also needs to determine the region ID numbers and names of nodesets to import into GEOS.
23+
The following shows how these could look in an input XML file for a mesh with three regions (*REGIONA*, *REGIONB*, and *REGIONC*) and six nodesets (*xneg*, *xpos*, *yneg*, *ypos*, *zneg*, and *zpos*):
24+
25+
26+
.. code-block:: xml
27+
28+
<Problem>
29+
<Mesh>
30+
<VTKMesh
31+
name="external_mesh"
32+
file="mesh.vtu"
33+
regionAttribute="REGIONA-REGIONB-REGIONC"
34+
nodesetNames="{ xneg, xpos, yneg, ypos, zneg, zpos }"/>
35+
</Mesh>
36+
37+
<ElementRegions>
38+
<CellElementRegion
39+
name="ALL"
40+
cellBlocks="{ 0_tetrahedra, 1_tetrahedra, 2_tetrahedra }"
41+
materialList="{ water, porousRock }"
42+
meshBody="external_mesh"/>
43+
</ElementRegions>
44+
</Problem>
45+
46+
47+
API
48+
^^^
49+
50+
.. automodule:: geosx_mesh_tools.abaqus_converter
51+
:members:

‎docs/geosx_xml_tools.rst‎

Lines changed: 82 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,82 @@
1+
2+
.. _XMLToolsPackage:
3+
4+
GEOS XML Tools
5+
--------------------------
6+
7+
The `geosx_xml_tools` python package adds a set of advanced features to the GEOS xml format: units, parameters, and symbolic expressions.
8+
See :ref:`PythonToolsSetup` for details on setup instructions, and `Advanced XML Features <https://geosx-geosx.readthedocs-hosted.com/en/latest/coreComponents/fileIO/doc/InputXMLFiles.html#advanced-xml-features>`_ for a detailed description of the input format.
9+
The available console scripts for this package and its API are described below.
10+
11+
12+
convert_abaqus
13+
^^^^^^^^^^^^^^
14+
15+
Convert an abaqus format mesh file to gmsh or vtk format.
16+
17+
.. argparse::
18+
:module: geosx_xml_tools.command_line_parsers
19+
:func: build_preprocessor_input_parser
20+
:prog: preprocess_xml
21+
22+
23+
format_xml
24+
^^^^^^^^^^^^^^
25+
26+
Formats an xml file.
27+
28+
.. argparse::
29+
:module: geosx_xml_tools.command_line_parsers
30+
:func: build_xml_formatter_input_parser
31+
:prog: format_xml
32+
33+
34+
check_xml_attribute_coverage
35+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
36+
37+
Checks xml attribute coverage for files in the GEOS repository.
38+
39+
.. argparse::
40+
:module: geosx_xml_tools.command_line_parsers
41+
:func: build_attribute_coverage_input_parser
42+
:prog: check_xml_attribute_coverage
43+
44+
45+
check_xml_redundancy
46+
^^^^^^^^^^^^^^^^^^^^^^^^^^^
47+
48+
Checks for redundant attribute definitions in an xml file, such as those that duplicate the default value.
49+
50+
.. argparse::
51+
:module: geosx_xml_tools.command_line_parsers
52+
:func: build_xml_redundancy_input_parser
53+
:prog: check_xml_redundancy
54+
55+
56+
API
57+
^^^
58+
59+
.. automodule:: geosx_xml_tools.main
60+
:members:
61+
62+
.. automodule:: geosx_xml_tools.xml_processor
63+
:members:
64+
65+
.. automodule:: geosx_xml_tools.xml_formatter
66+
:members:
67+
68+
.. automodule:: geosx_xml_tools.unit_manager
69+
:members:
70+
71+
.. automodule:: geosx_xml_tools.regex_tools
72+
:members:
73+
74+
.. automodule:: geosx_xml_tools.xml_redundancy_check
75+
:members:
76+
77+
.. automodule:: geosx_xml_tools.attribute_coverage
78+
:members:
79+
80+
.. automodule:: geosx_xml_tools.table_generator
81+
:members:
82+

‎docs/hdf5_wrapper.rst‎

Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,60 @@
1+
2+
HDF5 Wrapper
3+
--------------------------
4+
5+
The `hdf5_wrapper` python package adds a wrapper to `h5py` that greatly simplifies reading/writing to/from hdf5-format files.
6+
7+
8+
Usage
9+
^^^^^^^
10+
11+
Once loaded, the contents of a file can be navigated in the same way as a native python dictionary.
12+
13+
.. code-block:: python
14+
15+
import hdf5_wrapper
16+
17+
data = hdf5_wrapper.hdf5_wrapper('data.hdf5')
18+
19+
test = data['test']
20+
for k, v in data.items():
21+
print('key: %s, value: %s' % (k, str(v)))
22+
23+
24+
If the user indicates that a file should be opened in write-mode (`w`) or read/write-mode (`a`), then the file can be created or modified.
25+
Note: for these changes to be written to the disk, the wrapper may need to be closed or deleted.
26+
27+
.. code-block:: python
28+
29+
import hdf5_wrapper
30+
import numpy as np
31+
32+
data = hdf5_wrapper.hdf5_wrapper('data.hdf5', mode='w')
33+
data['string'] = 'string'
34+
data['integer'] = 123
35+
data['array'] = np.random.randn(3, 4, 5)
36+
data['child'] = {'float': 1.234}
37+
38+
39+
Existing dictionaries can be placed on the current level:
40+
41+
.. code-block:: python
42+
43+
existing_dict = {'some': 'value'}
44+
data.insert(existing_dict)
45+
46+
47+
And external hdf5 format files can be linked together:
48+
49+
.. code-block:: python
50+
51+
for k in ['child_a', 'child_b']:
52+
data.link(k, '%s.hdf5' % (k))
53+
54+
55+
56+
API
57+
^^^^^
58+
59+
.. automodule:: hdf5_wrapper.wrapper
60+
:members:

‎docs/index.rst‎

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
1+
2+
Python Tools
3+
==========================
4+
5+
6+
.. _PythonToolsSetup:
7+
8+
Python Tools Setup
9+
---------------------------------
10+
11+
The preferred method to setup the GEOSX python tools is to run the following command in the build directory:
12+
13+
.. code-block:: bash
14+
15+
make geosx_python_tools
16+
17+
18+
This will attempt to install the required packages into the python distribution indicated via the `Python3_EXECUTABLE` cmake variable (also used by pygeosx).
19+
20+
If the user does not have write access for the target python distribution, the installation will attempt to create a new virtual python environment (Note: this requires that the virtualenv package be installed).
21+
If any package dependencies are missing, then the install script will attempt to fetch them from the internet using pip.
22+
After installation, these packages will be available for import within the associated python distribution, and a set of console scripts will be available within the GEOSX build bin directory.
23+
24+
Alternatively, these packages can be installed manually into a python environment using pip:
25+
26+
.. code-block:: bash
27+
28+
cd GEOSX/src/coreComponents/python/modules/geosx_mesh_tools_package
29+
pip install --upgrade .
30+
31+
cd ../geosx_xml_tools_package
32+
pip install --upgrade .
33+
34+
# Etc.
35+
36+
37+
Packages
38+
-----------------------
39+
40+
41+
.. toctree::
42+
:maxdepth: 1
43+
44+
hdf5_wrapper
45+
46+
geosx_mesh_tools
47+
48+
geosx_xml_tools
49+
50+
pygeosx_tools
51+
52+
timehistory
53+
54+
mesh_doctor

0 commit comments

Comments
 (0)