pyharm 0.4.11__cp315-cp315-win_amd64.whl

pyharm/__init__.py

@@ -0,0 +1,39 @@
+"""
+PyHarm is a Python wrapper for CHarm.
+"""
+
+
+# start delvewheel patch
+def _delvewheel_patch_1_13_0():
+    import os
+    if os.path.isdir(libs_dir := os.path.abspath(os.path.join(os.path.dirname(__file__), os.pardir, 'pyharm.libs'))):
+        os.add_dll_directory(libs_dir)
+
+
+_delvewheel_patch_1_13_0()
+del _delvewheel_patch_1_13_0
+# end delvewheel patch
+
+import os as _os
+from ._lib import _load_lib
+
+# Name of the shared CHarm library to load
+_libcharmname = 'libcharm'
+
+# Directory of "_libcharmname"
+_libcharmdir = _os.path.join(_os.path.dirname(__file__), '')
+
+# Load the shared CHarm library
+_libcharm = _load_lib(_libcharmdir, _libcharmname)
+
+# Prefix to be added to the CHarm function names.  Depends on the format of
+# floating point numbers used to compile CHarm (single or double precision).
+_CHARM = 'charm_'
+
+# Prefix to be added to the PyHarm functions when calling "__repr__" methods
+_pyharm = 'pyharm'
+
+# The "err" module is intentionally not imported, as users do not interact with
+# it in PyHarm.
+from . import crd, glob, gfm, integ, leg, misc, sha, shc, shs
+__all__ = ['crd', 'glob', 'gfm', 'integ', 'leg', 'misc', 'sha', 'shc', 'shs']

pyharm/_check_types.py

@@ -0,0 +1,177 @@
+"""
+Internal checks of data types passed by users to PyHarm.
+"""
+
+
+import numpy as _np
+from ._data_types import _pyharm_ints, _pyharm_flt_all, _pyharm_flt
+
+
+def _check_int_scalar(x, s):
+    """
+    Checks whether "x" is an instance of one of the classes in `_pyharm_ints`
+    and if so, whether it is a scalar in order to represent the quantity named
+    `s`.
+
+    Parameters
+    ----------
+    x : any data type
+        Data to check
+    s : str
+        String with the name of the data that is being checked with the first
+        letter being uppercase (e.g. 'The \'crd_type\' variable').
+    """
+
+    if not isinstance(x, _pyharm_ints):
+        msg  = f'{s} must be an instance of one of the following classes: '
+        msg += f'{_pyharm_ints}.'
+        raise TypeError(msg)
+
+    if not _np.isscalar(x):
+        raise ValueError(f'{s} must be a scalar.')
+
+    return
+
+
+def _check_nonneg_int_scalar(x, s):
+    """
+    The same as `_check_int_scalar` but additionally checks whether `x` is
+    non-negative.
+
+    Parameters
+    ----------
+    x : any data type
+        Data to check
+    s : str
+        String with the name of the data that is being checked with the first
+        letter being uppercase (e.g. 'The \'crd_type\' variable').
+    """
+
+    _check_int_scalar(x, s)
+    if x < 0:
+        raise ValueError(f'{s} must not be negative.')
+
+    return
+
+
+def _check_flt_scalar(x, s):
+    """
+    Checks whether `x` is an instance of one of the classes in
+    `_pyharm_flt_all` and if so, whether it is a scalar to represent
+    the quantity named `s`.
+
+    Parameters
+    ----------
+    x : any data type
+        Data to check
+    s : str
+        String with the name of the data that is being checked with the first
+        letter being uppercase (e.g. 'Scaling parameter').
+    """
+
+    if not isinstance(x, _pyharm_flt_all):
+        msg  = f'{s} must be an instance of one of the following classes: '
+        msg += f'{_pyharm_flt_all}.'
+        raise TypeError(msg)
+
+    if not _np.isscalar(x):
+        raise ValueError(f'{s} must be a scalar.')
+
+    return
+
+
+def _check_deg_ord(x, do):
+    """
+    Checks whether `x` satisfies all conditions to represent harmonic degree
+    (`do == 'degree'`) or harmonic order (`do == 'order'`).
+
+    Parameters
+    ----------
+    x : any data type
+    do : str
+        Either 'degree' or 'order'
+    """
+
+    # Check whether "x" is of a correct integer class and whether it is
+    # a scalar
+    _check_int_scalar(x, f'Spherical harmonic {do}')
+    if do != 'degree' and do != 'order':
+        msg  = f'The \'do\' variable must be set either to \'degree\' '
+        msg += f'or to \'order\'.'
+        raise ValueError(msg)
+
+    if x < 0:
+        msg  = f'Spherical harmonic {do} cannot be smaller than zero.'
+        raise ValueError(msg)
+
+    return
+
+
+def _check_radius(x):
+    """
+    Checks whether `x` satisfies all conditions to represent spherical radius.
+
+    Parameters
+    ----------
+    x : any data type
+    """
+
+    _check_flt_scalar(x, 'Spherical radius')
+
+    if x <= 0.0:
+        raise ValueError('Spherical radius must be larger than zero.')
+
+    return
+
+
+def _check_flt_ndarray(x, n, s):
+    """
+    Checks whether `x` satisfies all conditions to represent an nD floating
+    point numpy array that can safely enter CHarm in order to represent
+    quantity named `s`.
+
+    Parameters
+    ----------
+    x : any data type
+        Object to be checked
+    n : integer
+        Required number of dimensions of the nD floating point array
+    s : str
+        String with the name of the object that is being checked with the first
+        letter being uppercase (e.g., 'Latitudes')
+    """
+
+    # Must be a "_np.ndarray"
+    if not isinstance(x, _np.ndarray):
+        msg  = f'{s} must be an instance of one of the following classes: '
+        msg += f'{_np.ndarray}.'
+        raise TypeError(msg)
+
+    # Must be of the correct "dtype"
+    if x.dtype != _pyharm_flt:
+        msg = f'{s} must be of the following \'dtype\': {_pyharm_flt}.'
+        raise ValueError(msg)
+
+    # Must have the correct number of dimensions
+    if x.ndim != n:
+        msg = f'{s} must be of the following dimension: \'ndim={n}\'.'
+        raise ValueError(msg)
+
+    # Must be C-contiguous
+    if not x.flags.c_contiguous:
+        msg  = f'{s} must be C-contiguous in memory (see the \'order\' flag '
+        msg += f'of numpy arrays).'
+        raise ValueError(msg)
+
+    return
+
+
+def _check_pointer(pointer, func_name, lib_name):
+
+    if not pointer:
+        msg  = f'Function call to \'{func_name}\' from the CHarm library '
+        msg += f'\'{lib_name}\' returned a NULL pointer.'
+        raise ValueError(msg)
+
+    return
+

pyharm/_constants.py

@@ -0,0 +1,62 @@
+"""
+Generated automatically.  Do not modify!
+"""
+
+_globals = {
+    'CHARM_SHC__NMAX_MODEL': -18446744073709551615,
+    'CHARM_SHC__NMAX_ERROR': -18446744073709551614,
+    'CHARM_SHC_WRITE_N': 0,
+    'CHARM_SHC_WRITE_M': 1,
+    'CHARM_CRD_CELL_GRID': -2,
+    'CHARM_CRD_CELL_SCATTERED': -1,
+    'CHARM_CRD_POINT_SCATTERED': 1,
+    'CHARM_CRD_POINT_GRID': 2,
+    'CHARM_CRD_POINT_GRID_GL': 3,
+    'CHARM_CRD_POINT_GRID_DH1': 4,
+    'CHARM_CRD_POINT_GRID_DH2': 5,
+    'CHARM_VERSION_MAJOR': 0,
+    'CHARM_VERSION_MINOR': 4,
+    'CHARM_VERSION_PATCH': 11,
+    'CHARM_VERSION_STRING': '0.4.11',
+    'CHARM_WITH_MPFR': 1,
+    'CHARM_WITH_MPI': 1,
+    'CHARM_ERR_MAX_FILE': 4096,
+    'CHARM_ERR_MAX_FUNC': 256,
+    'CHARM_ERR_MAX_MSG': 4096,
+    'CHARM_ERR_MAX_LEVEL': 10,
+    'CHARM_ERR_MALLOC_FAILURE': 'Memory allocation failure.',
+    'CHARM_ERR_FFTW_INIT_FAILURE': 'FFTW failed to initialize OpenMP threads.',
+    'CHARM_FAILURE': -1,
+    'CHARM_SUCCESS': 0,
+    'CHARM_EMEM': 1,
+    'CHARM_EFUNCARG': 2,
+    'CHARM_EFILEIO': 3,
+    'CHARM_EFFTWINIT': 4,
+    'CHARM_EMPIPROCESS': 5,
+    'CHARM_SHA_CELL_AQ': 0,
+    'CHARM_LEG_PMNJ': 0,
+    'CHARM_LEG_PMJN': 1,
+    'CHARM_GFM_Q00': 0,
+    'CHARM_GFM_Q10': 10,
+    'CHARM_GFM_Q11': 11,
+    'CHARM_GFM_Q20': 20,
+    'CHARM_GFM_Q21': 21,
+    'CHARM_GFM_Q22': 22,
+    'CHARM_GFM_NEAR_ZONE': 1,
+    'CHARM_GFM_FAR_ZONE': -1,
+    'CHARM_EXTERN': None,
+    'CHARM_CDECL': None,
+    'GRAD_0': 0,
+    'GRAD_1': -1,
+    'GRAD_2': -2,
+    'GRAD_LL': 0,
+    'GRAD_LR': 1,
+    'GRAD_LP': 2,
+    'GRAD_RR': 3,
+    'GRAD_RP': 4,
+    'GRAD_PP': 5,
+    'GRAD_P': 2,
+    'GRAD_L': 0,
+    'GRAD_R': 1,
+}
+

pyharm/_data_types.py

@@ -0,0 +1,46 @@
+"""
+Defines data types that:
+
+    * users can pass to PyHarm,
+    * PyHarm passes to CHarm, and
+    * CHarm returns to PyHarm.
+"""
+
+import numpy as _np
+import ctypes as _ct
+
+# Data types that user can pass to PyHarm to represent integers
+_pyharm_ints = (int, _np.integer)
+
+# Data types that user can pass to PyHarm to represent floating point
+# numbers.  Note that "PY_FLOAT" already contains the comma, so no comma
+# between "float," and "_np.float64".
+_pyharm_flt_all = (float, _np.float64,) + _pyharm_ints
+
+# Floating point data types for numpy ndarrays.  A *single* data type must be
+# defined here!  The reason is that it avoids making any internal copies of
+# data entered by the user, as this could be a problem for large arrays.
+_pyharm_flt = _np.float64
+
+# This is the data type, to which PyHarm converts the C's "double" (or "float"
+# if in single precision) returned by CHarm
+_charm_flt = _np.float64
+
+# C's "int" entering CHarm
+_ct_int = _ct.c_int
+
+# C's "unsigned int" entering CHarm
+_ct_uint = _ct.c_uint
+
+# C's "size_t" entering CHarm
+_ct_size_t = _ct.c_size_t
+
+# C's "long int" entering CHarm
+_ct_long = _ct.c_long
+
+# C's "unsigned long int" entering CHarm
+_ct_ulong = _ct.c_ulong
+
+# C's "double" (or "float" if in single precision) entering CHarm
+_ct_flt = _ct.c_double
+

pyharm/_encoding.py

@@ -0,0 +1,45 @@
+"""
+Defines default encoding for strings passed to CHarm and a routine returing
+ctype pointer to a Python string.
+"""
+
+# Default encoding
+_default_encoding = 'utf-8'
+
+# Default treatment of characters outside "_default_encoding" when calling the
+# "decode" method on strings of the "bytes" class
+_default_encoding_errors = 'replace'
+
+
+import ctypes as _ct
+
+
+def _str_ptr(string, encoding=_default_encoding):
+    """
+    Returns a ctypes pointer to `string` encoded with `encoding`.
+    """
+
+    if isinstance(string, str):
+        return _ct.create_string_buffer(string.encode(encoding))
+    elif string is None:
+        return None
+    else:
+        raise ValueError('\'string\' must be of \'str\' type or \'None\'.')
+
+
+def _bytes_decode(string,
+                  encoding=_default_encoding,
+                  errors=_default_encoding_errors):
+    """
+    Returns `str` by encoding `string` of class `bytes` using
+    `_default_encoding` and treating encoding errors by
+    `_default_encoding_errors`.
+    """
+
+    if isinstance(string, bytes):
+        return string.decode(encoding=_default_encoding,
+                             errors=_default_encoding_errors)
+    elif string is None:
+        return None
+    else:
+        raise ValueError('\'string\' must be of \'bytes\' type.')

pyharm/_err.py

@@ -0,0 +1,194 @@
+# Implements the "err" module of PyHarm.
+#
+# NOTE: Unlike in CHarm, users do *not* interact with the "err" module in
+# PyHarm!
+
+
+import ctypes as _ct
+from . import _libcharm, _libcharmname, _CHARM
+from ._get_module_constants import _get_module_constants
+from ._constants import _globals
+from ._data_types import _ct_int, _ct_size_t
+from ._check_types import _check_pointer
+from ._encoding import _bytes_decode
+
+
+# Get the module constants from "_constants.py" and add them to the module's
+# namespace
+_get_module_constants('CHARM_ERR_')
+
+
+# Character to represent the C's null character
+NULL_CHAR = '\0'
+
+
+class _Err(_ct.Structure):
+    """
+    Private class to represent the `charm_err` structure of CHarm.
+    """
+
+    _fields_ = [('level',       _ct_size_t),
+                ('file',        _ct.POINTER(_ct.POINTER(_ct.c_char))),
+                ('line',        _ct.POINTER(_ct_size_t)),
+                ('func',        _ct.POINTER(_ct.POINTER(_ct.c_char))),
+                ('code',        _ct_int),
+                ('msg',         _ct.POINTER(_ct.c_char)),
+                ('saturated', _ct.c_bool)]
+
+
+class CHarmError(Exception):
+    pass
+
+
+def init():
+    """
+    Creates an empty instance of the `_Err` class.
+
+    Returns
+    -------
+    out : _Err
+        An instance of the `_Err` class.
+    """
+
+    func          = _libcharm[_CHARM + 'err_init']
+    func.restype  = _ct.POINTER(_Err)
+    func.argtypes = None
+
+    err = func()
+    _check_pointer(err, _CHARM + 'err_init', _libcharmname)
+
+    return err
+
+
+def free(a):
+    """
+    Frees the memory associated with an instance `a` of the `_Err` class.
+
+    Parameters
+    ----------
+
+    a : _Err
+        An instance of the `_Err` class to be freed.
+    """
+
+    if a is not None:
+        func          = _libcharm[_CHARM + 'err_free']
+        func.restype  = None
+        func.argtypes = [_ct.POINTER(_Err)]
+        func(a)
+
+    return
+
+
+def isempty(a):
+    """
+    Returns `True` if an instance of the `_Err` class `a` is empty or `False`
+    otherwise.
+
+    Parameters
+    ----------
+    a : _Err
+        An instance of the `_Err` class to be checked
+
+    Returns
+    -------
+    out : bool
+        `True` if `a` is empty, `False` otherwise.
+    """
+
+    func          = _libcharm[_CHARM + 'err_isempty']
+    func.restype  = _ct.c_bool
+    func.argtypes = [_ct.POINTER(_Err)]
+
+    return func(a)
+
+
+def reset(a):
+    """
+    Resets an instance `a` of the `_Err` class.
+
+    Parameters
+    ----------
+    a : _Err
+        An instance of the `_Err` class to be reset.
+    """
+
+    func          = _libcharm[_CHARM + 'err_reset']
+    func.restype  = None
+    func.argtypes = [_ct.POINTER(_Err)]
+
+    func(a)
+
+    return
+
+
+def handler(a, terminate):
+    """
+    This is a Python implementation of the CHarm's `charm_err_handler`
+    function.  This Python implementation allows better error handling in
+    Python.
+
+    Parameters
+    ----------
+    a : _Err
+        An instance of the `_Err` class to be handled.
+    terminate : bool
+        If `True` and `a` is not empty, the execution of the program
+        terminates.  If `False` and `a` is not empty, the error is printed and
+        the program continues in code execution.  If `False` and `a` is empty,
+        nothing happens.
+    """
+
+    if isempty(a):
+        return
+
+    e = a.contents
+
+    err_msg  = f'\n'
+    err_msg += f'Error code: {e.code}                   ' \
+                'Traceback (most recent call last)\n'
+    err_msg += f'\n'
+
+    for l in range(e.level - 1, -1, -1):
+
+        f    = _bytes_decode(e.file[l][:MAX_FILE])
+        idx1 = f.find(NULL_CHAR)
+        if idx1 == -1:
+            raise ValueError(f'The \'file[{l}]\' string in the '
+                             f'\'{_CHARM}err\' structure that was passed by '
+                             f'CHarm to PyHarm does not contain the '
+                             f'null character.  Cannot read the CHarm error.')
+
+        func = _bytes_decode(e.func[l][:MAX_FUNC])
+        idx2 = func.find(NULL_CHAR)
+        if idx2 == -1:
+            raise ValueError(f'The \'func[{l}]\' string in the '
+                             f'\'{_CHARM}err\' structure that was passed by '
+                             f'CHarm to PyHarm does not contain the '
+                             f'null character.  Cannot read the CHarm error.')
+
+        err_msg += f'   File \'{f[:idx1]}\', line: {e.line[l]}, '
+        err_msg += f'function: \'{func[:idx2]}\'\n\n'
+
+    if e.saturated:
+        err_msg += '   Warning: The error structure is '
+        err_msg += 'saturated.  Most recent function calls may therefore '
+        err_msg += 'not be reported.\n'
+        err_msg += f'\n'
+
+    msg = _bytes_decode(e.msg[:MAX_MSG])
+    idx = msg.find(NULL_CHAR)
+    if idx == -1:
+        raise ValueError(f'The \'msg\' string in the '
+                         f'\'{_CHARM}err\' structure that was passed by '
+                         f'CHarm to PyHarm does not contain the '
+                         f'null character.  Cannot read the CHarm error.')
+    err_msg += f'Error message: {msg[:idx]}\n'
+
+    if terminate:
+        raise CHarmError(err_msg)
+    else:
+        print(err_msg)
+
+    return
+

pyharm/_formatting.py

@@ -0,0 +1,6 @@
+"""
+Defines default formatting when writting floating point numbers to text files.
+"""
+
+# Default formatting
+_default_formatting = '%0.18e'

pyharm/_get_empty_array.py

@@ -0,0 +1,17 @@
+import numpy as _np
+from ._data_types import _pyharm_flt
+
+
+def _get_empty_array():
+    """
+    Private function to return something that PyHarm considers to be an empty
+    numpy array.
+
+    Returns
+    -------
+    out : numpy floating point array
+        Empty numpy ndarray
+    """
+
+    return _np.array([], dtype=_pyharm_flt, order='C')
+

pyharm/_get_module_constants.py

@@ -0,0 +1,29 @@
+import sys
+from ._constants import _globals
+
+
+def _get_module_constants(prefix):
+    """
+    Private function to dynamically add global constants from the `_globals`
+    dictionary inside `_constants.py` to the module's namespace.  The variables
+    are added under a modified name following the pattern:
+
+        CHARM_CRD_CELLS_GRID --> CELLS_GRID
+
+    where `prefix = 'CHARM_CRD_'` is the input variable.
+
+    Parameters
+    ----------
+    prefix : str
+        Prefix to be removed from the keys in `_globals` before adding to the
+        module's namespace.  Should be, e.g., 'CHARM_CRD_', 'CHARM_SHA_', etc.
+    """
+
+    namespace = sys._getframe(1).f_globals
+
+    for name, value in _globals.items():
+        if name.startswith(prefix):
+            namespace[name[len(prefix):]] = value
+
+    return
+

pyharm/_lib.py

@@ -0,0 +1,29 @@
+import os
+import numpy as _np
+
+
+def _load_lib(libdir, libname):
+    """
+    Private function to load a shared library 'libname' from directory 
+    'libdir'.
+
+    Parameters
+    ----------
+    libdir : str
+        Path to the shared library
+    libname : str
+        Name of the shared library
+
+    Returns
+    -------
+    out : ctypes.CDLL
+        The CHarm shared library
+    """
+
+    try:
+        return _np.ctypeslib.load_library(libname, libdir)
+    except OSError:
+        fullpath = os.path.join(libdir, libname)
+        msg = f'Failed to load the shared library \'{fullpath}\'.'
+        raise OSError(msg)
+