base.utils Submodule

Base utilities for the naginterfaces package.

class naginterfaces.base.utils.EngineIntCType[source]

Class for the ctypes integer type that is compatible with the NAG Library Engine’s integer type.

The base class is platform dependent.

Examples

>>> from naginterfaces.base import utils
>>> i = utils.EngineIntCType(42)
class naginterfaces.base.utils.EngineIntNumPyType[source]

Class for the NumPy integer type that is compatible with the NAG Library Engine’s integer type.

The base class is platform dependent.

Examples

>>> import numpy as np
>>> from naginterfaces.base import utils
>>> i = np.array([42, 53], dtype=utils.EngineIntNumPyType)
class naginterfaces.base.utils.FileObjManager(fileobjs=None, locus_in_output=True)[source]

Bases: object

Class for translating between Python file objects and NAG Library Engine I/O units.

NAG Engine I/O units are roughly synonymous with Unix file descriptors. File objects may be registered with I/O units using the instance initializer or the register() method. Convenience methods register_to_errunit() and register_to_advunit() are supplied to associate file objects with the Engine error unit (analogous to standard error, stderr) and the Engine advisory unit (analogous to standard output, stdout), respectively.

A Python file object is considered valid for use with this class if it has a fileno method returning its underlying file descriptor. In particular, you may use any concrete subclass of io.IOBase (including the file attribute of a file object returned by tempfile.NamedTemporaryFile), or file objects in Python 2. Naturally, the object must also have read/readline and write methods.

Resource management (opening/closing/deleting/… files) remains the reponsibility of the caller. In particular, objects to be used for output streams must have been opened for writing (mut. mut. for objects to be used for input) before their associated units are used by the Engine.

To communicate I/O unit numbers to the NAG Engine the unit_from_fileobj() method must be used. This maps a (registered) file object to a valid unit number.

Writes requested from the Engine to a unit number that does not have a file object associated with it will fall back to being sent to sys.stdout.

By default written data is prefixed with the name of the calling NAG Python function. This behaviour can be disabled when constructing an instance by using the initializer’s locus_in_output argument.

Reads requested by the Engine from a unit number that does not have a file object associated with it will cause NagOSError to be raised.

File objects may be removed from the class’s registry of I/O units by calling the deregister() method.

The special nature of the Engine advisory and error units means that these have persistent file-object associations; they are not affected by a call to deregister. The methods deregister_errunit() and deregister_advunit() are available to restore the associations with sys.stderr and sys.stdout, respectively.

A module-level instance of this class called GLOBAL_IO_MANAGER is supplied for convenience. This is queried as the fallback I/O manager whenever the Engine requires an I/O manager but one has not been explicitly supplied to the calling Python function. It is constructed using the initializer’s default argument set: in particular, prefixing of output data with NAG Python function names is enabled.

Parameters:
fileobjs : None or tuple, optional

If not None, the file objects to register.

locus_in_output : bool, optional

Controls whether output managed by this instance is prefixed with the name of the calling NAG Python function.

Raises:
NagTypeError

fileobjs is neither None nor an instance of tuple.

NagOSError

An element of the fileobjs tuple is not a valid file-object instance.

See also

naginterfaces.library.examples.opt.handle_solve_bounds_foas_ex.main()
This example uses a FileObjManager.

Examples

To send monitoring from a (fictional) optimization function to a temporary file:

>>> import os
>>> import tempfile
>>> t_fd, t_path = tempfile.mkstemp()
>>> f1 = open(t_path, 'w')
>>> io_m = FileObjManager((f1,))
>>> io_m_unit = io_m.unit_from_fileobj(f1)
>>> OptimizerOptionSet("Monitoring File", io_m_unit) # doctest: +SKIP
...
>>> Optimizer(..., io_manager=io_m) # doctest: +SKIP
...
>>> f1.close()
>>> os.close(t_fd)
...
>>> os.unlink(t_path)

To display iteration statistics from another (fictional) optimization function, in which the statistics are documented as being sent to the advisory unit, delegating handling to GLOBAL_IO_MANAGER:

>>> AnotherOptimizerOptionSet("Print Level = 1") # doctest: +SKIP
# Don't supply a value for io_manager:
>>> AnotherOptimizer(...) # doctest: +SKIP
Attributes:
errunit : int

The value denoting the Engine error unit. This attribute should be considered read only. By default errunit is associated with sys.stderr.

advunit : int

The value denoting the Engine advisory unit. This attribute should be considered read only. By default advunit is associated with sys.stdout.

deregister(fileobjs)[source]

Deregister the supplied file objects from this manager instance.

Parameters:
fileobjs : tuple

The file objects to deregister.

Raises:
NagTypeError

fileobjs is not an instance of tuple.

deregister_advunit()[source]

Remove the current association for the Engine advisory unit and restore it to sys.stdout.

deregister_errunit()[source]

Remove the current association for the Engine error unit and restore it to sys.stderr.

register(fileobjs)[source]

Register the supplied file objects with this manager instance.

Parameters:
fileobjs : tuple

The file objects to register.

Raises:
NagTypeError

fileobjs is not an instance of tuple.

NagOSError

An element of the fileobjs tuple is not a valid file-object instance.

An element of the fileobjs tuple does not use a file descriptor.

register_to_advunit(fileobj)[source]

Register the supplied file object with the NAG Library Engine advisory output unit (equivalent to stdout).

Parameters:
fileobj : file object

The file object to register.

Raises:
NagOSError

fileobj is not a valid file-object instance.

fileobj does not use a file descriptor.

register_to_errunit(fileobj)[source]

Register the supplied file object with the NAG Library Engine error output unit (equivalent to stderr).

Parameters:
fileobj : file object

The file object to register.

Raises:
NagOSError

fileobj is not a valid file-object instance.

fileobj does not use a file descriptor.

unit_from_fileobj(fileobj)[source]

Return a NAG Library Engine unit number for the input file object.

Parameters:
fileobj : file object

The file object to query. It is registered with this manager instance if it has not already been.

Returns:
int

The NAG Engine unit number corresponding to fileobj.

Raises:
NagOSError

fileobj is not a valid file-object instance.

fileobj does not use a file descriptor.

naginterfaces.base.utils.GLOBAL_IO_MANAGER = <naginterfaces.base.utils.FileObjManager object>

The fallback I/O manager, used whenever the NAG Library Engine requires an I/O manager but one has not been explicitly supplied to the calling Python function. It has been constructed such that prefixing of output data with NAG Python function names is enabled.

class naginterfaces.base.utils.Handle[source]

Bases: ctypes.c_void_p

Class for communication handles in the NAG Library Engine.

Overrides __copy__.

Overrides __deepcopy__.

Raises:
NagAttributeError

Shallow or deep copy was requested; these operations are prohibited for this class.

See also

naginterfaces.library.examples.blgm.lm_formula_ex.main()
This example uses Handle instances.
naginterfaces.base.utils.NAG_FROBENIUS_NORM = 174

A named constant for use with certain functions in the blast module.

naginterfaces.base.utils.NAG_INF_NORM = 175

A named constant for use with certain functions in the blast module.

naginterfaces.base.utils.NAG_MAX_NORM = 177

A named constant for use with certain functions in the blast module.

naginterfaces.base.utils.NAG_ONE_NORM = 171

A named constant for use with certain functions in the blast module.

naginterfaces.base.utils.NAG_TWO_NORM = 173

A named constant for use with certain functions in the blast module.

exception naginterfaces.base.utils.NagAlgorithmicMajorWarning(locus, msg)[source]

Bases: naginterfaces.base.utils.NagAlgorithmicWarning

Concrete class for major warnings from NAG wrappers that were identified by the NAG Library Engine.

exception naginterfaces.base.utils.NagAlgorithmicWarning(locus, msg)[source]

Bases: naginterfaces.base.utils.NagWarning

Concrete class for warnings from NAG wrappers that were identified by the NAG Library Engine.

exception naginterfaces.base.utils.NagAttributeError(locus, msg)[source]

Bases: naginterfaces.base.utils.NagException, AttributeError

Concrete class for attribute errors from NAG wrappers.

exception naginterfaces.base.utils.NagCallbackTerminateWarning(locus, msg)[source]

Bases: naginterfaces.base.utils.NagAlgorithmicWarning

Concrete class for warnings when early termination from a callback was triggered by the user.

Attributes:
cb_excs : list of UserCallbackTerminate

The original exception(s) raised by the user.

exception naginterfaces.base.utils.NagDeprecatedWarning(locus, msg)[source]

Bases: naginterfaces.base.utils.NagWarning

Concrete class for warnings about NAG wrappers that are deprecated.

This category is not suppressed by default.

exception naginterfaces.base.utils.NagException(locus, msg)[source]

Bases: Exception

Base class for errors from this package.

Notes

Concrete subclasses NagLicenceError and NagMemoryError are potential exceptions that may be raised by any function in the naginterfaces package.

Attributes:
errno : int or None

When a call to the underlying NAG Library Engine flags an error or warning, this attribute is set to an integer identifier for the exit case. The value may be used to cross reference the failure in the corresponding NAG Library document for the routine in question. The __str__ representation of an exception having non-None errno will display a substring of the form code x[:y[,z]] in which the x integer is the same as the errno value (and where the y and z values, which may be absent, only have internal significance to NAG).

return_data : collections.namedtuple (nag_return_data) or None

When a call to the underlying NAG Engine flags a non-fatal warning and you have configured the Python warnings module to escalate NAG warnings to exceptions, this attribute is populated with the return arguments for the routine in question (in argument order). Thus after catching the warning you may access the routine’s return data via this attribute if desired. The tuple subclass - i.e., the type of this attribute - is named nag_return_data.

exception naginterfaces.base.utils.NagIndexError(locus, msg)[source]

Bases: naginterfaces.base.utils.NagException, IndexError

Concrete class for index errors from NAG wrappers.

exception naginterfaces.base.utils.NagKeyError(locus, msg)[source]

Bases: naginterfaces.base.utils.NagException, KeyError

Concrete class for key errors from NAG wrappers.

exception naginterfaces.base.utils.NagLicenceError(locus, msg)[source]

Bases: naginterfaces.base.utils.NagException

Concrete class for licensing errors from NAG wrappers.

exception naginterfaces.base.utils.NagMemoryError(locus, msg)[source]

Bases: naginterfaces.base.utils.NagException, MemoryError

Concrete class for allocation errors from NAG wrappers.

exception naginterfaces.base.utils.NagNotImplementedError(locus, msg)[source]

Bases: naginterfaces.base.utils.NagException, NotImplementedError

Concrete class for not-implemented errors from NAG wrappers.

exception naginterfaces.base.utils.NagOSError(locus, msg)[source]

Bases: naginterfaces.base.utils.NagException, OSError

Concrete class for OS errors from NAG wrappers.

exception naginterfaces.base.utils.NagOverflowError(locus, msg)[source]

Bases: naginterfaces.base.utils.NagException, OverflowError

Concrete class for overflow errors from NAG wrappers.

exception naginterfaces.base.utils.NagShapeError(locus, msg)[source]

Bases: naginterfaces.base.utils.NagValueError

Concrete class for shape errors from NAG wrappers.

exception naginterfaces.base.utils.NagTypeError(locus, msg)[source]

Bases: naginterfaces.base.utils.NagException, TypeError

Concrete class for type errors from NAG wrappers.

exception naginterfaces.base.utils.NagValueError(locus, msg)[source]

Bases: naginterfaces.base.utils.NagException, ValueError

Concrete class for value errors from NAG wrappers.

exception naginterfaces.base.utils.NagWarning(locus, msg)[source]

Bases: naginterfaces.base.utils.NagException, Warning

Base class for warnings from NAG wrappers.

As a subclass of the Python Warning class the behaviour of a NagWarning can be controlled using the methods in the core warnings module.

See also

naginterfaces.library.examples.glopt.nlp_multistart_sqp_lsq_ex.main()
This example catches a NagAlgorithmicWarning and retrieves some of its return_data.
naginterfaces.library.examples.roots.sys_func_rcomm_ex.main()
This example promotes instances of NagAlgorithmicWarning to exceptions.

Examples

To escalate occurrences of NagAlgorithmicWarning to exceptions and to never show occurrences of NagWithdrawalWarning (which would not be recommended in practice):

>>> import warnings
>>> from naginterfaces.base import utils
>>> warnings.simplefilter('error', utils.NagAlgorithmicWarning)
>>> warnings.simplefilter('ignore', utils.NagWithdrawalWarning)

Any promoted NagAlgorithmicWarning exits can then be caught and their errno and return_data attributes accessed as required:

>>> try: # doctest: +SKIP
...    some_nag_call(...)
... except NagAlgorithmicWarning as exc:
...    if exc.errno == xyz:
...        look at exc.return_data
exception naginterfaces.base.utils.NagWithdrawalWarning(locus, msg)[source]

Bases: naginterfaces.base.utils.NagDeprecatedWarning

Concrete class for warnings about NAG wrappers that are scheduled for withdrawal.

This category is not suppressed by default.

exception naginterfaces.base.utils.UserCallbackTerminate[source]

Bases: Exception

Concrete class for user-raised callback termination requests.