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 consisting of

a semidiscretization
the time integrator
an optional array of data vectors

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.

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.

LibTrixi.trixi_finalize_simulation — Function

trixi_finalize_simulation(simstate_handle::Cint)::Cvoid

Finalize a simulation and attempt to free the underlying memory.

LibTrixi.trixi_get_conservative_vars_pointer — Function

trixi_get_conservative_vars_pointer(simstate_handle::Cint)::Ptr{Cdouble}

Return pointer to internal data vector.

LibTrixi.trixi_get_simulation_time — Function

trixi_get_simulation_time(simstate_handle::Cint)::Cdouble

Return current physical time.

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.

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.

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.

LibTrixi.trixi_load_conservative_var — Function

trixi_load_conservative_var(simstate_handle::Cint, variable_id::Cint,
                            data::Ptr{Cdouble})::Cvoid

Load conservative variable.

LibTrixi.trixi_load_element_averaged_primitive_var — Function

trixi_load_element_averaged_primitive_var(simstate_handle::Cint, variable_id::Cint,
                                          data::Ptr{Cdouble})::Cvoid

Load element averages for primitive variable.

Element averaged values for the primitive variable at position variable_id for each element are stored in the given array data.

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

LibTrixi.trixi_load_node_reference_coordinates — Function

trixi_load_node_reference_coordinates(simstate_handle::Cint, data::Ptr{Cdouble})::Cvoid

Get reference coordinates of 1D quadrature nodes.

LibTrixi.trixi_load_node_weights — Function

trixi_load_node_weights(simstate_handle::Cint, data::Ptr{Cdouble})::Cvoid

Get weights of 1D quadrature nodes.

LibTrixi.trixi_load_primitive_var — Function

trixi_load_primitive_var(simstate_handle::Cint, variable_id::Cint,
                         data::Ptr{Cdouble})::Cvoid

Load primitive variable.

The values for the primitive variable at position variable_id at every degree of freedom are stored in the given array data.

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

LibTrixi.trixi_ndims — Function

trixi_ndims(simstate_handle::Cint)::Cint

Return number of spatial dimensions.

LibTrixi.trixi_ndofs — Function

trixi_ndofs(simstate_handle::Cint)::Cint

Return number of degrees of freedom (all quadrature points on all elements of current rank).

LibTrixi.trixi_ndofselement — Function

trixi_ndofselement(simstate_handle::Cint)::Cint

Return number of degrees of freedom per element.

LibTrixi.trixi_ndofsglobal — Function

trixi_ndofsglobal(simstate_handle::Cint)::Cint

Return global number of degrees of freedom (all quadrature points on all elements on all ranks).

LibTrixi.trixi_nelements — Function

trixi_nelements(simstate_handle::Cint)::Cint

Return number of elements local to the MPI rank.

LibTrixi.trixi_nelementsglobal — Function

trixi_nelementsglobal(simstate_handle::Cint)::Cint

Return global number of elements on all MPI ranks.

LibTrixi.trixi_nnodes — Function

trixi_nnodes(simstate_handle::Cint)::Cint

Return number of quadrature nodes per dimension.

LibTrixi.trixi_nvariables — Function

trixi_nvariables(simstate_handle::Cint)::Cint

Return number of variables.

LibTrixi.trixi_register_data — Function

trixi_register_data(data::Ptr{Cdouble}, size::Cint, index::Cint,
                    simstate_handle::Cint)::Cvoid

Store data vector in current simulation's registry.

A reference to the passed data array data will be stored in the registry of the simulation given by simstate_handle at given index. The registry object has to be created in init_simstate() of the running libelixir and can be used throughout the simulation.

The registry object has to exist, has to be of type LibTrixiDataRegistry, and has to hold enough data references such that access at index is valid. Memory storage remains on the user side. It must not be deallocated as long as it might be accessed via the registry. The size of data has to match size.

LibTrixi.trixi_step — Function

trixi_step(simstate_handle::Cint)::Cvoid

Advance the simulation in time by one step.

LibTrixi.trixi_store_conservative_var — Function

trixi_store_conservative_var(simstate_handle::Cint, variable_id::Cint,
                             data::Ptr{Cdouble})::Cvoid

Store conservative variable.

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.

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.

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.

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.

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.

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.