apocharmm.error Namespace Reference

Provides Python status constants and native-error translation. More...

Classes
class	_StatusFunction
	Describes a mutable ctypes status-returning function object. More...
class	ApoCharmmError
	Represents one failed apoCHARMM native operation in Python. More...

Functions
None	check_status (int status, str context)
	Raises ApoCharmmError for a failing C ABI status.
None	configure_status_function (_StatusFunction function, Sequence[object] argtypes, str context)
	Configures a ctypes function to translate nonzero C ABI statuses.

Variables
int	APO_STATUS_OK = 0
	Indicates that a C ABI operation completed successfully.
int	APO_STATUS_INVALID_ARGUMENT = 1
	Indicates that a C ABI argument, pointer, size, or value was rejected.
int	APO_STATUS_RUNTIME_ERROR = 2
	Indicates an uncategorized native runtime or exception failure.
int	APO_STATUS_CUDA_ERROR = 3
	Indicates that a CUDA operation failed.
int	APO_STATUS_NOT_INITIALIZED = 4
	Indicates that required native state has not been initialized.
int	APO_STATUS_NOT_IMPLEMENTED = 5
	Indicates that a recognized native operation is not implemented.

Detailed Description

Provides Python status constants and native-error translation.

The public constants and ApoCharmmError are re-exported by the top-level apocharmm package. Native wrapper functions use configure_status_function() to convert nonzero C ABI statuses into one Python exception type while retaining the numeric status, operation context, and copied native diagnostic.

Function Documentation

check_status()

None apocharmm.error.check_status	(	int	status,
		str	context
	)

Raises ApoCharmmError for a failing C ABI status.

APO_STATUS_OK returns immediately without reading the native diagnostic. Every other integer causes the current thread's apo_last_error() pointer to be copied immediately. A NULL or empty C string uses the defined fallback; other bytes are decoded as UTF-8 with replacement for invalid sequences.

Parameters

[in]	status	Numeric C ABI status to inspect. Unknown nonzero values are preserved in the raised exception.
[in]	context	Python-facing operation description retained by the exception.

Returns

None when status is APO_STATUS_OK.

Exceptions

ApoCharmmError

If status is any nonzero value.

Postcondition

A raised exception owns Python text independent of the native diagnostic pointer's lifetime.

configure_status_function()

None apocharmm.error.configure_status_function	(	_StatusFunction	function,
		Sequence[object]	argtypes,
		str	context
	)

Configures a ctypes function to translate nonzero C ABI statuses.

The function's argtypes are replaced with a new list copied from argtypes, its restype is set to ctypes.c_int, and its errcheck callback is replaced. The callback returns a successful integer unchanged and delegates every nonzero result to check_status() using the retained operation context.

Parameters

[in,out]	function	Borrowed mutable ctypes function object. The object is configured in place and is not otherwise retained.
[in]	argtypes	Sequence of ctypes argument declarations. The sequence is copied to a list; the declaration objects themselves are retained by that list.
[in]	context	Python-facing operation description captured by the installed callback for as long as the function retains that callback.

Returns

None.

Postcondition

function has integer status conversion and automatic ApoCharmmError translation installed.