Using the C++ interface

O2sclpy

C++ interface contents

C++ interface introduction

O₂sclpy includes several classes and functions which are wrappers around the original O₂scl classes and functions. The full documentation of these classes and functions is not reproduced here, but a link to the O₂scl documentation is provided. Note also that not all O₂scl functions are wrapped. In those O₂scl classes which are wrapped in O₂sclpy, not all of their methods or data members are accessible in O₂sclpy. If there is O₂scl which is missing and you would like me to include, let me know.

The O₂scl library is dynamically linked when O₂sclpy is imported. O₂sclpy classes which require O₂scl obtain a link from a global

Generally, O₂sclpy wrappers around O₂scl classes should take care of memory management for you. If they have ownership over their pointer, then their _owner data is True, and their __del__ method will call the C++ function necessary to free the memory associated with the underlying object. O₂sclpy contains wrappers to some std::shared_ptr objects, and these objects may not be destructed until the Python garbage collector deletes the last O₂sclpy class which owns a copy of the shared_ptr.

Throwing C++ exceptions across DLL boundaries is not supported in O₂scl, so O₂sclpy ensures that O₂scl uses an alternate error handler which calls exit() (i.e. from libc) when an error occurs. O₂sclpy does not support any interaction between Python and C++ exceptions.

Linking with O₂scl

The o2sclpy.linker class (see below) controls the dynamical loading of the O₂scl libraries. Some additional environment variables may need to be set in order to perform the dynamic loading properly.

The variable o2sclpy.linker.o2scl_cpp_lib specifies the C++ library to be loaded, in case it is not loaded automatically. This can be set by the environment variable O2SCL_CPP_LIB. On a MacOS laptop, when using clang the C++ library is typically found automatically, but when using gcc I have to set this value to something like /usr/local/lib/gcc/13/libstdc++.dylib.

The variable o2sclpy.linker.o2scl_lib_dir specifies the directory where libo2scl.so is to be found, in case it cannot be found automatically. This can be set by the environment variable O2SCL_LIB_DIR.

Finally, the variable o2sclpy.linker.o2scl_addl_libs is a list of additional libraries which are required and not automatically included by the dynamic loading. This can be set by specifying a comma-separated list in the environment variable O2SCL_ADDL_LIBS. If O₂scl is installed with OpenMP support, the OpenMP libraries are often not automatically linked in, and so you may need to include something similar to /usr/local/lib/gcc/13/libgomp.1.dylib. Also, on my MacOS laptop, the readline library is not automatically included, so I typically use O2SCL_ADDL_LIBS=/usr/lib/libreadline.dylib,/usr/local/lib/gcc/13/libgomp.1.dylib.

Linking with O₂scl example

Use this link to view this example as a jupyter notebook on nbviewer.org.

# # O$_2$scl library linking example for O$_2$sclpy

# See the O$_2$sclpy documentation at
# https://awsteiner.org/code/o2sclpy for more information.

# +
import sys
import o2sclpy

plots=True
if 'pytest' in sys.modules:
    plots=False
# -

# Importing ``o2sclpy'' automatically links the O$_2$scl library.
# Environment variables can be used to specify the location of various
# libraries which need to be added. See
# http://awsteiner.org/code/o2sclpy/link_cpp.html#linking-with-o2scl
# for more detail.

# To print the DLL handle obtain on import

print('O₂scl library DLL:',o2sclpy.doc_data.top_linker.o2scl)

# Obtain the O$_2$scl version from the DLL:

o2scl_settings=o2sclpy.lib_settings_class()

print('O₂scl library version',o2scl_settings.o2scl_version())

def test_fun():
    assert o2scl_settings.o2scl_version()==b'0.931'
    return

Class linker

class o2sclpy.linker

The class which controls the dynamic linking of the O2scl libraries and also the setting of the matplotlib backend for o2graph. If O2scl is successfully linked, this class also provides access to the global O2scl library settings object.

backend = ''

Backend specification from command-line

get_library_settings(argv=[])

Get the library settings from environment variables or the command-line arguments

A function for linking the o2scl libraries.

o2scl = 0

Main o2scl library handle

o2scl_addl = [<CDLL '/usr/lib/gcc/x86_64-linux-gnu/13/libgomp.so', handle 12f14d40>]

Additional library handles

o2scl_addl_libs = []

Additional library list from command-line or environment variables

o2scl_cpp_lib = ''

C++ library from command-line or environment variables

o2scl_lib_dir = ''

O2scl library directory from command-line or environment variables

o2scl_settings = 0

The o2scl_settings object

systcpp = 0

System C++ library handle

verbose = 0

If greater than 0, output more information about the linker. The command-line option -debug-link sets this parameter to 1.