`pyranha`¶

Root pyranha module.

pyranha.__all__ = ['celmec', 'math', 'test', 'types']¶: List of Pyranha submodules.

class pyranha.settings[source]¶

Settings class.

This class is used to configure global Pyranha settings via static methods. The methods are thread-safe.

static get_latex_repr()[source]¶

Check if the TeX representation of exposed types is enabled.

The _repr_latex_() method, if present, is used by the Jupyter notebook to display the TeX representation of an exposed type via a Javascript library. If an object is very large, it might be preferrable to disable the TeX representation in order to improve the performance of the notebook UI. When the TeX representation is disabled, Jupyter will fall back to the PNG-based representation of the object, which leverages - if available - a local installation of TeX for increased performance via a static rendering of the TeX representation of the object to a PNG bitmap.

By default, the TeX representation is enabled. See also pyranha.settings.set_latex_repr().

>>> settings.get_latex_repr()
True
>>> from .types import polynomial, rational, k_monomial
>>> pt = polynomial[rational,k_monomial]()
>>> x = pt('x')
>>> (x**2/2)._repr_latex_()
'\\[ \\frac{1}{2}{x}^{2} \\]'

static get_max_term_output()[source]¶

Get the maximum number of series terms to print.

Returns:	the maximum number of series terms to print
Raises:	any exception raised by the invoked low-level function

>>> settings.get_max_term_output()
20

static get_min_work_per_thread()[source]¶

Get the minimum work per thread.

>>> settings.get_min_work_per_thread() 
500000 # This will be an implementation-defined value.

static get_n_threads()[source]¶

Get the number of threads that can be used by Piranha.

The initial value is auto-detected on program startup.

Raises:	any exception raised by the invoked low-level function

>>> settings.get_n_threads() 
16 # This will be a platform-dependent value.

static get_thread_binding()[source]¶

Get the thread binding policy.

This method will return the flag set by pyranha.settings.set_thread_binding(). On program startup, the value returned by this function will be False.

Returns:	the thread binding policy
Return type:	`bool`
Raises:	any exception raised by the invoked low-level function

>>> settings.get_thread_binding()
False
>>> settings.set_thread_binding(True)
>>> settings.get_thread_binding()
True
>>> settings.set_thread_binding(False)
>>> settings.get_thread_binding()
False

static reset_max_term_output()[source]¶

Reset the maximum number of series terms to print to the default value.

Raises:	any exception raised by the invoked low-level function

>>> settings.set_max_term_output(10)
>>> settings.get_max_term_output()
10
>>> settings.reset_max_term_output()
>>> settings.get_max_term_output()
20

static reset_min_work_per_thread()[source]¶

Reset the minimum work per thread.

>>> n = settings.get_min_work_per_thread()
>>> settings.set_min_work_per_thread(10)
>>> settings.get_min_work_per_thread() 
10
>>> settings.reset_min_work_per_thread()
>>> settings.get_min_work_per_thread() == n
True

static reset_n_threads()[source]¶

Reset the number of threads that can be used by Piranha to the default value.

Raises:	any exception raised by the invoked low-level function

>>> n = settings.get_n_threads()
>>> settings.set_n_threads(10)
>>> settings.get_n_threads()
10
>>> settings.reset_n_threads()
>>> settings.get_n_threads() == n
True

static set_latex_repr(flag)[source]¶

Set the availability of the _repr_latex_() method for the exposed types.

If flag is True, the _repr_latex_() method of exposed types will be enabled. Otherwise, the method will be disabled. See the documentation for pyranha.settings.get_latex_repr() for a description of how the method is used.

Parameters:	flag (`bool`) – availability flag for the `_repr_latex_()` method
Raises:	`TypeError` if flag is not a `bool`

>>> settings.set_latex_repr(False)
>>> settings.get_latex_repr()
False
>>> from .types import polynomial, rational, k_monomial
>>> pt = polynomial[rational,k_monomial]()
>>> x = pt('x')
>>> (x**2/2)._repr_latex_() 
Traceback (most recent call last):
  ...
AttributeError: object has no attribute '_latex_repr_'
>>> settings.set_latex_repr(True)
>>> (x**2/2)._repr_latex_()
'\\[ \\frac{1}{2}{x}^{2} \\]'
>>> settings.set_latex_repr("hello") 
Traceback (most recent call last):
  ...
TypeError: the 'flag' parameter must be a bool

static set_max_term_output(n)[source]¶

Set the maximum number of series terms to print.

Parameters:	n (`int`) – number of series terms to print
Raises:	any exception raised by the invoked low-level function

>>> settings.set_max_term_output(10)
>>> settings.get_max_term_output()
10
>>> settings.set_max_term_output(-1) 
Traceback (most recent call last):
  ...
OverflowError: invalid value
>>> settings.set_max_term_output("hello") 
Traceback (most recent call last):
  ...
TypeError: invalid type
>>> settings.reset_max_term_output()

static set_min_work_per_thread(n)[source]¶

Set the minimum work per thread.

Parameters:	n (`int`) – desired work per thread
Raises:	any exception raised by the invoked low-level function

>>> settings.set_min_work_per_thread(2)
>>> settings.get_min_work_per_thread() 
2
>>> settings.set_min_work_per_thread(0) 
Traceback (most recent call last):
  ...
ValueError: invalid value
>>> settings.set_min_work_per_thread(-1) 
Traceback (most recent call last):
  ...
OverflowError: invalid value
>>> settings.reset_min_work_per_thread()

static set_n_threads(n)[source]¶

Set the number of threads that can be used by Piranha.

Parameters:	n (`int`) – desired number of threads
Raises:	any exception raised by the invoked low-level function

>>> settings.set_n_threads(2)
>>> settings.get_n_threads()
2
>>> settings.set_n_threads(0) 
Traceback (most recent call last):
  ...
ValueError: invalid value
>>> settings.set_n_threads(-1) 
Traceback (most recent call last):
  ...
OverflowError: invalid value
>>> settings.reset_n_threads()

static set_thread_binding(flag)[source]¶

Set the thread binding policy.

By default, the threads created by Piranha are not bound to specific processors/cores. Calling this method with a True flag will instruct Piranha to attempt to bind each thread to a different processor/core (which can result in increased performance in certain circumstances). If flag is False, the threads created by Piranha will be free to migrate across processors/cores.

Parameters:	flag (`bool`) – the desired thread binding policy
Raises:	any exception raised by the invoked low-level function

>>> settings.get_thread_binding()
False
>>> settings.set_thread_binding(True)
>>> settings.get_thread_binding()
True
>>> settings.set_thread_binding(False)
>>> settings.get_thread_binding()
False
>>> settings.set_thread_binding(4.56) 
Traceback (most recent call last):
  ...
TypeError: invalid argument type(s)

class pyranha.data_format[source]¶

Data format.

The members of this class identify the data formats that can be used when saving/loading to/from disk symbolic objects via pyranha.save_file() and pyranha.load_file(). The Boost formats are based on the Boost serialization library and they are always available. The msgpack formats rely on the msgpack-c library (which is an optional dependency).

The portable variants are slower but suitable for use across architectures and Piranha versions, the binary variants are faster but they are not portable across architectures and Piranha versions.

boost_binary = pyranha._core.data_format.boost_binary¶: Boost binary format.

boost_portable = pyranha._core.data_format.boost_portable¶: Boost portable format.

msgpack_binary = pyranha._core.data_format.msgpack_binary¶: msgpack binary format.

msgpack_portable = pyranha._core.data_format.msgpack_portable¶: msgpack portable format.

class pyranha.compression[source]¶

Compression format.

The members of this class identify the compression formats that can be used when saving/loading to/from disk symbolic objects via pyranha.save_file() and pyranha.load_file(). The compression formats are available only if Piranha was compiled with the corresponding optional compression options enabled.

bzip2 = pyranha._core.compression.bzip2¶: bzip2 compression.

gzip = pyranha._core.compression.gzip¶: gzip compression.

none = pyranha._core.compression.none¶: No compression.

zlib = pyranha._core.compression.zlib¶: zlib compression.

pyranha.save_file(obj, name, df=None, cf=None)[source]¶

Save to file.

This function will save the symbolic object obj to the file called name using df as data format and cf as compression format. The possible values for df and cf are listed in the pyranha.data_format and pyranha.compression classes respectively.

If df and cf are both None, then the data and compression formats are inferred from the filename:

if name ends in one of the suffixes .bz2, .gz or .zip then the suffix is removed for further considerations from name, and the corresponding pyranha.compression format is assumed (respectively, pyranha.compression.bzip2, pyranha.compression.gzip and pyranha.compression.zlib). Otherwise, pyranha.compression.none is assumed;
after the removal of any compression suffix, the extension of name is examined again: if the extension is one of .boostp, .boostb, .mpackp and .mpackb, then the corresponding data format is selected (respectively, pyranha.data_format.boost_portable, pyranha.data_format.boost_binary, pyranha.data_format.msgpack_portable, pyranha.data_format.msgpack_binary). Othwewise, an error will be produced.

Examples of file names:

foo.boostb.bz2 deduces pyranha.data_format.boost_binary and pyranha.compression.bzip2;
foo.mpackp deduces pyranha.data_format.msgpack_portable and pyranha.compression.none;
foo.txt produces an error;
foo.bz2 produces an error.

Parameters:	obj (a supported symbolic type) – the symbolic object that will be saved to file name (`str`) – the file name df – the desired data format (see `pyranha.data_format`) cf – the desired compression format (see `pyranha.compression`)
Raises:	`TypeError` if the file name is not a string
Raises:	`ValueError` if only one of df and cf is `None`
Raises:	any exception raised by the invoked low-level C++ function

>>> from pyranha.types import polynomial, rational, k_monomial
>>> import tempfile, os
>>> x = polynomial[rational,k_monomial]()('x')
>>> p = (x + 1)**10
>>> f = tempfile.NamedTemporaryFile(delete=False) # Generate a temporary file name
>>> f.close()
>>> save_file(p, f.name, data_format.boost_portable, compression.none)
>>> p_load = type(p)()
>>> load_file(p_load, f.name, data_format.boost_portable, compression.none)
>>> p_load == p
True
>>> save_file(p, 123) 
Traceback (most recent call last):
  ...
TypeError: the file name must be a string
>>> save_file(p, "foo", df = data_format.boost_portable) 
Traceback (most recent call last):
  ...
ValueError: the data format was provided but the compression format was not
>>> os.remove(f.name) # Cleanup

pyranha.load_file(obj, name, df=None, cf=None)[source]¶

Load from file.

This function will load into the symbolic object obj the data stored in the file called name using df as data format and cf as compression format. The possible values for df and cf are listed in the pyranha.data_format and pyranha.compression classes respectively.

If df and cf are both None, then the data and compression formats are inferred from the filename (see pyranha.save_file() for a detailed explanation and examples).

Parameters:	obj (a supported symbolic type) – the symbolic object into which the file’s data will be loaded name (`str`) – the source file name df – the desired data format (see `pyranha.data_format`) cf – the desired compression format (see `pyranha.compression`)
Raises:	`TypeError` if the file name is not a string
Raises:	`ValueError` if only one of df and cf is `None`
Raises:	any exception raised by the invoked low-level C++ function

pyranha¶

`pyranha`¶