minimage 0.1.4

/* Generated by cbindgen from src/capi.rs. Do not edit. */

/*
 * minimage C API.
 *
 * Memory ownership
 *   - Constructor calls write one mi_cell into a caller-owned out.
 *   - mi_displacement / mi_displacement_euclidean / mi_wrap_many /
 *     mi_dist2 / mi_dist2_many / mi_dist2_pairs / mi_dist2_ortho_diffs
 *     write into caller-owned buffers.
 *   - mi_reduce_pairs writes kept (i, j) pairs into caller-owned out
 *     and the count into out_n.
 *   - mi_last_error returns a thread-local pointer. Do not free. The
 *     pointer is invalid after the next mi_* call on the same thread.
 *     mi_version does not read or write the slot.
 *   - mi_version returns a process-static pointer. Do not free.
 *
 * Thread safety
 *   - Distinct cells and distance calls may run concurrently.
 *   - mi_last_error is a thread-local slot. Read it on the same thread
 *     that received a nonzero return.
 */


#ifndef MINIMAGE_H
#define MINIMAGE_H

#pragma once

/* Generated with cbindgen:0.29.4 */

/* Warning, this file is autogenerated by cbindgen. Don't modify this manually. */

#include <stdarg.h>
#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>
#include <stdlib.h>

/**
 * Periodic parallelepiped. Lattice vectors are a, b, c (same as vesin rows).
 */
typedef struct mi_cell {
    /**
     * Lattice vector a, x.
     */
    double ax;
    /**
     * Lattice vector a, y.
     */
    double ay;
    /**
     * Lattice vector a, z.
     */
    double az;
    /**
     * Lattice vector b, x.
     */
    double bx;
    /**
     * Lattice vector b, y.
     */
    double by;
    /**
     * Lattice vector b, z.
     */
    double bz;
    /**
     * Lattice vector c, x.
     */
    double cx;
    /**
     * Lattice vector c, y.
     */
    double cy;
    /**
     * Lattice vector c, z.
     */
    double cz;
    /**
     * Origin x.
     */
    double ox;
    /**
     * Origin y.
     */
    double oy;
    /**
     * Origin z.
     */
    double oz;
} mi_cell;

#ifdef __cplusplus
extern "C" {
#endif // __cplusplus

/**
 * Fill `out` from an ASE-style row-major 3x3 cell. `origin` may be NULL
 * (then zero).
 *
 * # Safety
 *
 * `rows` is nine readable doubles. `origin`, if non-null, is three
 * readable doubles. `out` is one writable `mi_cell`.
 */
int mi_cell_from_ase(const double *rows,
                     const double *origin,
                     struct mi_cell *out);

/**
 * Fill `out` from a CON 3x3 lattice (rows a, b, c).
 *
 * # Safety
 *
 * Same contract as [`mi_cell_from_ase`] with a null origin.
 */
int mi_cell_from_con(const double *rows, struct mi_cell *out);

/**
 * Fill `out` from CON lengths and angles in degrees.
 *
 * # Safety
 *
 * `boxl` and `angles_deg` are three readable doubles. `out` is one
 * writable `mi_cell`.
 */
int mi_cell_from_con_box(const double *boxl,
                         const double *angles_deg,
                         struct mi_cell *out);

/**
 * Fill `out` from LAMMPS `xlo xhi ylo yhi zlo zhi` and tilts.
 */
int mi_cell_from_lammps(double xlo,
                        double xhi,
                        double ylo,
                        double yhi,
                        double zlo,
                        double zhi,
                        double xy,
                        double xz,
                        double yz,
                        struct mi_cell *out);

/**
 * Fill `out` from dump bound spans, tilts, and bound lo.
 */
int mi_cell_from_lammps_bounds(double xspan,
                               double yspan,
                               double zspan,
                               double xy,
                               double xz,
                               double yz,
                               double xlo_b,
                               double ylo_b,
                               double zlo_b,
                               struct mi_cell *out);

/**
 * Fill `out` from lattice vectors a, b, c and an origin.
 *
 * # Safety
 *
 * `a`, `b`, `c`, `origin`, and `out` are non-null and point at three
 * doubles / one `mi_cell`.
 */
int mi_cell_from_vectors(const double *a,
                         const double *b,
                         const double *c,
                         const double *origin,
                         struct mi_cell *out);

/**
 * Fill `out` from a vesin 3x3 box (rows a, b, c).
 *
 * # Safety
 *
 * Same contract as [`mi_cell_from_con`].
 */
int mi_cell_from_vesin(const double *box_rows, struct mi_cell *out);

/**
 * Minimum-image displacement from `p` to `q` into `dr`.
 *
 * # Safety
 *
 * `simbox` is one `mi_cell`. `p`, `q`, and `dr` are three doubles.
 */
int mi_displacement(const struct mi_cell *simbox,
                    const double *p,
                    const double *q,
                    double *dr);

/**
 * Euclidean MIC: Smith half-altitude test, else the slicer on the
 * Selling superbasis, into `dr`.
 *
 * # Safety
 *
 * Same contract as [`mi_displacement`].
 */
int mi_displacement_euclidean(const struct mi_cell *simbox,
                              const double *p,
                              const double *q,
                              double *dr);

/**
 * Squared minimum-image distance from `p` to `q`.
 *
 * # Safety
 *
 * `simbox` is one `mi_cell`. `p` and `q` are three doubles. `out` is
 * one writable double.
 */
int mi_dist2(const struct mi_cell *simbox,
             const double *p,
             const double *q,
             double *out);

/**
 * Euclidean nearest-image squared distances from `p` to `n` packed
 * candidates: [`mi_displacement_euclidean`] per pair, bit for bit, with
 * one superbasis lookup per call and eight pairs per slicer pass.
 *
 * # Safety
 *
 * `qs` is `n * 3` doubles. `out` is `n` doubles.
 */
int mi_dist2_euclidean_many(const struct mi_cell *simbox,
                            const double *p,
                            const double *qs,
                            size_t n,
                            double *out);

/**
 * [`mi_dist2_euclidean_many`] for paired rows.
 *
 * # Safety
 *
 * `ps` and `qs` are `n * 3` doubles. `out` is `n` doubles.
 */
int mi_dist2_euclidean_pairs(const struct mi_cell *simbox,
                             const double *ps,
                             const double *qs,
                             size_t n,
                             double *out);

/**
 * [`mi_dist2_euclidean_pairs`] for pairs that persist across frames.
 * `images` is `n` rows of three `int32_t`: the cell-basis lattice shift
 * of each pair's image from the previous call, zeros to start, updated
 * in place. A pair whose stored image still lies in the Voronoi cell
 * skips the search; its distance equals the full search to rounding.
 *
 * # Safety
 *
 * `ps` and `qs` are `n * 3` doubles, `images` is `n * 3` writable
 * `int32_t`, and `out` is `n` doubles.
 */
int mi_dist2_euclidean_pairs_warm(const struct mi_cell *simbox,
                                  const double *ps,
                                  const double *qs,
                                  size_t n,
                                  int32_t *images,
                                  double *out);

/**
 * Squared engine-wrap distance between two fixed-point positions.
 *
 * # Safety
 *
 * `a` and `b` are three `uint64_t`. `out` is one writable double.
 */
int mi_dist2_fixed(const struct mi_cell *simbox,
                   const uint64_t *a,
                   const uint64_t *b,
                   double *out);

/**
 * Squared engine-wrap distance between two 32-bit fixed-point positions.
 *
 * # Safety
 *
 * `a` and `b` are three `uint32_t`. `out` is one writable double.
 */
int mi_dist2_fixed32(const struct mi_cell *simbox,
                     const uint32_t *a,
                     const uint32_t *b,
                     double *out);

/**
 * Squared MIC distances from `p` to `n` packed candidates in `qs`.
 *
 * # Safety
 *
 * `qs` is `n * 3` doubles. `out` is `n` doubles.
 */
int mi_dist2_many(const struct mi_cell *simbox,
                  const double *p,
                  const double *qs,
                  size_t n,
                  double *out);

/**
 * Squared engine-wrap distances from fixed-point `p` to `n` packed
 * fixed-point candidates.
 *
 * # Safety
 *
 * `p` is three `uint64_t`. `qs` is `n * 3` `uint64_t`. `out` is `n`
 * doubles.
 */
int mi_dist2_many_fixed(const struct mi_cell *simbox,
                        const uint64_t *p,
                        const uint64_t *qs,
                        size_t n,
                        double *out);

/**
 * Squared engine-wrap distances from 32-bit fixed-point `p` to `n` packed
 * fixed-point candidates.
 *
 * # Safety
 *
 * `p` is three `uint32_t`. `qs` is `n * 3` `uint32_t`. `out` is `n`
 * doubles.
 */
int mi_dist2_many_fixed32(const struct mi_cell *simbox,
                          const uint32_t *p,
                          const uint32_t *qs,
                          size_t n,
                          double *out);

/**
 * Orthorhombic wrap of precomputed differences (Highway kernel).
 *
 * # Safety
 *
 * `dx`, `dy`, `dz`, and `out` are `n` doubles.
 */
int mi_dist2_ortho_diffs(const double *dx,
                         const double *dy,
                         const double *dz,
                         double bx,
                         double by,
                         double bz,
                         double *out,
                         size_t n);

/**
 * Squared MIC distances for `n` packed pairs `(ps[k], qs[k])`.
 *
 * # Safety
 *
 * `ps` and `qs` are `n * 3` doubles. `out` is `n` doubles.
 */
int mi_dist2_pairs(const struct mi_cell *simbox,
                   const double *ps,
                   const double *qs,
                   size_t n,
                   double *out);

/**
 * Squared engine-wrap distances for `n` packed fixed-point pairs.
 *
 * # Safety
 *
 * `ps` and `qs` are `n * 3` `uint64_t`. `out` is `n` doubles.
 */
int mi_dist2_pairs_fixed(const struct mi_cell *simbox,
                         const uint64_t *ps,
                         const uint64_t *qs,
                         size_t n,
                         double *out);

/**
 * Squared engine-wrap distances for `n` packed 32-bit fixed-point pairs.
 *
 * # Safety
 *
 * `ps` and `qs` are `n * 3` `uint32_t`. `out` is `n` doubles.
 */
int mi_dist2_pairs_fixed32(const struct mi_cell *simbox,
                           const uint32_t *ps,
                           const uint32_t *qs,
                           size_t n,
                           double *out);

/**
 * Squared distances from `p` to `n` points in `qs`, plus one lattice
 * shift `(sx, sy, sz)` on every candidate. Rapaport's bin pair.
 *
 * # Safety
 *
 * `p` is three doubles. `qs` is `n * 3` doubles. `out` is `n` doubles.
 */
int mi_dist2_shifted_many(const double *p,
                          const double *qs,
                          const double *shift,
                          size_t n,
                          double *out);

/**
 * 32-bit fixed-point fractional coordinates of `n` packed positions:
 * three `uint32_t` per position, each the 64-bit fraction of
 * [`mi_fixed_many`] rounded to its top 32 bits.
 *
 * # Safety
 *
 * `rs` is `n * 3` doubles. `out` is `n * 3` writable `uint32_t`.
 */
int mi_fixed32_many(const struct mi_cell *simbox,
                    const double *rs,
                    size_t n,
                    uint32_t *out);

/**
 * Fixed-point fractional coordinates of `n` packed positions: three
 * `uint64_t` per position, each fraction as `round(s * 2^52) * 2^12`.
 *
 * # Safety
 *
 * `rs` is `n * 3` doubles. `out` is `n * 3` writable `uint64_t`.
 */
int mi_fixed_many(const struct mi_cell *simbox,
                  const double *rs,
                  size_t n,
                  uint64_t *out);

/**
 * Thread-local last-error string from this thread's most recent `mi_*`
 * failure.
 *
 * Returns a pointer to a NUL-terminated UTF-8 C string, or `NULL` if
 * the last call on this thread succeeded, or if none has failed yet.
 * [`mi_version`] does not read or write the slot. Distinct threads
 * have independent slots. The pointer is valid until the next `mi_*`
 * call on this thread. Do not free it.
 */
const char *mi_last_error(void);

/**
 * Drop self images and collapse duplicate `(i, j)` rows.
 *
 * `pairs` is `n * 2` ints. `out` has room for `n * 2` ints. `out_n`
 * receives the kept pair count.
 *
 * # Safety
 *
 * `pairs` is `2 * n` readable ints. `out` is `2 * n` writable ints.
 * `out_n` is one writable `size_t`.
 */
int mi_reduce_pairs(const int *pairs, size_t n, int *out, size_t *out_n);

/**
 * Library version string. Process-static, NUL-terminated. Do not free.
 */
const char *mi_version(void);

/**
 * Engine wrap of `n` packed difference vectors into `out`.
 *
 * # Safety
 *
 * `diffs` and `out` are `n * 3` doubles.
 */
int mi_wrap_many(const struct mi_cell *simbox,
                 const double *diffs,
                 size_t n,
                 double *out);

#ifdef __cplusplus
}  // extern "C"
#endif  // __cplusplus

#endif  /* MINIMAGE_H */

#ifndef MINIMAGE_MI_CELL_ORTHO_H
#define MINIMAGE_MI_CELL_ORTHO_H

#ifdef __cplusplus
extern "C" {
#endif

/**
 * Orthorhombic cell with origin at zero.
 */
static inline mi_cell mi_cell_ortho(double lx, double ly, double lz) {
    mi_cell c;
    c.ax = lx;
    c.ay = 0.0;
    c.az = 0.0;
    c.bx = 0.0;
    c.by = ly;
    c.bz = 0.0;
    c.cx = 0.0;
    c.cy = 0.0;
    c.cz = lz;
    c.ox = 0.0;
    c.oy = 0.0;
    c.oz = 0.0;
    return c;
}

#ifdef __cplusplus
}  /* extern "C" */
#endif

#endif  /* MINIMAGE_MI_CELL_ORTHO_H */