nmWTAI-Platform/3rd/Pebi/include/accelwt_cpu.h

#ifndef ACCELWT_CPU_H
#define ACCELWT_CPU_H

#if defined(_WIN32) || defined(__CYGWIN__)
#  if defined(ACCELWT_CPU_STATIC_DEFINE)
#    define ACCELWT_CPU_API
#  elif defined(ACCELWT_CPU_BUILDING_LIBRARY)
#    define ACCELWT_CPU_API __declspec(dllexport)
#  else
#    define ACCELWT_CPU_API __declspec(dllimport)
#  endif
#elif defined(__GNUC__) && __GNUC__ >= 4
#  define ACCELWT_CPU_API __attribute__((visibility("default")))
#else
#  define ACCELWT_CPU_API
#endif

#ifdef __cplusplus
extern "C" {
#endif

#define ACCELWT_CPU_VERSION_MAJOR 3
#define ACCELWT_CPU_VERSION_MINOR 2
#define ACCELWT_CPU_VERSION_PATCH 0

/*
 * Persistent simulation session. Create one context for a fixed CSR sparsity
 * pattern, reuse it across accepted physical time steps, and destroy it when
 * the simulation ends. Keeping this object alive enables temporal history,
 * workspace reuse and lagged preconditioner refreshes.
 */
typedef struct AccelWTCPUContext AccelWTCPUContext;
typedef AccelWTCPUContext AccelWTCPUSession;

typedef enum AccelWTCPUStatus
{
    ACCELWT_CPU_SUCCESS = 0,
    ACCELWT_CPU_INVALID_ARGUMENT = 1,
    ACCELWT_CPU_INVALID_MATRIX = 2,
    ACCELWT_CPU_ALLOCATION_FAILED = 3,
    ACCELWT_CPU_SETUP_FAILED = 4,
    ACCELWT_CPU_NOT_READY = 5,
    ACCELWT_CPU_SOLVE_FAILED = 6,
    ACCELWT_CPU_NOT_CONVERGED = 7
} AccelWTCPUStatus;

typedef struct AccelWTCPUOptions
{
    int max_iterations;
    double relative_tolerance;
    double absolute_tolerance;
    int ilu_jacobi_iterations;
    int omp_threads;
    int use_initial_guess;
    /* Default: 1. Set to 0 to opt into experimental LU-split Jacobi. */
    int use_exact_triangular_solve;
    /*
     * Experimental four-thread block triangular application.
     * 0 keeps the mode selected above, 1 performs one block sweep and
     * 2 performs one cross-subdomain correction sweep. Requires omp_threads=4.
     */
    int block_triangular_sweeps;
} AccelWTCPUOptions;

typedef struct AccelWTCPUInfo
{
    int iterations;
    double final_rel_residual;
    double final_abs_residual;
    double setup_seconds;
    double solve_seconds;
    int status;
} AccelWTCPUInfo;

typedef struct AccelWTCPUPhaseInfo
{
    double initialization_seconds;
    double direction_update_seconds;
    double preconditioner_seconds;
    double spmv_reduction_seconds;
    double solution_update_seconds;
    double true_residual_seconds;
} AccelWTCPUPhaseInfo;

typedef enum AccelWTCPUTemporalGuess
{
    ACCELWT_CPU_TEMPORAL_GUESS_NONE = 0,
    ACCELWT_CPU_TEMPORAL_GUESS_PREVIOUS = 1,
    ACCELWT_CPU_TEMPORAL_GUESS_MR2 = 2
} AccelWTCPUTemporalGuess;

typedef struct AccelWTCPUTemporalOptions
{
    int initial_guess_policy;
    int enable_early_exit;
    int ilu_refresh_interval;
    int ilu_refresh_iteration_threshold;
} AccelWTCPUTemporalOptions;

typedef struct AccelWTCPUStepInfo
{
    AccelWTCPUInfo solve;
    int used_mr2;
    int history_depth;
    int early_exit;
    int refreshed_preconditioner;
    double predicted_relative_residual;
    double prediction_seconds;
    double update_seconds;
    double solve_seconds;
} AccelWTCPUStepInfo;

/*
 * Simple session configuration for time-dependent applications.
 * Zero values select library defaults. One ILU factor is used for
 * ilu_reuse_steps consecutive time steps; 1 rebuilds it every step.
 */
typedef struct AccelWTCPUSessionOptions
{
    int omp_threads;
    int ilu_reuse_steps;
} AccelWTCPUSessionOptions;

#define ACCELWT_CPU_SESSION_OPTIONS_DEFAULT {0, 5}

/*
 * Simple three-function interface. Passing NULL options uses the defaults,
 * including an ILU reuse window of five time steps.
 */
ACCELWT_CPU_API int accelwt_cpu_session_create(
    int n,
    int nnz,
    const int *row_ptr,
    const int *col_ind,
    const AccelWTCPUSessionOptions *options,
    AccelWTCPUSession **session);

ACCELWT_CPU_API int accelwt_cpu_session_solve(
    AccelWTCPUSession *session,
    const double *values,
    const double *rhs,
    double *x,
    AccelWTCPUStepInfo *info);

/* Accepts NULL. */
ACCELWT_CPU_API void accelwt_cpu_session_destroy(AccelWTCPUSession *session);

/* Returns the default options without allocating a solver context. */
ACCELWT_CPU_API void accelwt_cpu_default_options(AccelWTCPUOptions *options);
ACCELWT_CPU_API void accelwt_cpu_default_temporal_options(
    AccelWTCPUTemporalOptions *options);

ACCELWT_CPU_API const char *accelwt_cpu_backend_name(void);
ACCELWT_CPU_API const char *accelwt_cpu_status_string(int status);

/*
 * Creates a persistent solver for a zero-based, square CSR matrix pattern.
 * The row and column arrays are copied and may be released after this call.
 * Column indices must be strictly increasing within each row, and every row
 * must contain its diagonal entry.
 */
ACCELWT_CPU_API int accelwt_cpu_create(int n,
                                       int nnz,
                                       const int *row_ptr,
                                       const int *col_ind,
                                       const AccelWTCPUOptions *options,
                                       AccelWTCPUContext **context);

/*
 * Copies new CSR values into the context. A nonzero refresh_preconditioner
 * rebuilds ILU0. The first update always builds ILU0, regardless of the flag.
 */
ACCELWT_CPU_API int accelwt_cpu_update_matrix(AccelWTCPUContext *context,
                                              const double *values,
                                              int refresh_preconditioner,
                                              AccelWTCPUInfo *info);

/* Solves A*x=rhs. The context is not safe for concurrent solve calls. */
ACCELWT_CPU_API int accelwt_cpu_solve(AccelWTCPUContext *context,
                                      const double *rhs,
                                      double *x,
                                      AccelWTCPUInfo *info);

/*
 * Returns phase timings from the latest solve. Values are zero unless the
 * library was built with ACCELWT_CPU_PHASE_TIMING=ON.
 */
ACCELWT_CPU_API int accelwt_cpu_get_last_phase_info(
    const AccelWTCPUContext *context,
    AccelWTCPUPhaseInfo *info);

/*
 * Configures the library-owned temporal policy. The default is MR2 with
 * verified early exit and a five-step lagged-ILU interval.
 */
ACCELWT_CPU_API int accelwt_cpu_set_temporal_options(
    AccelWTCPUContext *context,
    const AccelWTCPUTemporalOptions *options);

/*
 * Updates A and solves one accepted physical time step while managing MR2
 * history, verified early exit and lagged-ILU refreshes inside the session.
 * This interface assumes one linear solve per accepted physical time step.
 * Do not call it for intermediate or rejected nonlinear iterations because a
 * successful call immediately commits x to the temporal history.
 */
ACCELWT_CPU_API int accelwt_cpu_solve_step(AccelWTCPUContext *context,
                                           const double *values,
                                           const double *rhs,
                                           double *x,
                                           AccelWTCPUStepInfo *info);

ACCELWT_CPU_API int accelwt_cpu_reset_temporal_history(
    AccelWTCPUContext *context);

/* Accepts NULL. */
ACCELWT_CPU_API void accelwt_cpu_destroy(AccelWTCPUContext *context);

#ifdef __cplusplus
}
#endif

#endif