`pygeosx` — GEOS in Python

GEOS can be manipulated and executed through a Python script.

High-level control of GEOS is managed through the top-level pygeosx functions, like initialize and run. GEOS’s data can be manipulated by getting pylvarray views of LvArray objects living in GEOS’s data repository. These pylvarray views are fetched by calling Wrapper.value() after getting a Wrapper out of the data repository.

Warning

The pygeosx module provides plenty of opportunities to crash Python. See the Segmentation Faults section below.

Only Python 3 is supported.

Module Functions

pygeosx.initialize(rank, args)

Initialize GEOS for the first time, with a rank and command-line arguments.

This function should only be called once. To reinitialize, use the reinit function.

Generally the rank is obtained from the mpi4py module and the arguments are obtained from sys.argv.

Returns a Group representing the ProblemManager instance.

pygeosx.reinit(args)

Reinitialize GEOS with a new set of command-line arguments.

Returns a Group representing the ProblemManager instance.

pygeosx.apply_initial_conditions(): Apply the initial conditions.

pygeosx.finalize(): Finalize GEOS. After this no calls into pygeosx or to MPI are allowed.

pygeosx.run()

Enter the GEOS event loop.

Runs until hitting a breakpoint defined in the input deck, or until the simulation is complete.

Returns one of the state constants defined below.

GEOS State

pygeosx.UNINITIALIZED

pygeosx.INITIALIZED

pygeosx.READY_TO_RUN: This state indicates that GEOS still has time steps left to run.

pygeosx.COMPLETED: This state indicates that GEOS has completed the current simulation.

Module Classes

class pygeosx.Group

Python interface to geos::dataRepository::Group.

Used to get access to other groups, and ultimately to get wrappers and convert them into Python views of C++ objects.

groups(): Return a list of the subgroups.

wrappers(): Return a list of the wrappers.

get_group(path)

get_group(path, default): Return the Group at the relative path path; default is optional. If no group exists and default is not given, raise a ValueError; otherwise return default.

get_wrapper(path)

get_wrapper(path, default): Return the Wrapper at the relative path path; default is optional. If no Wrapper exists and default is not given, raise a ValueError; otherwise return default.

register(callback)

Register a callback on the physics solver.

The callback should take two arguments: the CRSMatrix and the array.

Raise TypeError if the group is not the Physics solver.

class pygeosx.Wrapper

Python interface to geos::dataRepository::WrapperBase.

Wraps a generic C++ object. Use repr to get a description of the type.

value()

Return a view of the wrapped value, or None if it cannot be exported to Python.

A breakdown of the possible return types:

Instance of a pylvarray class If the wrapped type is one of the LvArray types that have a Python wrapper type.
1D numpy.ndarray If the wrapped type is a numeric constant. The returned array is a shallow copy and has a single entry.
str If the wrapped type is a std::string this returns a copy of the string.
list of str If the wrapped type is a LvArray::Array< std::string, 1, … > or a std::vector< std::string >. This is a copy.
None If the wrapped type is not covered by any of the above.

Segmentation Faults

Improper use of this module and associated programs can easily cause Python to crash. There are two main causes of crashes. Both can be avoided by following some general guidelines.

Stale Numpy Views

The pylvarray classes (which may be returned from Wrapper.value()) provide various ways to get Numpy views of their data. However, those views are only valid as long as the LvArray object’s buffer is not reallocated. The buffer may be reallocated by invoking methods (the ones that require the pylarray.RESIZEABLE permission) or by calls into pygeosx. It is strongly recommended that you do not keep Numpy views of LvArray objects around after calls to pygeosx.

my_array = pygeosx.get_wrapper("path").value()
view = my_array.to_numpy()
my_array.resize(1000)
print(view) # segfault

Destroyed LvArray C++ objects

As mentioned earlier, the classes defined in this module cannot be created in Python; pygeosx must create an LvArray object in C++, then create a pylvarray view of it. However, the Python view will only be valid as long as the underlying LvArray C++ object is kept around. If that is destroyed, the Python object will be left holding an invalid pointer and subsequent attempts to use the Python object will cause undefined behavior. Unfortunately, pygeosx may destroy LvArray objects without warning. It is therefore strongly recommended that you do not keep pylvarray objects around after calls to pygeosx. The following code snippet, for instance, could segfault:

my_array = pygeosx.get_wrapper("path").value()
pygeosx.run()
view = my_array.to_numpy() # segfault

pygeosx — GEOS in Python