Skip to content

Commit

Permalink
Merge pull request #4497 from lisajulia/python-documentation
Browse files Browse the repository at this point in the history 
More Python documentation
  • Loading branch information
@blattms
blattms authored Feb 27, 2025
2 parents 287509a + b8a6bc6 commit 35c4832
Show file tree
Hide file tree
Showing 2 changed files with 150 additions and 40 deletions.
58 changes: 29 additions & 29 deletions python/cxx/eclipse_io.cpp
View file
Original file line number Diff line number Diff line change
Expand Up @@ -477,37 +477,37 @@ void python::common::export_IO(py::module& m) {
.def("__get_data", &get_erst_vector, py::arg("name"), py::arg("report_step"), py::arg("occurrence"), ERst_get_data_vector_docstring);


py::class_<ESmryBind>(m, "ESmry")
.def(py::init<const std::string &, const bool>(), py::arg("filename"), py::arg("load_base_run") = false)
.def("__contains__", &ESmryBind::hasKey, py::arg("key"))
.def("make_esmry_file", &ESmryBind::make_esmry_file)
.def("__len__", &ESmryBind::numberOfTimeSteps)
.def("__get_all", &ESmryBind::get_smry_vector, py::arg("key"))
.def("__get_at_rstep", &ESmryBind::get_smry_vector_at_rsteps, py::arg("key"))
.def_property_readonly("start_date", &ESmryBind::smry_start_date)
py::class_<ESmryBind>(m, "ESmry", ESmry_docstring)
.def(py::init<const std::string &, const bool>(), py::arg("filename"), py::arg("load_base_run") = false, ESmry_init_docstring)
.def("__contains__", &ESmryBind::hasKey, py::arg("key"), ESmry_contains_docstring)
.def("make_esmry_file", &ESmryBind::make_esmry_file, ESmry_make_esmry_file_docstring)
.def("__len__", &ESmryBind::numberOfTimeSteps, ESmry_len_docstring)
.def("__get_all", &ESmryBind::get_smry_vector, py::arg("key"), ESmry_get_all_docstring)
.def("__get_at_rstep", &ESmryBind::get_smry_vector_at_rsteps, py::arg("key"), ESmry_get_at_rstep_docstring)
.def_property_readonly("start_date", &ESmryBind::smry_start_date, ESmry_start_date_docstring)
.def("keys", (const std::vector<std::string>& (ESmryBind::*) (void) const)
&ESmryBind::keywordList)
&ESmryBind::keywordList, ESmry_keys1_docstring)
.def("keys", (std::vector<std::string> (ESmryBind::*) (const std::string&) const)
&ESmryBind::keywordList)
.def("dates", &ESmryBind::dates)
.def("units", &ESmryBind::units, py::arg("field"));

py::class_<Opm::EclIO::EGrid>(m, "EGrid")
.def(py::init<const std::string &, const std::string &>(), py::arg("filename"),
py::arg("grid_name") = "global")
.def_property_readonly("active_cells", &Opm::EclIO::EGrid::activeCells)
.def_property_readonly("dimension", &Opm::EclIO::EGrid::dimension)
.def("ijk_from_global_index", &Opm::EclIO::EGrid::ijk_from_global_index)
.def("ijk_from_active_index", &Opm::EclIO::EGrid::ijk_from_active_index)
.def("active_index", &Opm::EclIO::EGrid::active_index)
.def("global_index", &Opm::EclIO::EGrid::global_index)
.def("export_mapaxes", &Opm::EclIO::EGrid::get_mapaxes)
.def("xyz_from_ijk", &get_xyz_from_ijk)
.def("xyz_from_ijk", &get_xyz_from_ijk_mapaxes)
.def("xyz_from_active_index", &get_xyz_from_active_index)
.def("xyz_from_active_index", &get_xyz_from_active_index_mapaxes)
.def("cellvolumes", &get_cellvolumes)
.def("cellvolumes", &get_cellvolumes_mask);
&ESmryBind::keywordList, py::arg("pattern"), ESmry_keys2_docstring)
.def("dates", &ESmryBind::dates, ESmry_dates_docstring)
.def("units", &ESmryBind::units, py::arg("field"), ESmry_units_docstring);

py::class_<Opm::EclIO::EGrid>(m, "EGrid", EGrid_docstring)
.def(py::init<const std::string &, const std::string &>(), py::arg("filename"), py::arg("grid_name") = "global", EGrid_init_docstring)
.def_property_readonly("active_cells", &Opm::EclIO::EGrid::activeCells, EGrid_active_cells_docstring)
.def_property_readonly("dimension", &Opm::EclIO::EGrid::dimension, EGrid_dimension_docstring)
.def("ijk_from_global_index", &Opm::EclIO::EGrid::ijk_from_global_index, py::arg("global_index"), EGrid_ijk_from_global_index_docstring)
.def("ijk_from_active_index", &Opm::EclIO::EGrid::ijk_from_active_index, py::arg("active_index"), EGrid_ijk_from_active_index_docstring)
.def("active_index", &Opm::EclIO::EGrid::active_index, py::arg("i"), py::arg("j"), py::arg("k"), EGrid_active_index_docstring)
.def("global_index", &Opm::EclIO::EGrid::global_index, py::arg("i"), py::arg("j"), py::arg("k"), EGrid_global_index_docstring)
.def("export_mapaxes", &Opm::EclIO::EGrid::get_mapaxes, EGrid_export_mapaxes_docstring)
.def("xyz_from_ijk", &get_xyz_from_ijk, py::arg("i"), py::arg("j"), py::arg("k"), EGrid_xyz_from_ijk_docstring)
.def("xyz_from_ijk", &get_xyz_from_ijk_mapaxes, py::arg("i"), py::arg("j"), py::arg("k"), py::arg("apply_mapaxes"), EGrid_xyz_from_ijk_mapaxes_docstring)
.def("xyz_from_active_index", &get_xyz_from_active_index, py::arg("active_index"), EGrid_xyz_from_active_index_docstring)
.def("xyz_from_active_index", &get_xyz_from_active_index_mapaxes, py::arg("active_index"), py::arg("apply_mapaxes"), EGrid_xyz_from_active_index_mapaxes_docstring)
.def("cellvolumes", &get_cellvolumes, EGrid_cellvolumes_docstring)
.def("cellvolumes", &get_cellvolumes_mask, py::arg("mask"), EGrid_cellvolumes_mask_docstring);


py::class_<Opm::EclIO::ERft>(m, "ERft")
.def(py::init<const std::string &>())
Expand Down
132 changes: 121 additions & 11 deletions python/docstrings_common.json
View file
Original file line number Diff line number Diff line change
Expand Up @@ -645,36 +645,36 @@
"doc": "Returns a tuple containing the IJK indices of the grid cell with global index g.\n\n:return: A a tuple containing the IJK indices of the grid cell with global index g.\n:type: tuple(int,int,int)"
},
"EclipseGrid_getCellVolume1G": {
"signature": "EclipseGrid.getCellVolume1G(g: int) -> double",
"signature": "EclipseGrid.getCellVolume(g: int) -> double",
"doc": "Returns the cell volume for the grid cell at the global index g.\n\n:param g: The global index of the grid cell.\n:type g: int\n:return: The volume of the grid cell.\n:type: double"
},
"EclipseGrid_getCellVolume3": {
"signature": "EclipseGrid.getCellVolume3(i: int, j: int, k: int) -> double",
"signature": "EclipseGrid.getCellVolume(i: int, j: int, k: int) -> double",
"doc": "Returns the cell volume for a grid cell identified by its (i, j, k) indices.\n\n:param i: The I index of the grid cell.\n:type i: int\n:param j: The J index of the grid cell.\n:type j: int\n:param k: The K index of the grid cell.\n:type k: int\n:return: The volume of the grid cell identified by the (i, j, k) indices.\n:type: double"
},
"EclipseGrid_getCellVolumeAll": {
"signature": "EclipseGrid.getCellVolumeAll() -> numpy.ndarray[double]",
"signature": "EclipseGrid.getCellVolume() -> numpy.ndarray[double]",
"doc": "Returns a `numpy.ndarray <https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html>`_ containing the volumes of all grid cells. Each entry in the array corresponds to the volume of a grid cell, with the array index matching the global index of that cell.\n\n:return: A numpy.ndarray each entry represents the volume of a grid cell, the index being to the global index.\n:type: numpy.ndarray[double]"
},
"EclipseGrid_getCellVolumeMask": {
"signature": "EclipseGrid.getCellVolumeMask(mask: list[int]) -> numpy.ndarray[double]",
"doc": "Returns the cell volumes for the cells with the global ids given in the input list.\n\n:return: The cell volumes for the given cells.\n:type: numpy.ndarray[double]"
"signature": "EclipseGrid.getCellVolume(mask: list[int]) -> numpy.ndarray[double]",
"doc": "Returns the cell volumes for the selected cells.\n\n:param mask: List containing one entry per grid cell, if the entry in the list is '1', this cell is selected by the mask.\n:type mask: list[int]\n:return: The cell volumes for the given cells.\n:type: numpy.ndarray[double]"
},
"EclipseGrid_getCellDepth1G": {
"signature": "EclipseGrid.getCellDepth1G(g: int) -> double",
"signature": "EclipseGrid.getCellDepth(g: int) -> double",
"doc": "Returns the depth of the grid cell corresponding to the given global index.\n\n:param g: The global index of the grid cell.\n:type g: int\n:return: The depth of the grid cell with the specified global index.\n:type: double"
},
"EclipseGrid_getCellDepth3": {
"signature": "EclipseGrid.getCellDepth3(i: int, j: int, k: int) -> double",
"signature": "EclipseGrid.getCellDepth(i: int, j: int, k: int) -> double",
"doc": "Returns the depth of the grid cell specified by the given IJK indices.\n\n:param i: The I index of the grid cell.\n:type i: int\n:param j: The J index of the grid cell.\n:type j: int\n:param k: The K index of the grid cell.\n:type k: int\n:return: The depth of the grid cell with the specified IJK indices.\n:type: double"
},
"EclipseGrid_getCellDepthAll": {
"signature": "EclipseGrid.getCellDepthAll() -> numpy.ndarray[double]",
"signature": "EclipseGrid.getCellDepth() -> numpy.ndarray[double]",
"doc": "Returns a `numpy.ndarray <https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html>`_ containing the depths of all grid cells. Each entry in the array corresponds to the depth of a grid cell, with the array index matching the global index of that cell.\n\n:return: A numpy.ndarray each entry represents the depth of a grid cell, and the index being the global index.\n:type: numpy.ndarray[double]"
},
"EclipseGrid_getCellDepthMask": {
"signature": "EclipseGrid.getCellDepthMask(mask: list[int]) -> numpy.ndarray[double]",
"doc": "Returns the depths for the cell with the global ids given in the input list.\n\n:return: The depths for the given cells.\n:type: numpy.ndarray[double]"
"doc": "Returns the depths for the selected cells.\n\n:param mask: List containing one entry per grid cell, if the entry in the list is '1', this cell is selected by the mask.\n:type mask: list[int]\n:return: The depths for the given cells.\n:type: numpy.ndarray[double]"
},
"eclArrType": {
"type": "class",
Expand Down Expand Up @@ -752,8 +752,8 @@
"doc": "Represents an Eclipse Restart file. This class inherits from the class EclFile."
},
"ERst_init": {
"signature": "opm.io.ecl.ERst.__init__(filename: str)",
"doc": "Initializes the ERst object by loading the Restart file (and the underlying EclFile) from the specified path.\n\n:param filename: The path to the Restart file.\n:type filename: str"
"signature": "opm.io.ecl.ERst.__init__(filename: str) -> ERst",
"doc": "Initializes the ERst object by loading the Restart file (and the underlying EclFile) from the specified path.\n\n:param filename: The path to the Restart file.\n:type filename: str\n:return: The ERst object.\n:type: ERst"
},
"ERst_has_report_step": {
"signature": "opm.io.ecl.ERst.__has_report_step(report_step: int) -> bool",
Expand Down Expand Up @@ -794,6 +794,116 @@
"ERst_get_data_vector": {
"signature": "opm.io.ecl.ERst.get_erst_vector(name: str, report_step: int, occurrence: int) -> tuple[numpy.ndarray, eclArrType]",
"doc": "Retrieves the data array of the given name a the given occurrence at the given report step.\n\n:param name: The name of the arrays.\n:type name: str\n:param report_step: The report step.\n:type report_step: int\n:param occurrence: The occurrence to retrieve.\n:type occurrence: int\n:return: A tuple containing the data array and its associated type.\n:rtype: tuple[numpy.ndarray, eclArrType]"
},
"ESmry": {
"type": "class",
"signature": "opm.io.ecl.ESmry",
"doc": "Handles summary data from Eclipse simulations."
},
"ESmry_init": {
"signature": "opm.io.ecl.ESmry.__init__(filename: str, load_base_run: bool = False) -> ESmry",
"doc": "Initializes the ESmry object by loading the summary file.\n\n:param filename: Path to the .SMSPEC or .ESMRY file.\n:type filename: str\n:param load_base_run: Whether to load base run data. Default is False.\n:type load_base_run: bool\n:return: The ESmry object.\n:rtype: ESmry"
},
"ESmry_contains": {
"signature": "opm.io.ecl.ESmry.__contains__(key: str) -> bool",
"doc": "Checks if the specified key exists in the summary data.\n\n:param key: The key to check.\n:type key: str\n:return: True if the key exists, otherwise False.\n:rtype: bool"
},
"ESmry_make_esmry_file": {
"signature": "opm.io.ecl.ESmry.make_esmry_file() -> None",
"doc": "Generates an ESMRY file from an SMSPEC input file."
},
"ESmry_len": {
"signature": "opm.io.ecl.ESmry.__len__() -> int",
"doc": "Returns the number of time steps in the summary data.\n\n:return: The number of available time steps.\n:rtype: int"
},
"ESmry_get_all": {
"signature": "opm.io.ecl.ESmry.__get_all(key: str) -> numpy.ndarray",
"doc": "Retrieves the summary vector for the given key.\n\n:param key: The key.\n:type key: str\n:return: The summary for the specified key.\n:rtype: numpy.ndarray"
},
"ESmry_get_at_rstep": {
"signature": "opm.io.ecl.ESmry.__get_at_rstep(key: str) -> numpy.ndarray",
"doc": "Retrieves the report step summary vector for the given key.\n\n:param key: The key.\n:type key: str\n:return: The report step summary for the specified key.\n:rtype: numpy.ndarray"
},
"ESmry_start_date": {
"signature": "opm.io.ecl.ESmry.start_date -> datetime.datetime",
"doc": "The start date of the summary data as a `datetime.datetime <https://docs.python.org/3/library/datetime.html#datetime.datetime>`_.\n\n:return: The start date.\n:rtype: datetime.datetime"
},
"ESmry_keys1": {
"signature": "opm.io.ecl.ESmry.keys() -> list[str]",
"doc": "Retrieves a list of summary keys.\n\n:return: A list of available summary keys.\n:rtype: list[str]"
},
"ESmry_keys2": {
"signature": "opm.io.ecl.ESmry.keys(pattern: str) -> list[str]",
"doc": "Retrieves a list of summary keys matching the given pattern.\n\n:param pattern: A pattern to filter the keys.\n:type pattern: str\n:return: A list of available summary keys.\n:rtype: list[str]"
},
"ESmry_dates": {
"signature": "opm.io.ecl.ESmry.dates() -> list[datetime.datetime]",
"doc": "Retrieves a list of dates corresponding to the time steps in the summary data.\n\n:return: A list of dates.\n:rtype: list[datetime.datetime]"
},
"ESmry_units": {
"signature": "opm.io.ecl.ESmry.units(field: str) -> str",
"doc": "Retrieves the unit for a given field.\n\n:param field: The field name.\n:type field: str\n:return: The unit corresponding to the specified field.\n:rtype: str"
},
"EGrid": {
"type": "class",
"signature": "opm.io.ecl.EGrid",
"doc": "Represents an Eclipse Grid file."
},
"EGrid_init": {
"signature": "opm.io.ecl.EGrid.__init__(filename: str, grid_name: str = 'global') -> EGrid",
"doc": "Initializes an EGrid object by loading the grid file.\n\n:param filename: Path to the grid file.\n:type filename: str\n:param grid_name: The name of the grid (default is 'global').\n:type grid_name: str\n:return: The EGrid object.\n:rtype: EGrid"
},
"EGrid_active_cells": {
"signature": "opm.io.ecl.EGrid.active_cells -> int",
"doc": "Returns the number of active cells in the grid.\n\n:return: Number of active cells.\n:type: int"
},
"EGrid_dimension": {
"signature": "opm.io.ecl.EGrid.dimension -> tuple[int, int, int]",
"doc": "Returns the dimensions of the grid.\n\n:return: The (x,y,z) dimensions.\n:type: tuple[int, int, int]"
},
"EGrid_ijk_from_global_index": {
"signature": "opm.io.ecl.EGrid.ijk_from_global_index(global_index: int) -> tuple[int, int, int]",
"doc": "Converts a global index to IJK indices.\n\n:param global_index: The global index of the cell.\n:type global_index: int\n:return: The (I, J, K) indices.\n:type: tuple[int, int, int]"
},
"EGrid_ijk_from_active_index": {
"signature": "opm.io.ecl.EGrid.ijk_from_active_index(active_index: int) -> tuple[int, int, int]",
"doc": "Converts an active cell index to IJK indices.\n\n:param active_index: The active cell index.\n:type active_index: int\n:return: The (I, J, K) indices.\n:type: tuple[int, int, int]"
},
"EGrid_active_index": {
"signature": "opm.io.ecl.EGrid.active_index(i: int, j: int, k: int) -> int",
"doc": "Returns the active index corresponding to the given IJK index.\n\n:param i: The i index.\n:type i: int\n:param j: The j index.\n:type j: int\n:param k: The k index.\n:type k: int\n:return: The active cell index.\n:type: int"
},
"EGrid_global_index": {
"signature": "opm.io.ecl.EGrid.global_index(i: int, j: int, k: int) -> int",
"doc": "Returns the global index corresponding to the given IJK index.\n\n:param i: The i index.\n:type i: int\n:param j: The j index.\n:type j: int\n:param k: The k index.\n:type k: int\n:return: The global index.\n:type: int"
},
"EGrid_export_mapaxes": {
"signature": "opm.io.ecl.EGrid.export_mapaxes() -> tuple[double, 8]",
"doc": "Exports the map axes transformation for visualization.\n\n:return: tuple[double, 8]"
},
"EGrid_xyz_from_ijk": {
"signature": "opm.io.ecl.EGrid.xyz_from_ijk(i: int, j: int, k: int) -> tuple[tuple[double, 8], tuple[double, 8], tuple[double, 8]]",
"doc": "Computes the XYZ coordinates of the 8 cell corners given its ijk indices.\n\n:param i: The i index of the cell.\n:type i: int\n:param j: The j index of the cell.\n:type j: int\n:param k: The k index of the cell.\n:type k: int\n:return: The XYZ coordinates, as three tuples.\n:type: tuple[tuple[double, 8], tuple[double, 8], tuple[double, 8]]"
},
"EGrid_xyz_from_ijk_mapaxes": {
"signature": "opm.io.ecl.EGrid.xyz_from_ijk(i: int, j: int, k: int, apply_mapaxes: bool) -> tuple[tuple[double, 8], tuple[double, 8], tuple[double, 8]]",
"doc": "Computes the XYZ coordinates of the 8 cell corners given its ijk indices.\n\n:param i: The i index of the cell.\n:type i: int\n:param j: The j index of the cell.\n:type j: int\n:param k: The k index of the cell.\n:type k: int\n:param apply_mapaxes: Boolean to indicate if a mapaxes tranformation (if available) should be carried out before.\n:type apply_mapaxes: bool\n:return: The XYZ coordinates, as three tuples.\n:type: tuple[tuple[double, 8], tuple[double, 8], tuple[double, 8]]"
},
"EGrid_xyz_from_active_index": {
"signature": "opm.io.ecl.EGrid.xyz_from_active_index(active_index: int) -> tuple[tuple[double, 8], tuple[double, 8], tuple[double, 8]]",
"doc": "Computes the XYZ coordinates of a cell given its active index.\n\n:param active_index: The active cell index.\n:type active_index: int\n:return: XYZ coordinates.\n:type: tuple[float, float, float]"
},
"EGrid_xyz_from_active_index_mapaxes": {
"signature": "opm.io.ecl.EGrid.xyz_from_active_index(active_index: int, apply_mapaxes: bool) -> tuple[tuple[double, 8], tuple[double, 8], tuple[double, 8]]",
"doc": "Computes the XYZ coordinates of a cell given its active index.\n\n:param active_index: The active cell index.\n:type active_index: int\n:param apply_mapaxes: Boolean to indicate if a mapaxes tranformation (if available) should be carried out before.\n:type apply_mapaxes: bool\n:return: XYZ coordinates.\n:type: tuple[float, float, float]"
},
"EGrid_cellvolumes": {
"signature": "opm.io.ecl.EGrid.cellvolumes() -> numpy.ndarray",
"doc": "Returns an array containing the volume of each cell in the grid.\n\n:return: A NumPy array containing cell volumes.\n:type: numpy.ndarray"
},
"EGrid_cellvolumes_mask": {
"signature": "opm.io.ecl.EGrid.cellvolumes(mask: list[int]) -> numpy.ndarray",
"doc": "Returns an array containing the volume of the selected cells.\n\n:param mask: List containing one entry per grid cell, if the entry in the list is '1', this cell is selected by the mask.\n:type mask: list[int]\n:return: A NumPy array containing cell volumes.\n:type: numpy.ndarray"
}

}

0 comments on commit 35c4832

Please sign in to comment.