seams-core v2.14.0
libyodaLib, the C++ engine of d-SEAMS
Loading...
Searching...
No Matches
Library metadata and errors

Version, names, error strings, and the thread team. More...

Functions

SEAMS_API int seams_abi (void)
 ABI number compiled into this library.
SEAMS_API int seams_version (void)
 Packed release number.
SEAMS_API int seams_version_major (void)
 Major version of the library at run time.
SEAMS_API int seams_version_minor (void)
 Minor version of the library at run time.
SEAMS_API int seams_version_patch (void)
 Patch version of the library at run time.
SEAMS_API const char * seams_version_string (void)
 Version text, for example "2.14.0".
SEAMS_API const char * seams_status_string (seams_status status)
 Short name of a status code.
SEAMS_API const char * seams_last_error (void)
 Thread-local detail of the last failing call on this thread.
SEAMS_API const char * seams_handle_error (const void *handle)
 Detail string stored on a handle.
SEAMS_API const char * seams_label_name (int label)
 Name of a CHILL label.
SEAMS_API const char * seams_ring_symmetry_name (int symmetry)
 Name of a ring-symmetry code.
SEAMS_API seams_status seams_set_num_threads (int n)
 Set the OpenMP team used by later analysis calls.
SEAMS_API int seams_get_num_threads (void)
 Team width the next analysis call will request.

Detailed Description

Version, names, error strings, and the thread team.

Function Documentation

◆ seams_abi()

SEAMS_API int seams_abi ( void )

ABI number compiled into this library.

Returns
SEAMS_ABI, which is 1.
Thread safety
Pure.
Example
if (seams_abi() != SEAMS_ABI) { return 1; }
SEAMS_API int seams_abi(void)
ABI number compiled into this library.
#define SEAMS_ABI
ABI generation of this header.
Definition seams.h:102

◆ seams_get_num_threads()

SEAMS_API int seams_get_num_threads ( void )

Team width the next analysis call will request.

Returns
A positive count. After seams_set_num_threads(0) this is the saved default, which is omp_get_max_threads() when OpenMP is linked and 1 otherwise.
Thread safety
Observes the process-global width. Do not call it concurrently with seams_set_num_threads().
Example
int width = seams_get_num_threads();
SEAMS_API int seams_get_num_threads(void)
Team width the next analysis call will request.

◆ seams_handle_error()

SEAMS_API const char * seams_handle_error ( const void * handle)

Detail string stored on a handle.

Parameters
handleA seams_system, seams_neighbours, seams_rings, seams_cage_set, seams_topo, or seams_brine, or NULL.
Returns
The handle's string, or the thread-local string when handle is NULL. Never NULL.

A call taking the handle non-const clears the string on entry. A call taking it const writes the string only when it fails, so after a successful const call the string still holds the last failure.

Ownership
Owned by the handle. Valid until the next failing call on that handle, the next non-const call on it, or destroy.
Thread safety
Reading a handle requires that no other thread is inside a call on that same handle.
Example
labels, n, NULL) != SEAMS_OK) {
fprintf(stderr, "%s\n", seams_handle_error(sys));
}
SEAMS_API const char * seams_handle_error(const void *handle)
Detail string stored on a handle.
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_OK
The call succeeded.
Definition seams.h:154
@ SEAMS_GRAPH_CUTOFF
Every neighbour inside the cutoff.
Definition seams.h:208

◆ seams_label_name()

SEAMS_API const char * seams_label_name ( int label)

Name of a CHILL label.

Parameters
labelA seams_label value.
Returns
Static string. Unknown codes return "unknown".
Ownership
The caller does not free it.
Thread safety
Pure.
Example
SEAMS_API const char * seams_label_name(int label)
Name of a CHILL label.
@ SEAMS_LABEL_HEXAGONAL
Hexagonal ice (Ih).
Definition seams.h:167

◆ seams_last_error()

SEAMS_API const char * seams_last_error ( void )

Thread-local detail of the last failing call on this thread.

ABI 1 spelling of seams_last_error_message(). Both return the same string.

Returns
Pointer to a thread-local string. Never NULL.
Ownership
Owned by the library. Valid until the next call on this thread that sets or clears the error.
Thread safety
The storage is thread-local.
Example
if (seams_system_set_atoms(sys, xyz, n, box9, 9, NULL, NULL) != SEAMS_OK) {
fprintf(stderr, "%s\n", seams_last_error());
}
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 const char * seams_last_error(void)
Thread-local detail of the last failing call on this thread.

◆ seams_ring_symmetry_name()

SEAMS_API const char * seams_ring_symmetry_name ( int symmetry)

Name of a ring-symmetry code.

Parameters
symmetryA seams_ring_symmetry value.
Returns
Static string. Unknown codes return "unknown".
Ownership
The caller does not free it.
Thread safety
Pure.
Example
SEAMS_API const char * seams_ring_symmetry_name(int symmetry)
Name of a ring-symmetry code.
@ SEAMS_RING_DDC
Face of a double-diamond cage.
Definition seams.h:180

◆ seams_set_num_threads()

SEAMS_API seams_status seams_set_num_threads ( int n)

Set the OpenMP team used by later analysis calls.

Parameters
nPositive width, or 0 to restore the width captured at first use. A negative width is rejected.
Returns
SEAMS_OK, or SEAMS_ERR_RANGE when n is negative, SEAMS_ERR_NOMEM, SEAMS_ERR_INTERNAL.
Thread safety
Process-global. Do not call it concurrently with analysis. The stored width is then read by every handle.
Example
SEAMS_API seams_status seams_set_num_threads(int n)
Set the OpenMP team used by later analysis calls.

◆ seams_status_string()

SEAMS_API const char * seams_status_string ( seams_status status)

Short name of a status code.

Parameters
statusA seams_status value.
Returns
Pointer to a static string. Unknown codes return "unknown status".
Ownership
The caller does not free it.
Thread safety
Pure.
Example
fprintf(stderr, "%s\n", seams_status_string(SEAMS_ERR_BOX));
SEAMS_API const char * seams_status_string(seams_status status)
Short name of a status code.
@ SEAMS_ERR_BOX
The cell is missing, non-finite, or has no volume.
Definition seams.h:157

◆ seams_version()

SEAMS_API int seams_version ( void )

Packed release number.

Returns
SEAMS_VERSION_NUMBER, (major << 16) | (minor << 8) | patch.
Thread safety
Pure.
Example
if (seams_version() < ((2 << 16) | (14 << 8))) { return 1; }
SEAMS_API int seams_version(void)
Packed release number.

◆ seams_version_major()

SEAMS_API int seams_version_major ( void )

Major version of the library at run time.

Returns
SEAMS_VERSION_MAJOR of the build.
Thread safety
Pure.
Example
int major = seams_version_major();
SEAMS_API int seams_version_major(void)
Major version of the library at run time.

◆ seams_version_minor()

SEAMS_API int seams_version_minor ( void )

Minor version of the library at run time.

Returns
SEAMS_VERSION_MINOR of the build.
Thread safety
Pure.
Example
int minor = seams_version_minor();
SEAMS_API int seams_version_minor(void)
Minor version of the library at run time.

◆ seams_version_patch()

SEAMS_API int seams_version_patch ( void )

Patch version of the library at run time.

Returns
SEAMS_VERSION_PATCH of the build.
Thread safety
Pure.
Example
int patch = seams_version_patch();
SEAMS_API int seams_version_patch(void)
Patch version of the library at run time.

◆ seams_version_string()

SEAMS_API const char * seams_version_string ( void )

Version text, for example "2.14.0".

Returns
Pointer to a static string. Never NULL.
Ownership
The caller does not free it.
Thread safety
Pure.
Example
printf("d-SEAMS %s\n", seams_version_string());
SEAMS_API const char * seams_version_string(void)
Version text, for example "2.14.0".