Skip to content

Commit

Permalink
Merge pull request #4405 from lisajulia/feature/pyAction-documentation
Browse files Browse the repository at this point in the history 
Add missing documentation
  • Loading branch information
@blattms
blattms authored Jan 9, 2025
2 parents 50288c2 + bd81d65 commit e27878e
Show file tree
Hide file tree
Showing 6 changed files with 417 additions and 103 deletions.
36 changes: 20 additions & 16 deletions python/cxx/connection.cpp
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,8 @@

#include "export.hpp"

#include <python/cxx/OpmCommonPythonDoc.hpp>

namespace {

std::string state( const Connection& c ) {
Expand All @@ -21,20 +23,22 @@ std::tuple<int, int, int> get_pos( const Connection& conn ) {

void python::common::export_Connection(py::module& module) {

py::class_< Connection >( module, "Connection")
.def_property_readonly("direction", &direction )
.def_property_readonly("state", &state )
.def_property_readonly( "i", &Connection::getI )
.def_property_readonly( "j", &Connection::getJ )
.def_property_readonly( "k", &Connection::getK )
.def_property_readonly( "pos", &get_pos )
.def_property_readonly( "attached_to_segment", &Connection::attachedToSegment )
.def_property_readonly( "center_depth", &Connection::depth)
.def_property_readonly( "rw", &Connection::rw)
.def_property_readonly( "complnum", &Connection::complnum)
.def_property_readonly( "number", &Connection::complnum) // This is deprecated; complnum is the "correct" proeprty name
.def_property_readonly( "sat_table_id", &Connection::satTableId)
.def_property_readonly( "segment_number", &Connection::segment)
.def_property_readonly( "cf", &Connection::CF)
.def_property_readonly( "kh", &Connection::Kh);
using namespace Opm::Common::DocStrings;

py::class_<Connection>(module, "Connection", Connection_docstring)
.def_property_readonly("direction", &direction, Connection_direction_docstring)
.def_property_readonly("state", &state, Connection_state_docstring)
.def_property_readonly("i", &Connection::getI, Connection_getI_docstring)
.def_property_readonly("j", &Connection::getJ, Connection_getJ_docstring)
.def_property_readonly("k", &Connection::getK, Connection_getK_docstring)
.def_property_readonly("pos", &get_pos, Connection_pos_docstring)
.def_property_readonly("attached_to_segment", &Connection::attachedToSegment, Connection_attachedToSegment_docstring)
.def_property_readonly("center_depth", &Connection::depth, Connection_depth_docstring)
.def_property_readonly("rw", &Connection::rw, Connection_rw_docstring)
.def_property_readonly("complnum", &Connection::complnum, Connection_complnum_docstring)
.def_property_readonly("number", &Connection::complnum, Connection_number_docstring) // DEPRECATED: Use 'complnum' instead.
.def_property_readonly("sat_table_id", &Connection::satTableId, Connection_satTableId_docstring)
.def_property_readonly("segment_number", &Connection::segment, Connection_segment_docstring)
.def_property_readonly("cf", &Connection::CF, Connection_CF_docstring)
.def_property_readonly("kh", &Connection::Kh, Connection_Kh_docstring);
}
41 changes: 21 additions & 20 deletions python/cxx/deck.cpp
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,7 @@
#include "converters.hpp"
#include "export.hpp"

#include <python/cxx/OpmCommonPythonDoc.hpp>

namespace {

Expand Down Expand Up @@ -45,34 +46,34 @@ namespace {

void python::common::export_Deck(py::module &module) {

using namespace Opm::Common::DocStrings;

// Note: In the below class we use std::shared_ptr as the holder type, see:
//
// https://pybind11.readthedocs.io/en/stable/advanced/smart_ptrs.html
//
// this makes it possible to share the returned object with e.g. and
// opm.simulators.BlackOilSimulator Python object
//
py::class_< Deck, std::shared_ptr<Deck> >(module, "Deck")
.def( "__len__", &size )
.def( "__contains__", &hasKeyword )
py::class_<Deck, std::shared_ptr<Deck>>(module, "Deck", Deck_docstring)
.def("__len__", &size, Deck_len_docstring)
.def("__contains__", &hasKeyword, py::arg("keyword"), Deck_contains_docstring)
.def("__iter__",
[] (const Deck &deck) { return py::make_iterator(deck.begin(), deck.end()); }, py::keep_alive<0, 1>())
.def( "__getitem__", &getKeyword_int, ref_internal)
.def( "__getitem__", &getKeyword_string, ref_internal)
.def( "__getitem__", &getKeyword_tuple, ref_internal)
.def( "__str__", &str<Deck>)

.def("active_unit_system", [](const Deck& deck) -> const UnitSystem& {
return deck.getActiveUnitSystem();
} )

.def("default_unit_system", [](const Deck& deck) -> const UnitSystem& {
return deck.getDefaultUnitSystem();
} )

.def( "count", &count )
.def( "add", &addKeyword)
;
[](const Deck &deck) { return py::make_iterator(deck.begin(), deck.end()); },
py::keep_alive<0, 1>(), Deck_iter_docstring)
.def("__getitem__", &getKeyword_int, py::arg("index"), ref_internal, Deck_getitem_int_docstring)
.def("__getitem__", &getKeyword_string, py::arg("keyword"), ref_internal, Deck_getitem_string_docstring)
.def("__getitem__", &getKeyword_tuple, py::arg("keyword_index"), ref_internal, Deck_getitem_tuple_docstring)
.def("__str__", &str<Deck>, Deck_str_docstring)
.def("active_unit_system",
[](const Deck& deck) -> const UnitSystem& { return deck.getActiveUnitSystem(); },
Deck_active_unit_system_docstring)
.def("default_unit_system",
[](const Deck& deck) -> const UnitSystem& { return deck.getDefaultUnitSystem(); },
Deck_default_unit_system_docstring)
.def("count", &count, py::arg("keyword"), Deck_count_docstring)
.def("add", &addKeyword, py::arg("keyword"), Deck_add_docstring);

}


83 changes: 42 additions & 41 deletions python/cxx/deck_keyword.cpp
View file
Original file line number Diff line number Diff line change
Expand Up @@ -14,8 +14,9 @@
#include "export.hpp"
#include "converters.hpp"

#include <iostream>
#include <python/cxx/OpmCommonPythonDoc.hpp>

#include <iostream>

namespace {

Expand Down Expand Up @@ -164,11 +165,12 @@ std::string get_string(DeckItem * item, std::size_t index) {

}
void python::common::export_DeckKeyword(py::module& module) {
py::class_< DeckKeyword >( module, "DeckKeyword")
.def(py::init<const ParserKeyword& >())

.def(py::init([](const ParserKeyword& parser_keyword, py::list record_list, UnitSystem& active_system, UnitSystem& default_system) {
using namespace Opm::Common::DocStrings;

py::class_<DeckKeyword>(module, "DeckKeyword", DeckKeyword_docstring)
.def(py::init<const ParserKeyword&>(), py::arg("parser_keyword"), DeckKeyword_init_parser_keyword_docstring)
.def(py::init([](const ParserKeyword& parser_keyword, py::list record_list, UnitSystem& active_system, UnitSystem& default_system) {
std::vector< std::vector<DeckValue> > value_record_list;
int i = 0;
for (py::handle record_obj : record_list) {
Expand Down Expand Up @@ -218,27 +220,26 @@ void python::common::export_DeckKeyword(py::module& module) {
value_record_list.push_back( value_record );
}
return DeckKeyword(parser_keyword, value_record_list, active_system, default_system);
} ) )

.def( "__repr__", &DeckKeyword::name )
.def( "__str__", &str<DeckKeyword> )
.def("__iter__", [] (const DeckKeyword &keyword) { return py::make_iterator(keyword.begin(), keyword.end()); }, py::keep_alive<0,1>())
.def( "__getitem__", getRecord, ref_internal)
.def( "__len__", &DeckKeyword::size )
.def_property_readonly("name", &DeckKeyword::name )

.def(py::init([](const ParserKeyword& parser_keyword, py::array_t<int> py_data) {
} ), py::arg("parser_keyword"), py::arg("record_list"), py::arg("active_system"), py::arg("default_system"), DeckKeyword_init_parser_keyword_record_list_docstring)
.def("__repr__", &DeckKeyword::name, DeckKeyword_repr_docstring)
.def("__str__", &str<DeckKeyword>, DeckKeyword_str_docstring)
.def("__iter__", [](const DeckKeyword &keyword) { return py::make_iterator(keyword.begin(), keyword.end()); },
py::keep_alive<0,1>(), DeckKeyword_iter_docstring)
.def("__getitem__", getRecord, ref_internal, py::arg("index"), DeckKeyword_getitem_docstring)
.def("__len__", &DeckKeyword::size, DeckKeyword_len_docstring)
.def_property_readonly("name", &DeckKeyword::name, DeckKeyword_name_docstring)

.def(py::init([](const ParserKeyword& parser_keyword, py::array_t<int> py_data) {
return DeckKeyword(parser_keyword, convert::vector(py_data));
} ) )
}), py::arg("parser_keyword"), py::arg("py_data"), DeckKeyword_init_parser_keyword_pydata_int_docstring)

.def(py::init([](const ParserKeyword& parser_keyword, py::array_t<double> py_data, UnitSystem& active_system, UnitSystem& default_system) {
.def(py::init([](const ParserKeyword& parser_keyword, py::array_t<double> py_data, UnitSystem& active_system, UnitSystem& default_system) {
return DeckKeyword(parser_keyword, convert::vector(py_data), active_system, default_system);
} ) )
}), py::arg("parser_keyword"), py::arg("py_data"), py::arg("active_system"), py::arg("default_system"), DeckKeyword_init_parser_keyword_pydata_double_docstring)

.def("get_int_array", &get_int_array)
.def("get_raw_array", &get_raw_array)
.def("get_SI_array", &get_SI_array)
;
.def("get_int_array", &get_int_array, DeckKeyword_get_int_array_docstring)
.def("get_raw_array", &get_raw_array, DeckKeyword_get_raw_array_docstring)
.def("get_SI_array", &get_SI_array, DeckKeyword_get_SI_array_docstring);


py::class_< DeckRecord >( module, "DeckRecord")
Expand All @@ -249,26 +250,26 @@ void python::common::export_DeckKeyword(py::module& module) {
;


py::class_< DeckItem >(module, "DeckItem")
.def( "__len__", &DeckItem::data_size )
.def("is_uda", &DeckItem::is_uda)
.def("is_double", &DeckItem::is_double)
.def("is_int", &DeckItem::is_int)
.def("is_string", &DeckItem::is_string)
.def("get_str", &get_string)
.def("get_int", &DeckItem::get<int>)
.def("get_raw", &DeckItem::get<double>)
.def("get_uda", &DeckItem::get<UDAValue>)
.def("get_SI", &DeckItem::getSIDouble)
.def("get_data_list", &item_to_pylist)
.def("get_raw_data_list", &raw_data_to_pylist)
.def("get_SI_data_list", &SI_data_to_pylist)
.def("__has_value", &DeckItem::hasValue)
.def("__defaulted", &DeckItem::defaultApplied)
.def("__is_numeric", &uda_item_is_numeric)
.def("__uda_double", &get_uda_double)
.def("__uda_str", &get_uda_str)
.def("name", &DeckItem::name)
py::class_<DeckItem>(module, "DeckItem", DeckItem_docstring)
.def("__len__", &DeckItem::data_size, DeckItem_len_docstring)
.def("is_uda", &DeckItem::is_uda, DeckItem_is_uda_docstring)
.def("is_double", &DeckItem::is_double, DeckItem_is_double_docstring)
.def("is_int", &DeckItem::is_int, DeckItem_is_int_docstring)
.def("is_string", &DeckItem::is_string, DeckItem_is_string_docstring)
.def("get_str", &get_string, py::arg("index"), DeckItem_get_str_docstring)
.def("get_int", &DeckItem::get<int>, py::arg("index"), DeckItem_get_int_docstring)
.def("get_raw", &DeckItem::get<double>, py::arg("index"), DeckItem_get_raw_docstring)
.def("get_uda", &DeckItem::get<UDAValue>, py::arg("index"), DeckItem_get_uda_docstring)
.def("get_SI", &DeckItem::getSIDouble, py::arg("index"), DeckItem_get_SI_docstring)
.def("get_data_list", &item_to_pylist, DeckItem_get_data_list_docstring)
.def("get_raw_data_list", &raw_data_to_pylist, DeckItem_get_raw_data_list_docstring)
.def("get_SI_data_list", &SI_data_to_pylist, DeckItem_get_SI_data_list_docstring)
.def("__has_value", &DeckItem::hasValue, py::arg("index"), DeckItem_has_value_docstring)
.def("__defaulted", &DeckItem::defaultApplied, py::arg("index"), DeckItem_defaulted_docstring)
.def("__is_numeric", &uda_item_is_numeric, DeckItem_is_numeric_docstring)
.def("__uda_double", &get_uda_double, DeckItem_uda_double_docstring)
.def("__uda_str", &get_uda_str, DeckItem_uda_str_docstring)
.def("name", &DeckItem::name, DeckItem_name_docstring)
;


Expand Down
28 changes: 14 additions & 14 deletions python/cxx/schedule.cpp
View file
Original file line number Diff line number Diff line change
Expand Up @@ -209,30 +209,30 @@ void python::common::export_Schedule(py::module& module) {
py::class_< Schedule, std::shared_ptr<Schedule> >( module, "Schedule", ScheduleClass_docstring)
.def(py::init<const Deck&, const EclipseState& >(), py::arg("deck"), py::arg("eclipse_state"))
.def("_groups", &get_groups, py::arg("report_step"), Schedule_groups_docstring)
.def_property_readonly( "start", &get_start_time )
.def_property_readonly( "end", &get_end_time )
.def_property_readonly("start", &get_start_time, Schedule_start_docstring)
.def_property_readonly("end", &get_end_time, Schedule_end_docstring)
.def_property_readonly("timesteps", [](const Schedule& self) {
py::print("The property 'timesteps' is deprecated, since the name is misleading. This actually returns the report steps, so use 'reportsteps' instead!");
return get_reportsteps(self);
}) // Deprecated since the name is misleading, this function actually returns the report steps
.def_property_readonly( "reportsteps", &get_reportsteps )
.def("__len__", &Schedule::size)
.def_property_readonly("reportsteps", &get_reportsteps, Schedule_reportsteps_docstring)
.def("__len__", &Schedule::size, Schedule_len_docstring)
.def("__getitem__", &getitem, py::arg("report_step"), Schedule_getitem_docstring)
.def("shut_well", py::overload_cast<const std::string&, std::size_t>(&Schedule::shut_well), py::arg("well_name"), py::arg("step"), Schedule_shut_well_well_name_step_docstring)
.def("shut_well", py::overload_cast<const std::string&>(&Schedule::shut_well), py::arg("well_name"), Schedule_shut_well_well_name_docstring)
.def("open_well", py::overload_cast<const std::string&, std::size_t>(&Schedule::open_well), py::arg("well_name"), py::arg("step"), Schedule_open_well_well_name_step_docstring)
.def("open_well", py::overload_cast<const std::string&>(&Schedule::open_well), py::arg("well_name"), Schedule_open_well_well_name_docstring)
.def("stop_well", py::overload_cast<const std::string&, std::size_t>(&Schedule::stop_well), py::arg("well_name"), py::arg("step"), Schedule_stop_well_well_name_step_docstring)
.def("stop_well", py::overload_cast<const std::string&>(&Schedule::stop_well), py::arg("well_name"), Schedule_stop_well_well_name_docstring)
.def( "get_wells", &Schedule::getWells, py::arg("well_name_pattern"), Schedule_get_wells_docstring)
.def( "get_injection_properties", &get_injection_properties, py::arg("well_name"), py::arg("report_step"), Schedule_get_injection_properties_docstring)
.def( "get_production_properties", &get_production_properties, py::arg("well_name"), py::arg("report_step"), Schedule_get_production_properties_docstring)
.def("well_names", py::overload_cast<const std::string&>(&Schedule::wellNames, py::const_), py::arg("well_name_pattern"))
.def( "get_well", &get_well, py::arg("well_name"), py::arg("report_step"), Schedule_get_well_docstring)
.def( "insert_keywords", py::overload_cast<Schedule&, py::list&, std::size_t>(&insert_keywords), py::arg("keywords"), py::arg("step"))
.def( "insert_keywords", py::overload_cast<Schedule&, const std::string&, std::size_t, const UnitSystem&>(&insert_keywords), py::arg("data"), py::arg("step"), py::arg("unit_system"))
.def( "insert_keywords", py::overload_cast<Schedule&, const std::string&, std::size_t>(&insert_keywords), py::arg("data"), py::arg("step"))
.def( "insert_keywords", py::overload_cast<Schedule&, const std::string&>(&insert_keywords),py::arg("data"))
.def("__contains__", &has_well, py::arg("well_name"))
.def("get_wells", &Schedule::getWells, py::arg("report_step"), Schedule_get_wells_docstring)
.def("get_injection_properties", &get_injection_properties, py::arg("well_name"), py::arg("report_step"), Schedule_get_injection_properties_docstring)
.def("get_production_properties", &get_production_properties, py::arg("well_name"), py::arg("report_step"), Schedule_get_production_properties_docstring)
.def("well_names", py::overload_cast<const std::string&>(&Schedule::wellNames, py::const_), py::arg("well_name_pattern"), Schedule_well_names_docstring)
.def("get_well", &get_well, py::arg("well_name"), py::arg("report_step"), Schedule_get_well_docstring)
.def("insert_keywords", py::overload_cast<Schedule&, py::list&, std::size_t>(&insert_keywords), py::arg("keywords"), py::arg("step"), Schedule_insert_keywords_list_docstring)
.def("insert_keywords", py::overload_cast<Schedule&, const std::string&, std::size_t, const UnitSystem&>(&insert_keywords), py::arg("data"), py::arg("step"), py::arg("unit_system"), Schedule_insert_keywords_data_step_unit_system_docstring)
.def("insert_keywords", py::overload_cast<Schedule&, const std::string&, std::size_t>(&insert_keywords), py::arg("data"), py::arg("step"), Schedule_insert_keywords_data_step_docstring)
.def("insert_keywords", py::overload_cast<Schedule&, const std::string&>(&insert_keywords),py::arg("data"), Schedule_insert_keywords_data_docstring)
.def("__contains__", &has_well, py::arg("well_name"), Schedule_contains_docstring)
;
}
8 changes: 4 additions & 4 deletions python/cxx/summary_state.cpp
View file
Original file line number Diff line number Diff line change
Expand Up @@ -48,18 +48,18 @@ void python::common::export_SummaryState(py::module& module) {

py::class_<SummaryState, std::shared_ptr<SummaryState>>(module, "SummaryState", SummaryStateClass_docstring)
.def(py::init<std::time_t>())
.def("update", &SummaryState::update)
.def("update", &SummaryState::update, py::arg("variable_name"), py::arg("value"), SummaryState_update_docstring)
.def("update_well_var", &SummaryState::update_well_var, py::arg("well_name"), py::arg("variable_name"), py::arg("new_value"), SummaryState_update_well_var_docstring)
.def("update_group_var", &SummaryState::update_group_var, py::arg("group_name"), py::arg("variable_name"), py::arg("new_value"), SummaryState_update_group_var_docstring)
.def("well_var", py::overload_cast<const std::string&, const std::string&>(&SummaryState::get_well_var, py::const_), py::arg("well_name"), py::arg("variable_name"), SummaryState_well_var_docstring)
.def("group_var", py::overload_cast<const std::string&, const std::string&>(&SummaryState::get_group_var, py::const_), py::arg("group_name"), py::arg("variable_name"), SummaryState_group_var_docstring)
.def("elapsed", &SummaryState::get_elapsed, SummaryState_elapsed_docstring)
.def_property_readonly("groups", groups, SummaryState_groups_docstring)
.def_property_readonly("wells", wells, SummaryState_wells_docstring)
.def("__contains__", &SummaryState::has)
.def("__contains__", &SummaryState::has, py::arg("variable_name"), SummaryState_contains_docstring)
.def("has_well_var", py::overload_cast<const std::string&, const std::string&>(&SummaryState::has_well_var, py::const_), py::arg("well_name"), py::arg("variable_name"), SummaryState_has_well_var_docstring)
.def("has_group_var", py::overload_cast<const std::string&, const std::string&>(&SummaryState::has_group_var, py::const_), py::arg("group_name"), py::arg("variable_name"), SummaryState_has_group_var_docstring)
.def("__setitem__", &SummaryState::set)
.def("__getitem__", py::overload_cast<const std::string&>(&SummaryState::get, py::const_))
.def("__setitem__", &SummaryState::set, py::arg("variable_name"), py::arg("new_value"), SummaryState_setitem_docstring)
.def("__getitem__", py::overload_cast<const std::string&>(&SummaryState::get, py::const_), py::arg("variable_name"), SummaryState_getitem_docstring)
;
}
Loading

0 comments on commit e27878e

Please sign in to comment.