eon_relax_engine.h

Go to the documentation of this file.

/*
** This file is part of eOn.
**
** SPDX-License-Identifier: BSD-3-Clause
**
** Copyright (c) 2010--present, eOn Development Team
** All rights reserved.
**
** Repo:
** https://github.com/TheochemUI/eOn
*/
#pragma once
 
#include <stddef.h>
#include <stdint.h>
 
#ifdef __cplusplus
extern "C" {
#endif
 
#ifdef _WIN32
#if defined(EON_RELAX_STATIC)
#define EON_RELAX_API
#elif defined(EON_RELAX_ENGINE_BUILD)
#define EON_RELAX_API __declspec(dllexport)
#else
#define EON_RELAX_API __declspec(dllimport)
#endif
#else
#define EON_RELAX_API __attribute__((visibility("default")))
#endif
 
typedef struct EonRelaxEngine EonRelaxEngine;
 
#define EON_RELAX_ABI_MAJOR 2u
#define EON_RELAX_ABI_MINOR 1u

typedef struct {
  uint32_t major;
  uint32_t minor;
} eon_relax_version_t;
 
#define EON_RELAX_VERSION_INIT {EON_RELAX_ABI_MAJOR, EON_RELAX_ABI_MINOR}
 
typedef enum {
  EON_RELAX_KIND_INVALID = 0,
  EON_RELAX_KIND_NEB = 1,
  EON_RELAX_KIND_SADDLE = 2
} eon_relax_kind_t;
 
#define EON_RELAX_KIND_IS_KNOWN(k)                                             \
  ((k) == EON_RELAX_KIND_NEB || (k) == EON_RELAX_KIND_SADDLE)

typedef enum {
  EON_RELAX_OK = 0,
  EON_RELAX_NULL_ENGINE = -1,
  EON_RELAX_NULL_BAND = -2,
  EON_RELAX_NULL_SURFACE = -3,
  EON_RELAX_NULL_OUTCOME = -4,
  EON_RELAX_NULL_POSITIONS = -5,
  EON_RELAX_NULL_ATOMIC_NRS = -6,
  EON_RELAX_NULL_BOXES = -7,
  EON_RELAX_NULL_MODE = -8,
  EON_RELAX_BAND_TOO_SHORT = -9,
  EON_RELAX_NATOMS = -10,
  EON_RELAX_UNKNOWN_KIND = -11,
  EON_RELAX_UNKNOWN_STATUS = -12,
  EON_RELAX_CAPNP_ROOT = -13,
  EON_RELAX_SURFACE_FATAL = -15,
  EON_RELAX_SADDLE_NIMAGES = -17,
  EON_RELAX_BAND_SIZE = -18,
  EON_RELAX_ALLOC = -19,
  EON_RELAX_UNAVAILABLE = -21,
  EON_RELAX_INVALID_PARAMETER = -22,
  EON_RELAX_ABI_MISMATCH = -23
} eon_relax_rc_t;

typedef enum {
  EON_RELAX_NEB_GOOD = 0,
  EON_RELAX_NEB_INIT = 1,
  EON_RELAX_NEB_BAD_MAX_ITERATIONS = 2,
  EON_RELAX_NEB_RUNNING = 3,
  EON_RELAX_NEB_MAX_UNCERTAINTY = 4
} eon_relax_neb_status_t;
 
#define EON_RELAX_IMAGE_NONE INT64_C(-1)

typedef struct {
  eon_relax_version_t version;
  uint64_t flags;
  int64_t n_images;
  int64_t n_atoms;
  double *positions;
  const int32_t *atomic_nrs;
  const double *boxes;
  const int32_t *is_fixed;
  const double *mode;
  const int64_t *image_ids;
  const double *masses;
} eon_relax_band_t;

typedef struct {
  eon_relax_version_t version;
  uint64_t flags;
  int32_t kind;
  int32_t status;
  int64_t iterations;
  int64_t climbing_image;
  double max_force;
  uint64_t version_hash;
  uint64_t surface_epoch;
} eon_relax_outcome_t;

typedef struct {
  eon_relax_version_t version;
  uint64_t flags;
  int64_t n_images;
  int64_t n_atoms;
  const double *positions;
  const int32_t *atomic_nrs;
  const double *boxes;
  const int64_t *image_ids;
  double *energies;
  double *forces;
  double *variances;
  uint64_t *epoch_out;
} eon_relax_surface_request_t;

typedef int (*eon_relax_surface_fn)(void *user,
                                    eon_relax_surface_request_t *req);

EON_RELAX_API int eon_relax_abi_version(void);
EON_RELAX_API int eon_relax_available(void);
EON_RELAX_API int eon_relax_abi_stamp(eon_relax_version_t *out);
EON_RELAX_API const char *eon_relax_version_hash_str(void);
EON_RELAX_API uint64_t eon_relax_version_hash(void);

EON_RELAX_API EonRelaxEngine *eon_relax_create(const void *config,
                                               size_t config_len, char *errbuf,
                                               size_t errlen);
 
EON_RELAX_API int eon_relax_set_surface_epoch(EonRelaxEngine *eng,
                                              uint64_t epoch);
EON_RELAX_API int eon_relax_last_error(const EonRelaxEngine *eng);

EON_RELAX_API int eon_relax_run(EonRelaxEngine *eng, eon_relax_band_t *band,
                                eon_relax_surface_fn surface, void *user,
                                eon_relax_outcome_t *out);

EON_RELAX_API int eon_relax_step(EonRelaxEngine *eng, eon_relax_band_t *band,
                                 eon_relax_surface_fn surface, void *user,
                                 eon_relax_outcome_t *out);

EON_RELAX_API int eon_relax_reset(EonRelaxEngine *eng);
 
EON_RELAX_API void eon_relax_destroy(EonRelaxEngine *eng);

EON_RELAX_API const char *eon_relax_status_name(eon_relax_kind_t kind,
                                                int status);
 
#ifdef __cplusplus
}
#endif