`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). 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

fileobjsNone or tuple, optional: If not None, the file objects to register.
locus_in_outputbool, 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) 
...
>>> Optimizer(..., io_manager=io_m) 
...
>>> 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") 
# Don't supply a value for io_manager:
>>> AnotherOptimizer(...) 

Attributes

errunitint: The value denoting the Engine error unit. This attribute should be considered read only. By default errunit is associated with sys.stderr.
advunitint: 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

fileobjstuple: 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

fileobjstuple: 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

fileobjfile 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

fileobjfile 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

fileobjfile 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: 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.

NAG and Python

Return to Front

`base.utils` Submodule¶

base.utils Submodule¶

`base.utils` Submodule¶