seams-core v2.14.0
libyodaLib, the C++ engine of d-SEAMS
Loading...
Searching...
No Matches
Frames

Create, fill, read, and free a seams_system. More...

Functions

SEAMS_API seams_system * seams_system_create (void)
 Allocate an empty frame.
SEAMS_API void seams_system_destroy (seams_system *sys)
 Free a 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_system_set_frame (seams_system *sys, const double *xyz, int n, const double *box9, const int *types, const int *ids)
 Store points and a general LAMMPS cell, with an int count.
SEAMS_API seams_status seams_system_set_ortho (seams_system *sys, const double *xyz, int n, double ox, double oy, double oz, double lx, double ly, double lz, const int *types, const int *ids)
 Store points and an orthorhombic cell.
SEAMS_API seams_status seams_system_read (seams_system *sys, const char *path, int frame, int type_filter)
 Read one frame from a trajectory file.
SEAMS_API seams_status seams_path_nframes (const char *path, size_t *nframes)
 Number of frames in a trajectory path.
SEAMS_API int seams_system_count (const seams_system *sys)
 Number of points in the frame, as an int.

Detailed Description

Create, fill, read, and free a seams_system.

Function Documentation

◆ seams_path_nframes()

SEAMS_API seams_status seams_path_nframes ( const char * path,
size_t * nframes )

Number of frames in a trajectory path.

Parameters
pathFilesystem path.
nframesReceives the count. Must be non-NULL.
Returns
SEAMS_OK, or SEAMS_ERR_NULL, SEAMS_ERR_RANGE, SEAMS_ERR_ARG, SEAMS_ERR_INTERNAL. *nframes is unchanged on failure.
Ownership
path is read during the call only. nframes is caller storage that the call fills. The library keeps no pointer to any argument.
Thread safety
Safe for distinct paths.
Example
size_t nframes = 0;
seams_status rc = seams_path_nframes("ice.lammpstrj", &nframes);
SEAMS_API seams_status seams_path_nframes(const char *path, size_t *nframes)
Number of frames in a trajectory path.
seams_status
Status codes.
Definition seams.h:153

◆ seams_system_count()

SEAMS_API int seams_system_count ( const seams_system * sys)

Number of points in the frame, as an int.

ABI 1 query. It cannot report an error; seams_system_natoms() can.

Parameters
sysFrame handle, or NULL.
Returns
The atom count, or 0 when sys is NULL or holds no frame.
Ownership
The caller owns sys; the call borrows it. The library keeps no pointer to any argument.
Thread safety
Read-only: may run alongside other const calls on sys, and not alongside a non-const call on sys.
Example
int n = seams_system_count(sys);
SEAMS_API int seams_system_count(const seams_system *sys)
Number of points in the frame, as an int.

◆ seams_system_create()

SEAMS_API seams_system * seams_system_create ( void )

Allocate an empty frame.

Returns
A new handle, or NULL on allocation failure. seams_last_error_message() then explains the failure.
Ownership
The caller owns the handle and passes it to seams_system_destroy().
Thread safety
Safe. The new handle is not shared yet.
Example
if (sys == NULL) { return SEAMS_ERR_NOMEM; }
SEAMS_API seams_system * seams_system_create(void)
Allocate an empty frame.
SEAMS_API void seams_system_destroy(seams_system *sys)
Free a frame.
struct seams_system seams_system
One frame.
Definition seams.h:241
@ SEAMS_ERR_NOMEM
An allocation failed.
Definition seams.h:160

◆ seams_system_destroy()

SEAMS_API void seams_system_destroy ( seams_system * sys)

Free a frame.

Parameters
sysHandle from seams_system_create(), or NULL. NULL is ignored.
Ownership
The handle and the frame it stored are released. Neighbour, ring, cage, and brine handles built from it stay valid: they hold their own copies.
Thread safety
The caller must not use sys after this returns, and must not call it concurrently with any use of sys.
Example
sys = NULL;

◆ seams_system_read()

SEAMS_API seams_status seams_system_read ( seams_system * sys,
const char * path,
int frame,
int type_filter )

Read one frame from a trajectory file.

Parameters
sysFrame handle. On failure the previously stored frame is kept.
pathFilesystem path. CON, LAMMPS dump, and the formats the linked readers accept.
frameFrame index, 1-based, matching the file order.
type_filterNegative keeps every atom. Zero guesses the oxygen species. A positive value keeps that species number.
Returns
SEAMS_OK, or SEAMS_ERR_NULL, SEAMS_ERR_RANGE (frame index or empty frame), SEAMS_ERR_ARG (unreadable file), SEAMS_ERR_NOMEM, SEAMS_ERR_INTERNAL.
Handle access
Non-const: replaces the stored frame. On failure the old frame stays.
Ownership
The library copies the frame out of the file.
Thread safety
Exclusive use of sys. Concurrent reads of distinct paths on distinct handles are safe.
Example
seams_status rc = seams_system_read(sys, "ice.lammpstrj", 1, -1);
SEAMS_API seams_status seams_system_read(seams_system *sys, const char *path, int frame, int type_filter)
Read one frame from a trajectory file.

◆ seams_system_set_atoms()

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.

Lengths are size_t.

On failure the previously stored frame, if any, is kept.

A reload on the same handle reuses its per-atom storage. When ids is NULL or 1..n and n matches the previous load, the id table is kept as well, so reloading a trajectory frame by frame costs one pass over the input after the finiteness check. seams_system_set_positions() also skips the type and id pass.

Parameters
sysFrame handle.
xyzn times 3 Cartesian coordinates, Angstrom. Every value must be finite.
nAtom count. Zero is rejected. A count that does not fit in the frame's integer width is rejected.
box9Cell numbers: ox, oy, oz, lx, ly, lz, xy, xz, yz.
box_lenMust be 9.
typesAtom types, or NULL to store type 1 for every atom.
idsAtom ids, or NULL to store 1..n. Ids must be unique.
Returns
SEAMS_OK; SEAMS_ERR_NULL for a NULL sys, xyz, or box9; SEAMS_ERR_RANGE for n == 0 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 or repeated ids; SEAMS_ERR_NOMEM; SEAMS_ERR_INTERNAL.
Handle access
Non-const: replaces the stored frame. On failure the old frame stays.
Ownership
The library copies the arrays. The caller keeps them.
Thread safety
Exclusive use of sys.
Example
const double xyz[6] = {0, 0, 0, 1.5, 0, 0};
const double box9[9] = {0, 0, 0, 10, 10, 10, 0, 0, 0};
seams_status rc = seams_system_set_atoms(sys, xyz, 2, box9, 9, NULL, NULL);
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_system_set_frame()

SEAMS_API seams_status seams_system_set_frame ( seams_system * sys,
const double * xyz,
int n,
const double * box9,
const int * types,
const int * ids )

Store points and a general LAMMPS cell, with an int count.

ABI 1 entry. New callers use seams_system_set_atoms().

Parameters
sysFrame handle.
xyzn times 3 coordinates, Angstrom.
nAtom count. A non-positive count is rejected.
box9Nine cell numbers: ox, oy, oz, lx, ly, lz, xy, xz, yz.
typesTypes, or NULL for type 1.
idsIds, or NULL for 1..n.
Returns
Same codes as seams_system_set_atoms().
Handle access
Non-const: replaces the stored frame. On failure the old frame stays.
Ownership
The library copies the arrays.
Thread safety
Exclusive use of sys.
Example
seams_status rc = seams_system_set_frame(sys, xyz, 2, box9, NULL, NULL);
SEAMS_API seams_status seams_system_set_frame(seams_system *sys, const double *xyz, int n, const double *box9, const int *types, const int *ids)
Store points and a general LAMMPS cell, with an int count.

◆ seams_system_set_ortho()

SEAMS_API seams_status seams_system_set_ortho ( seams_system * sys,
const double * xyz,
int n,
double ox,
double oy,
double oz,
double lx,
double ly,
double lz,
const int * types,
const int * ids )

Store points and an orthorhombic cell.

Parameters
sysFrame handle.
xyzn times 3 coordinates, Angstrom.
nAtom count.
oxOrigin x, Angstrom.
oyOrigin y, Angstrom.
ozOrigin z, Angstrom.
lxEdge length x, Angstrom.
lyEdge length y, Angstrom.
lzEdge length z, Angstrom.
typesTypes, or NULL.
idsIds, or NULL.
Returns
Same codes as seams_system_set_frame(). The tilt is zero.
Handle access
Non-const: replaces the stored frame. On failure the old frame stays.
Ownership
The library copies the arrays.
Thread safety
Exclusive use of sys.
Example
seams_status rc = seams_system_set_ortho(sys, xyz, 2, 0, 0, 0, 10, 10, 10, NULL, NULL);
SEAMS_API seams_status seams_system_set_ortho(seams_system *sys, const double *xyz, int n, double ox, double oy, double oz, double lx, double ly, double lz, const int *types, const int *ids)
Store points and an orthorhombic cell.