GitHub

Julia API

This page documents the Julia part of libtrixi, which is implemented in the LibTrixi.jl package. LibTrixi.jl provides Julia-based wrappers around Trixi.jl, making simulations controllable through a defined API.

Internal and development use only

The Julia API provided by LibTrixi.jl is only provided for internal use by libtrixi and to facilitate easier development and debugging of new library features. It is not intended to be used by Julia developers: They should directly utilize Trixi.jl to benefit from its Julia-native implementation.

LibTrixi.SimulationState — Type
SimulationState

Data structure to store a simulation state that consists of a semidiscretization plus the time integrator.

source
LibTrixi.trixi_calculate_dt — Function
trixi_calculate_dt(simstate_handle::Cint)::Cdouble

Compute, store, and return the time step size for the next time integration step.

source
LibTrixi.trixi_eval_julia — Function
trixi_eval_julia(code::Cstring)::Cvoid

Execute the provided code in the current Julia runtime environment.

Only for development

Code is not checked prior to execution.

source
LibTrixi.trixi_get_t8code_forest — Function
trixi_get_t8code_forest(simstate_handle::Cint)::::Ptr{Trixi.t8_forest}

Return t8code forest of the current T8codeMesh.

Experimental

The interface to t8code is experimental and implementation details may change at any time without warning.

source
LibTrixi.trixi_initialize_simulation — Function
trixi_initialize_simulation(libelixir::Cstring)::Cint
trixi_initialize_simulation(libelixir::AbstractString)::Cint

Initialize a new simulation based on the file libelixirand return a handle to the corresponding SimulationState as a Cint (i.e, a plain C int).

The libelixir has a similar purpose as a regular "elixir" in Trixi.jl, as it completely defines a simulation setup in Julia code. A key difference (and thus the name libelixir) is that instead of running a simulation directly, it should define an argument-less function named init_simstate() that returns a SimulationState with the complete simulation setup. trixi_initialize_simulation will store the SimulationState object internally and allow one to use it in subsequent calls to libtrixi via the handle returned from this function.

For convenience, when using LibTrixi.jl directly from Julia, one can also pass a regular String in the libelixir argument.

Libelixir hygiene and `init_simstate`

The libelixir file will be evaluated in the Main module. Thus any previously defined function init_simstate will be overwritten, and any variables defined outside the function will live throughout the lifetime of the Julia process.

Thread safety

This function is not thread safe. Since the libelixir file will be evaluated in the Main module, calling trixi_initialize_simulation simultaneously from different threads can lead to undefined behavior.

source
LibTrixi.trixi_is_finished — Function
trixi_is_finished(simstate_handle::Cint)::Cint

Return 0 if the simulation time has not yet reached the final time, and 1 otherwise.

source
LibTrixi.trixi_load_cell_averages — Function
trixi_load_cell_averages(data::Ptr{Cdouble}, simstate_handle::Cint)::Cvoid

Return cell averaged solution state.

Cell averaged values for each cell and each primitive variable are stored in a contiguous array, where cell values for the first variable appear first and values for the other variables subsequently (structure-of-arrays layout).

The given array has to be of correct size and memory has to be allocated beforehand.

source
LibTrixi.trixi_version_julia — Function
trixi_version_julia()::Cstring

Return name and version of loaded Julia packages LibTrixi directly depends on.

The return value is a read-only pointer to a NULL-terminated string with the name and version information of the loaded Julia packages, separated by newlines.

The returned pointer is to static memory and must not be used to change the contents of the version string. Multiple calls to the function will return the same address.

This function is thread-safe. It must be run after trixi_initialize has been called.

source
LibTrixi.trixi_version_julia_extended — Function
trixi_version_julia_extended()::Cstring

Return name and version of all loaded Julia packages.

The return value is a read-only pointer to a NULL-terminated string with the name and version information of all loaded Julia packages, including implicit dependencies, separated by newlines.

The returned pointer is to static memory and must not be used to change the contents of the version string. Multiple calls to the function will return the same address.

This function is thread-safe. It must be run after trixi_initialize has been called.

source
LibTrixi.trixi_version_library — Function
trixi_version_library()::Cstring

Return full version string of libtrixi.

The return value is a read-only pointer to a NULL-terminated string with the version information. This may include not just MAJOR.MINOR.PATCH but possibly also additional build or development version information.

The returned pointer is to static memory and must not be used to change the contents of the version string. Multiple calls to the function will return the same address.

This function is thread-safe. It must be run after trixi_initialize has been called.

source
LibTrixi.trixi_version_library_major — Function
trixi_version_library_major()::Cint

Return major version number of libtrixi.

This function is thread-safe. It must be run after trixi_initialize has been called.

source
LibTrixi.trixi_version_library_minor — Function
trixi_version_library_minor()::Cint

Return minor version number of libtrixi.

This function is thread-safe. It must be run after trixi_initialize has been called.

source
LibTrixi.trixi_version_library_patch — Function
trixi_version_library_patch()::Cint

Return patch version number of libtrixi.

This function is thread-safe. It must be run after trixi_initialize has been called.

source