seams-core v2.14.0
libyodaLib, the C++ engine of d-SEAMS
Loading...
Searching...
No Matches
Frame reload and read-back

Overwrite coordinates in place and copy the stored frame out. More...

Functions

SEAMS_API seams_status seams_system_set_positions (seams_system *sys, const double *xyz, size_t n, const double *box9, size_t box_len)
 Overwrite the coordinates, and optionally the cell, of the stored frame.
SEAMS_API seams_status seams_system_stage_positions (seams_system *sys, int enable)
 Trade memory for a single pass in seams_system_set_positions().
SEAMS_API seams_status seams_system_box (const seams_system *sys, double *box9, size_t box_len)
 Copy the stored cell out as nine LAMMPS numbers.
SEAMS_API seams_status seams_system_positions (const seams_system *sys, double *xyz, size_t len)
 Copy the stored coordinates out.
SEAMS_API seams_status seams_system_types (const seams_system *sys, int *types, size_t len)
 Copy the stored atom types out.
SEAMS_API seams_status seams_system_ids (const seams_system *sys, int *ids, size_t len)
 Copy the stored atom ids out.

Detailed Description

Overwrite coordinates in place and copy the stored frame out.

There is no borrowed-pointer load. Every analysis reads the library's per-atom records, so a view onto caller memory would be copied on each analysis call instead of once per frame. A trajectory loop calls seams_system_set_atoms() once and seams_system_set_positions() for each later frame, which writes only the coordinates.

Function Documentation

◆ seams_system_box()

SEAMS_API seams_status seams_system_box ( const seams_system * sys,
double * box9,
size_t box_len )

Copy the stored cell out as nine LAMMPS numbers.

Parameters
sysFrame handle.
box9Caller buffer: ox, oy, oz, lx, ly, lz, xy, xz, yz. The values match the cell that was stored, to rounding.
box_lenMust be 9.
Returns
SEAMS_OK; SEAMS_ERR_NULL; SEAMS_ERR_RANGE when box_len != 9; SEAMS_ERR_STATE when no frame is stored.
Ownership
The caller owns box9.
Thread safety
Read-only: may run alongside other const calls on sys, and not alongside a non-const call on sys.
Example
double cell[9];
seams_system_box(sys, cell, 9);
SEAMS_API seams_status seams_system_box(const seams_system *sys, double *box9, size_t box_len)
Copy the stored cell out as nine LAMMPS numbers.

◆ seams_system_ids()

SEAMS_API seams_status seams_system_ids ( const seams_system * sys,
int * ids,
size_t len )

Copy the stored atom ids out.

Parameters
sysFrame handle.
idsCaller buffer for n ints, in stored order.
lenLength of ids. Must be at least n.
Returns
SEAMS_OK; SEAMS_ERR_NULL; SEAMS_ERR_STATE when no frame is stored; SEAMS_ERR_RANGE for a short buffer.
Ownership
The caller owns ids.
Thread safety
Read-only: may run alongside other const calls on sys, and not alongside a non-const call on sys.
Example
seams_system_ids(sys, ids, n);
SEAMS_API seams_status seams_system_ids(const seams_system *sys, int *ids, size_t len)
Copy the stored atom ids out.

◆ seams_system_positions()

SEAMS_API seams_status seams_system_positions ( const seams_system * sys,
double * xyz,
size_t len )

Copy the stored coordinates out.

Parameters
sysFrame handle.
xyzCaller buffer for 3 n doubles, Angstrom, in stored order.
lenLength of xyz in doubles. Must be at least 3 n.
Returns
SEAMS_OK; SEAMS_ERR_NULL; SEAMS_ERR_STATE when no frame is stored; SEAMS_ERR_RANGE for a short buffer.
Ownership
The caller owns xyz.
Thread safety
Read-only: may run alongside other const calls on sys, and not alongside a non-const call on sys.
Example
size_t n = 0;
double *xyz = malloc(3 * n * sizeof *xyz);
seams_system_positions(sys, xyz, 3 * n);
free(xyz);
SEAMS_API seams_status seams_system_positions(const seams_system *sys, double *xyz, size_t len)
Copy the stored coordinates out.
SEAMS_API seams_status seams_system_natoms(const seams_system *sys, size_t *n)
Number of points in the frame.

◆ seams_system_set_positions()

SEAMS_API seams_status seams_system_set_positions ( seams_system * sys,
const double * xyz,
size_t n,
const double * box9,
size_t box_len )

Overwrite the coordinates, and optionally the cell, of the stored frame.

Types and ids stay as stored. Per-atom labels written by an earlier seams_chill() or seams_chill_plus() are reset. On failure the frame is unchanged.

By default the call checks every coordinate first and then writes them in place, which reads xyz twice and needs no extra memory. After seams_system_stage_positions(sys, 1) it reads xyz once instead (see there).

Parameters
sysFrame handle with a stored frame.
xyzn times 3 Cartesian coordinates, Angstrom. Every value must be finite.
nAtom count. Must equal the stored count.
box9New cell (ox, oy, oz, lx, ly, lz, xy, xz, yz), or NULL to keep the stored cell.
box_len9 when box9 is not NULL; ignored otherwise.
Returns
SEAMS_OK; SEAMS_ERR_NULL for a NULL sys or xyz; SEAMS_ERR_STATE when no frame is stored; SEAMS_ERR_RANGE when n differs from the stored count or box_len != 9; SEAMS_ERR_BOX for a non-finite cell or a non-positive edge; SEAMS_ERR_ARG for a non-finite coordinate; SEAMS_ERR_NOMEM; SEAMS_ERR_INTERNAL.
Handle access
Non-const: replaces the stored coordinates and cell.
Ownership
The library copies xyz and box9. The caller keeps them and may reuse the buffers as soon as the call returns.
Thread safety
Exclusive use of sys.
Example
seams_system_set_atoms(sys, frame0, n, box9, 9, types, NULL);
for (size_t f = 1; f < nframes; ++f) {
seams_system_set_positions(sys, frames[f], n, NULL, 0);
labels, n, NULL);
}
SEAMS_API seams_status seams_system_set_positions(seams_system *sys, const double *xyz, size_t n, const double *box9, size_t box_len)
Overwrite the coordinates, and optionally the cell, of the stored frame.
SEAMS_API seams_status seams_system_set_atoms(seams_system *sys, const double *xyz, size_t n, const double *box9, size_t box_len, const int *types, const int *ids)
Store points and a general cell.
SEAMS_API seams_status seams_chill_plus_n(seams_system *sys, double cutoff, int type, int graph, int rule, int *labels, size_t labels_len, int counts9[9])
CHILL+ labels into a buffer of known length.
@ SEAMS_CHILL_PUBLISHED
Nguyen and Molinero, four closest neighbours.
Definition seams.h:202
@ SEAMS_GRAPH_CUTOFF
Every neighbour inside the cutoff.
Definition seams.h:208

◆ seams_system_stage_positions()

SEAMS_API seams_status seams_system_stage_positions ( seams_system * sys,
int enable )

Trade memory for a single pass in seams_system_set_positions().

With enable nonzero the handle keeps a second set of per-atom records, about 72 bytes per atom. seams_system_set_positions() then checks and writes the coordinates into that set in one pass and swaps it with the stored frame when every value was finite, so a failed call still leaves the frame unchanged. The first reload after each load fills the second set from the frame. With enable 0, the default, the second set is freed. The setting survives loads.

Parameters
sysFrame handle, with or without a stored frame.
enableNonzero to keep the second set, 0 to free it.
Returns
SEAMS_OK; SEAMS_ERR_NULL for a NULL sys.
Handle access
Non-const: changes how later reloads use memory. The stored frame is not touched.
Ownership
The library owns the second set and frees it with enable 0 or seams_system_destroy().
Thread safety
Exclusive use of sys.
Example
for (size_t f = 1; f < nframes; ++f) {
seams_system_set_positions(sys, frames[f], n, NULL, 0);
}
SEAMS_API seams_status seams_system_stage_positions(seams_system *sys, int enable)
Trade memory for a single pass in seams_system_set_positions().

◆ seams_system_types()

SEAMS_API seams_status seams_system_types ( const seams_system * sys,
int * types,
size_t len )

Copy the stored atom types out.

Parameters
sysFrame handle.
typesCaller buffer for n ints, in stored order.
lenLength of types. Must be at least n.
Returns
SEAMS_OK; SEAMS_ERR_NULL; SEAMS_ERR_STATE when no frame is stored; SEAMS_ERR_RANGE for a short buffer.
Ownership
The caller owns types.
Thread safety
Read-only: may run alongside other const calls on sys, and not alongside a non-const call on sys.
Example
seams_system_types(sys, types, n);
SEAMS_API seams_status seams_system_types(const seams_system *sys, int *types, size_t len)
Copy the stored atom types out.