fue 0.1.0__py3-none-any.whl

fue/__init__.py

@@ -0,0 +1,32 @@
+"""
+fue — Python interface to the FUE exact maximum likelihood estimation engine.
+
+Typical usage::
+
+    import fue
+
+    ts = fue.TimeSeries.from_array(data, freq=12, start=(1990, 1))
+
+    m = fue.Model(ts, ar=[[1]], ma=[[1]], d=1, D=1)
+    m.fit()
+    print(m.summary())
+
+    m.plot_residuals()
+    m.residuals.plot_acf()
+"""
+
+from .series import TimeSeries
+from .intervention import Intervention
+from .model import Model, FixedFreqFactor
+from .forecast import ForecastResult
+from .diagnostics import acf, pacf, jarque_bera, ljung_box
+from .inp import load, load_fuf
+from .report import write_out, write_fuf, write_fuf_out
+from .report_forecast import write_forecast_report
+from . import datasets
+
+__version__ = "0.1.0"
+__all__ = ["TimeSeries", "Intervention", "Model", "FixedFreqFactor",
+           "ForecastResult", "acf", "pacf", "jarque_bera", "ljung_box",
+           "load", "load_fuf", "write_out", "write_fuf", "write_fuf_out",
+           "write_forecast_report", "datasets"]

fue/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+main()

fue/_build_cffi.py

@@ -0,0 +1,174 @@
+"""
+cffi build script for the FUE estimation engine.
+
+Activated in pyproject.toml via:
+    cffi_modules = ["src/fue/_build_cffi.py:ffi"]
+
+This file is run at build time (pip install / python setup.py build_ext).
+It compiles csrc/fue_api.c + csrc/internal/*.c against GSL and produces
+the _fue_engine extension module imported by _engine.py at runtime.
+"""
+
+import os
+import sys
+import cffi
+
+# Compute paths relative to the project root (CWD during pip/setup.py build).
+# os.path.relpath normalises away the ".." components that confuse distutils.
+_THIS_DIR = os.path.dirname(os.path.abspath(__file__))
+_ROOT   = os.path.relpath(os.path.join(_THIS_DIR, "..", "..", "csrc"))
+_INTERN = os.path.join(_ROOT, "internal")
+
+# cffi cannot process C preprocessor directives (#define, #ifdef, etc.).
+# We provide a macro-expanded cdef string with literal values instead.
+# Macro values: FUE_MAX_DETVARS=64, FUE_MAX_FACTORS=8, FUE_MAX_POLYORD=16.
+_CDEF = """
+typedef struct {
+    int    type;
+    int    obs_index;
+    double harmonic;
+
+    int    nomega;
+    double omega[16];
+    int    omega_free[16];
+
+    int    ndelta;
+    double delta[16];
+    int    delta_free[16];
+
+    double *indicator_data;
+} FueIntervention;
+
+typedef struct {
+    int    order;
+    double coefs[16];
+    int    coef_free[16];
+} FueFactor;
+
+typedef struct {
+    int     nobs;
+    double *data;
+    int     sper;
+    int     numbering;
+    int     begyear;
+    int     begtime;
+
+    double  boxlam;
+    double  refactor;
+
+    int     nrdiff;
+    int     nadiff;
+
+    double  mu0;
+    int     estimate_mu;
+
+    int            ninterventions;
+    FueIntervention interventions[64];
+
+    int       nar1;
+    FueFactor ar1[8];
+
+    int       nar2;
+    FueFactor ar2[8];
+
+    int       nma1;
+    FueFactor ma1[8];
+
+    int       nma2;
+    FueFactor ma2[8];
+
+    int    nar1f;
+    double ar1f_freq[8];
+    double ar1f_coef[8];
+    int    ar1f_free[8];
+
+    int    nma1f;
+    double ma1f_freq[8];
+    double ma1f_coef[8];
+    int    ma1f_free[8];
+
+    int    ifadf[8];
+
+    int    maxits;
+    double grtol;
+    double sptol;
+    double xitol;
+    int    chkma;
+    int    eml;
+} FueModelSpec;
+
+typedef struct {
+    int     ifault;
+    int     npar;
+    double *params;
+    double *std_errors;
+    double *cov_matrix;
+    double *residuals;
+    int     nresiduals;
+    double  sigma2;
+    double  loglik;
+    double  aic;
+    double  bic;
+} FueResult;
+
+FueResult *fue_estimate(const FueModelSpec *spec);
+void       fue_defaults(FueModelSpec *spec);
+void       fue_result_free(FueResult *r);
+const char *fue_strerror(int ifault);
+"""
+
+_SOURCES = [
+    os.path.join(_ROOT, "fue_api.c"),
+    os.path.join(_INTERN, "elfvarma.c"),
+    os.path.join(_INTERN, "usmelard.c"),
+    os.path.join(_INTERN, "qnewtopt.c"),
+    os.path.join(_INTERN, "nlatools.c"),
+    os.path.join(_INTERN, "drvmlest.c"),
+]
+
+if sys.platform == "win32":
+    _libraries    = ["gsl", "gslcblas"]   # no -lm on Windows
+    _compile_args = ["/O2", "/W2"]
+    # conda-build sets LIBRARY_INC / LIBRARY_LIB; prefer those when present.
+    _lib_inc = os.environ.get("LIBRARY_INC")
+    _lib_lib = os.environ.get("LIBRARY_LIB")
+    if _lib_inc and _lib_lib:
+        _include_dirs = [_ROOT, _INTERN, _lib_inc]
+        _library_dirs = [_lib_lib]
+    else:
+        # GSL via vcpkg (x64-windows-static-md triplet) — used by cibuildwheel.
+        # Set GSL_ROOT to override the default vcpkg install prefix.
+        _vcpkg_default = os.path.join(
+            os.environ.get("VCPKG_INSTALLATION_ROOT", r"C:\vcpkg"),
+            "installed", "x64-windows-static-md",
+        )
+        _gsl_root     = os.environ.get("GSL_ROOT", _vcpkg_default)
+        _include_dirs = [_ROOT, _INTERN, os.path.join(_gsl_root, "include")]
+        _library_dirs = [os.path.join(_gsl_root, "lib")]
+else:
+    _libraries    = ["gsl", "gslcblas", "m"]
+    _compile_args = ["-O2", "-std=c99", "-Wall"]
+    # conda-build sets PREFIX to the environment where host deps are installed.
+    _prefix = os.environ.get("PREFIX")
+    if _prefix:
+        _include_dirs = [_ROOT, _INTERN, os.path.join(_prefix, "include")]
+        _library_dirs = [os.path.join(_prefix, "lib")]
+    else:
+        _include_dirs = [_ROOT, _INTERN]
+        _library_dirs = []
+
+ffi = cffi.FFI()
+ffi.cdef(_CDEF)
+
+ffi.set_source(
+    "fue._fue_engine",
+    r'#include "fue_api.h"',
+    sources=_SOURCES,
+    include_dirs=_include_dirs,
+    library_dirs=_library_dirs,
+    libraries=_libraries,
+    extra_compile_args=_compile_args,
+)
+
+if __name__ == "__main__":
+    ffi.compile(verbose=True)

fue/_engine.py

@@ -0,0 +1,130 @@
+"""
+Bridge between the Python Model API and the cffi-compiled C extension.
+
+Falls back to the pure-Python estimator (cast_us.estimate_py) when the
+C extension (_fue_engine) is not available.
+"""
+
+import numpy as np
+
+
+def estimate(model):
+    """
+    Estimate model parameters by exact ML.
+
+    Tries the C extension first; falls back to the pure-Python estimator
+    (scipy L-BFGS-B + elf_scalar) when the extension is not compiled.
+    """
+    try:
+        from fue._fue_engine import ffi, lib
+    except ImportError:
+        from .cast_us import estimate_py
+        return estimate_py(model)
+
+    spec = ffi.new("FueModelSpec *")
+    lib.fue_defaults(spec)
+
+    ts = model.series
+
+    # Keep the numpy array alive via ffi.from_buffer so spec.data stays valid.
+    _data = np.ascontiguousarray(ts.data, dtype=np.float64)
+    _data_buf = ffi.from_buffer("double[]", _data)
+
+    spec.nobs      = ts.nobs
+    spec.data      = _data_buf
+    spec.sper      = ts.freq if ts.freq > 0 else 1
+    spec.numbering = 1 if ts.numbering else 0
+    spec.begyear   = ts.start[0]
+    spec.begtime   = ts.start[1]
+
+    spec.boxlam      = model.boxlam
+    spec.refactor    = model.refactor
+    spec.nrdiff      = model.d
+    spec.nadiff      = model.D
+    spec.mu0         = model.mu0
+    spec.estimate_mu = 1 if model.estimate_mu else 0
+    spec.chkma       = 1 if model.chkma else 0
+    spec.eml         = 1 if model.eml else 0
+
+    def _fill_factors(spec_arr, factors, free_lists):
+        for i, factor in enumerate(factors):
+            spec_arr[i].order = len(factor)
+            free = free_lists[i] if free_lists is not None else None
+            for j, v in enumerate(factor):
+                spec_arr[i].coefs[j]     = v
+                spec_arr[i].coef_free[j] = (
+                    0 if (free is not None and not free[j]) else 1
+                )
+
+    spec.nar1 = len(model.ar);   _fill_factors(spec.ar1, model.ar,   model.ar_free)
+    spec.nma1 = len(model.ma);   _fill_factors(spec.ma1, model.ma,   model.ma_free)
+    spec.nar2 = len(model.ar_s); _fill_factors(spec.ar2, model.ar_s, model.ar_s_free)
+    spec.nma2 = len(model.ma_s); _fill_factors(spec.ma2, model.ma_s, model.ma_s_free)
+
+    for i, v in enumerate(model.ifadf[:8]):
+        spec.ifadf[i] = 1 if v else 0
+
+    spec.nar1f = len(model.ar_f)
+    for i, ff in enumerate(model.ar_f):
+        spec.ar1f_freq[i] = ff.freq
+        spec.ar1f_coef[i] = ff.coef
+        spec.ar1f_free[i] = 1 if ff.free else 0
+
+    spec.nma1f = len(model.ma_f)
+    for i, ff in enumerate(model.ma_f):
+        spec.ma1f_freq[i] = ff.freq
+        spec.ma1f_coef[i] = ff.coef
+        spec.ma1f_free[i] = 1 if ff.free else 0
+
+    spec.ninterventions = len(model.interventions)
+    # Custom indicator buffers must stay alive until fue_estimate returns.
+    _custom_bufs = []
+    for i, itv in enumerate(model.interventions):
+        spec.interventions[i].type      = itv.type_code
+        spec.interventions[i].obs_index = itv.at
+        spec.interventions[i].harmonic  = itv.harmonic
+        spec.interventions[i].nomega    = len(itv.omega)
+        for j, v in enumerate(itv.omega):
+            spec.interventions[i].omega[j]       = v
+            spec.interventions[i].omega_free[j]  = 1 if itv.omega_free[j] else 0
+        spec.interventions[i].ndelta = len(itv.delta)
+        for j, v in enumerate(itv.delta):
+            spec.interventions[i].delta[j]       = v
+            spec.interventions[i].delta_free[j]  = 1 if itv.delta_free[j] else 0
+        if itv.type == "custom" and itv.data is not None:
+            _arr = np.ascontiguousarray(itv.data, dtype=np.float64)
+            _buf = ffi.from_buffer("double[]", _arr)
+            spec.interventions[i].indicator_data = _buf
+            _custom_bufs.append((_arr, _buf))
+        else:
+            spec.interventions[i].indicator_data = ffi.NULL
+
+    # _data, _data_buf, and _custom_bufs remain alive until fue_estimate returns.
+    raw = lib.fue_estimate(spec)
+    if raw == ffi.NULL:
+        return {'ifault': -1, 'npar': 0, 'nresiduals': 0,
+                'sigma2': 0.0, 'loglik': 0.0, 'aic': 0.0, 'bic': 0.0,
+                'params': np.array([]), 'std_errors': np.array([]),
+                'cov_matrix': np.zeros((0, 0)), 'residuals': np.array([])}
+
+    n  = raw.npar
+    nr = raw.nresiduals
+    try:
+        data = {
+            'ifault':     raw.ifault,
+            'npar':       n,
+            'nresiduals': nr,
+            'sigma2':     raw.sigma2,
+            'loglik':     raw.loglik,
+            'aic':        raw.aic,
+            'bic':        raw.bic,
+            'params':     np.array([raw.params[i]     for i in range(n)],    dtype=float),
+            'std_errors': np.array([raw.std_errors[i] for i in range(n)],    dtype=float),
+            'cov_matrix': np.array([raw.cov_matrix[i] for i in range(n * n)],
+                                   dtype=float).reshape(n, n) if n > 0 else np.zeros((0, 0)),
+            'residuals':  np.array([raw.residuals[i]  for i in range(nr)],   dtype=float),
+        }
+    finally:
+        lib.fue_result_free(raw)
+
+    return data