API Reference

pl_reset

void pl_reset(int *numThreads, PanLink_Module_Type type);

Resets the PanLink engine for a new simulation session. This initializes internal states and prepares the specified module.

numThreads: Pointer to an integer specifying the number of threads to use (e.g., for OpenMP).

type: The module type to initialize (PL_MODULE_TYPE_PanPhaseEquilibrium, PL_MODULE_TYPE_PanEvolution, or PL_MODULE_TYPE_PanSoldification).

pl_free_PanLink

void pl_free_PanLink();

Frees all memory allocated by PanLink and shuts down the engine. Should be called when the simulation is complete.

pl_set_db_folder

bool pl_set_db_folder(char * path, char * error_msg);

Sets the base directory where database files (.tdb, .kdb, etc.) are located. This must be called before running calculations.

path: Absolute or relative path to the database folder.

error_msg: Buffer to store any error messages if the operation fails.

Returns: true if successful, false otherwise.

pl_set_max_dt

void pl_set_max_dt(double *max_dt);

Sets the maximum time step allowed for the simulation. If max_dt <= 0, the engine uses its adaptive time stepping.

max_dt: Pointer to the maximum time step value (in seconds).

pl_set_num_clusters

void pl_set_num_clusters(int *num_clusters);

Sets the number of clusters for precipitation simulations. Default is typically 100.

num_clusters: Pointer to the integer value.

pl_set_output_properties

void pl_set_output_properties(const PanLink_Predefined_Property_Status* status, int count);

Enables or disables the calculation/output of specific predefined properties.

status: Array of PanLink_Predefined_Property_Status structures defining which properties to toggle.

count: The number of elements in the status array.

Note: Properties not included in the request retain their previous status. PROP_ID_CUSTOM cannot be managed here.

pl_update_material_property

bool pl_update_material_property(int *thread_id, int *cell_id, PanLink_State_Variable *variable, PanLink_Property *props, char *error_msg);

The core function to perform a calculation step. It takes the current state (time, temperature, composition) and updates the material properties.

thread_id: Pointer to the current thread ID (0-indexed).

cell_id: Pointer to the unique ID of the simulation cell/node.

variable: Pointer to the PanLink_State_Variable struct containing inputs (T, t, composition, etc.).

props: Pointer to the PanLink_Property struct where results will be stored.

error_msg: Buffer to store error messages on failure.

Returns: true if the update was successful, false otherwise.

PL_UPDATE_MATERIAL_PROPERTY

bool PL_UPDATE_MATERIAL_PROPERTY(...);

Alias for pl_update_material_property (uppercase convention).

pl_get_system_info

bool pl_get_system_info(Material_System_Info * info);

Retrieves information about the currently loaded material system, including components and databases.

info: Pointer to a Material_System_Info struct to be populated.

Returns: true if successful.

Initialization & Cleanup