Index¶

API¶

group libyt API: yt_initialize

Functions

int yt_initialize(int argc, char *argv[], const yt_param_libyt *param_libyt)¶

Initialize libyt.

This function should not be called more than once.
Initialize libyt workflow, Python interpreter, and import libyt module.

Parameters:

argc[in] –
argv[in] –
param_libyt[in] – libyt runtime parameters

Returns:

YT_SUCCESS or YT_FAIL

group libyt API: yt_set_Parameters

Functions

int yt_set_Parameters(yt_param_yt *input_param_yt)¶

Set YT-specific parameters and parameters for initializing AMR data structure.

Store yt relevant data to libyt Python module libyt.param_yt.
Initialize AMR data structure and storage.
Should be called after yt_initialize.

Parameters:: input_param_yt[in] – YT-specific parameters and parameters for initializing AMR data structure
Returns:: YT_SUCCESS or YT_FAIL

group Api_yt_set_UserParameter

Functions

int yt_set_UserParameterInt(const char *key, const int n, const int *input)¶

Set user parameter int.

Key-value pair will be appended to libyt.param_user.
Data is copied.

Parameters:

key[in] – key
n[in] – length of value array to be set in dictionary
input[in] – value array

Returns:

YT_SUCCESS or YT_FAIL

int yt_set_UserParameterLong(const char *key, const int n, const long *input)¶

Set user parameter long.

Key-value pair will be appended to libyt.param_user.
Data is copied.

Parameters:

key[in] – key
n[in] – length of value array to be set in dictionary
input[in] – value array

Returns:

YT_SUCCESS or YT_FAIL

int yt_set_UserParameterLongLong(const char *key, const int n, const long long *input)¶

Set user parameter long long.

Key-value pair will be appended to libyt.param_user.
Data is copied.

Parameters:

key[in] – key
n[in] – length of value array to be set in dictionary
input[in] – value array

Returns:

YT_SUCCESS or YT_FAIL

int yt_set_UserParameterUint(const char *key, const int n, const unsigned int *input)¶

Set user parameter unsigned int.

Key-value pair will be appended to libyt.param_user.
Data is copied.

Parameters:

key[in] – key
n[in] – length of value array to be set in dictionary
input[in] – value array

Returns:

YT_SUCCESS or YT_FAIL

int yt_set_UserParameterUlong(const char *key, const int n, const unsigned long *input)¶

Set user parameter unsigned long.

Key-value pair will be appended to libyt.param_user.
Data is copied.

Parameters:

key[in] – key
n[in] – length of value array to be set in dictionary
input[in] – value array

Returns:

YT_SUCCESS or YT_FAIL

int yt_set_UserParameterFloat(const char *key, const int n, const float *input)¶

Set user parameter float.

Key-value pair will be appended to libyt.param_user.
Data is copied.

Parameters:

key[in] – key
n[in] – length of value array to be set in dictionary
input[in] – value array

Returns:

YT_SUCCESS or YT_FAIL

int yt_set_UserParameterDouble(const char *key, const int n, const double *input)¶

Set user parameter double.

Key-value pair will be appended to libyt.param_user.
Data is copied.

Parameters:

key[in] – key
n[in] – length of value array to be set in dictionary
input[in] – value array

Returns:

YT_SUCCESS or YT_FAIL

int yt_set_UserParameterString(const char *key, const char *input)¶

Set user parameter string.

Key-value pair will be appended to libyt.param_user.
Data is copied.

Parameters:

key[in] – key
input[in] – value

Returns:

YT_SUCCESS or YT_FAIL

group libyt API: yt_get_FieldsPtr

Functions

int yt_get_FieldsPtr(yt_field **field_list)¶

Get pointer of field information array.

User should call this function after yt_set_Parameters, because the AMR structure is initialized there.

Todo:

The setting up of field info is just bad. Should fix it in libyt-v1.0. Probably should make setting of field info field-by-field

Parameters:: field_list[out] – Pointer to the array of yt_field is stored here
Returns:: YT_SUCCESS or YT_FAIL

group libyt API: yt_get_ParticlesPtr

Functions

int yt_get_ParticlesPtr(yt_particle **particle_list)¶

Get pointer of particle information array.

User should call this function after yt_set_Parameters, because the AMR structure is initialized there.

Todo:

The setting up of particle info is just bad. Should fix it in libyt-v1.0.

Parameters:: particle_list[out] – Pointer to the array of yt_particle is stored
Returns:: YT_SUCCESS or YT_FAIL

group libyt API: yt_get_GridsPtr

Functions

int yt_get_GridsPtr(yt_grid **grids_local)¶

Get pointer of local grids information array.

User should call this function after yt_set_Parameters, because the AMR structure is initialized there.

Todo:

Loading grid hierarchy and data is so inefficient, should fix it in libyt-v1.0.

Parameters:: grids_local[out] – Pointer to the array of yt_grid is stored
Returns:: YT_SUCCESS or YT_FAIL

group libyt API: yt_commit

Functions

int yt_commit()¶

Add local grids, append field list and particle list info to the libyt Python module.

Must call yt_get_FieldsPtr (if num_fields>0), yt_get_ParticlesPtr (if num_par_types>0), and yt_get_GridsPtr.
Call DataStructureAmr to bind info, bind hierarchy, and bind local data to Python.

Returns:: YT_SUCCESS or YT_FAIL

group libyt API: Getting Grid and Data Information

Functions

int yt_getGridInfo_Dimensions(const long gid, int (*dimensions)[3])¶

Get grid dimensions in [x][y][z] coordinates of grid with grid id = gid.

It searches full hierarchy loaded in Python, and returns YT_FAIL if error occurs.
grid_dimensions is defined in [x][y][z] <-> [0][1][2] coordinate.
gid is grid id passed in by user, it doesn’t need to be 0-indexed.

long gid = 0;
int dim[3];
yt_getGridInfo_Dimensions( gid, &dim );

Parameters:

gid[in] – grid id
dimensions[out] – grid dimensions

Returns:

YT_SUCCESS or YT_FAIL

int yt_getGridInfo_LeftEdge(const long gid, double (*left_edge)[3])¶

Get grid left edges in [x][y][z] coordinates of grid with grid id = gid.

It searches full hierarchy loaded in Python, and returns YT_FAIL if error occurs.
Returned left edge is defined in [x][y][z] <-> [0][1][2] coordinate.
gid is grid id passed in by user, it doesn’t need to be 0-indexed.

long gid = 0;
double left_edge[3];
yt_getGridInfo_LeftEdge( gid, &left_edge );

Parameters:

gid[in] – grid id
left_edge[out] – grid left edge

Returns:

YT_SUCCESS or YT_FAIL

int yt_getGridInfo_RightEdge(const long gid, double (*right_edge)[3])¶

Get grid right edges in [x][y][z] coordinates of grid with grid id = gid.

It searches full hierarchy loaded in Python, and returns YT_FAIL if error occurs.
Returned right edge is defined in [x][y][z] <-> [0][1][2] coordinate.
gid is grid id passed in by user, it doesn’t need to be 0-indexed.

long gid = 0;
double right_edge[3];
yt_getGridInfo_RightEdge( gid, &right_edge );

Parameters:

gid[in] – grid id
right_edge[out] – grid right edge

Returns:

YT_SUCCESS or YT_FAIL

int yt_getGridInfo_ParentId(const long gid, long *parent_id)¶

Get parent id of grid with grid id = gid.

It searches full hierarchy loaded in Python, and returns YT_FAIL if error occurs.
gid is grid id passed in by user, it doesn’t need to be 0-indexed.

long parent_id;
yt_getGridInfo_ParentId( gid, &parent_id );

Parameters:

gid[in] – grid id
parent_id[out] – parent id

Returns:

YT_SUCCESS or YT_FAIL

int yt_getGridInfo_Level(const long gid, int *level)¶

Get level of grid with grid id = gid.

It searches full hierarchy loaded in Python, and returns YT_FAIL if error occurs.
gid is grid id passed in by user, it doesn’t need to be 0-indexed.
Root level starts at 0.

int level;
yt_getGridInfo_Level( gid, &level );

Parameters:

gid[in] – grid id
level[out] – level

Returns:

YT_SUCCESS or YT_FAIL

int yt_getGridInfo_ProcNum(const long gid, int *proc_num)¶

Get processor number (mpi rank) of grid with grid id = gid.

It searches full hierarchy loaded in Python, and returns YT_FAIL if error occurs.
gid is grid id passed in by user, it doesn’t need to be 0-indexed.
Processor number starts at 0.

int proc_num;
yt_getGridInfo_ProcNum( gid, &proc_num );

Parameters:

gid[in] – grid id
proc_num[out] – processor number

Returns:

YT_SUCCESS or YT_FAIL

int yt_getGridInfo_ParticleCount(const long gid, const char *ptype, long *par_count)¶

Get particle count of a particle type inside grid with grid id = gid.

It searches full hierarchy loaded in Python, and returns YT_FAIL if error occurs.
gid is grid id passed in by user, it doesn’t need to be 0-indexed.

long par_count;
yt_getGridInfo_ParticleCount( gid, "io", &par_count );

Parameters:

gid[in] – grid id
ptype[in] – particle type
par_count[out] – particle count

int yt_getGridInfo_FieldData(const long gid, const char *field_name, yt_data *field_data)¶

Get field data of grid with grid id = gid.

It searches simulation field data registered under libyt Python module, and returns YT_FAIL if error occurs.
gid is grid id passed in by user, it doesn’t need to be 0-indexed.
User should cast to their own datatype after receiving the pointer.
Returns an existing data pointer and data dimensions user passed in, and does not make a copy of it!!
Works only for 3-dim data.

yt_data data;
yt_getGridInfo_FieldData(gid, "field_name", &data);
double *field_data = (double *) data.data_ptr;

Parameters:

gid[in] – grid id
field_name[in] – queried field name
field_data[out] – field data pointer and metadata

Returns:

YT_SUCCESS or YT_FAIL

int yt_getGridInfo_ParticleData(const long gid, const char *ptype, const char *attr, yt_data *par_data)¶

Get particle data of grid with grid id = gid.

It searches particle data registered under libyt Python module, and returns YT_FAIL if error occurs.
gid is grid id passed in by user, it doesn’t need to be 0-indexed.
User should cast to their own datatype after receiving the pointer.
Returns an existing data pointer and data dimensions user passed in, and does not make a copy of it!!
For 1-dim data (like particles), the higher dimensions is set to 0.

yt_data data;
yt_getGridInfo_ParticleData(gid, "io", "PosX", &data);
double *par_data = (double *) data.data_ptr;

Parameters:

gid[in] – grid id
ptype[in] – queried particle type
attr[in] – queried attribute
par_data[out] – particle data pointer and metadata

Returns:

YT_SUCCESS or YT_FAIL

group libyt API: yt_run_FunctionArguments / yt_run_Function

Functions

int yt_run_FunctionArguments(const char *function_name, int argc, ...)¶

Call Python function with args in in situ process.

The function is run inside the inline script namespace, which is the script passed in yt_initialize and yt_param_libyt. Which means the script contains the function name you called.
Must give argc (argument count), even if there are no arguments.
libyt wraps function and its arguments using either """ or ''' triple quotes, so we must avoid using both of these triple quotes in function arguments.
Under INTERACTIVE_MODE, function will be wrapped inside try/except. If an error occurred, it will be stored under libyt.interactive_mode.

// Equivalent to Python: function_name(1, 'string', var_name)
yt_run_FunctionArguments("function_name", 3, "1", "'string'", "var_name");

Parameters:

function_name[in] – Python function name
argc[in] – Number of arguments
...[in] – List of arguments, should be input as strings

Returns:

YT_SUCCESS or YT_FAIL

int yt_run_Function(const char *function_name)¶

Call Python function without args in in situ process.

Route to yt_run_FunctionArguments.

// Equivalent to Python: function_name()
yt_run_Function("function_name");

Parameters:: function_name[in] – Python function name
Returns:: YT_SUCCESS or YT_FAIL

group libyt API: yt_run_InteractiveMode

Functions

int yt_run_InteractiveMode(const char *flag_file_name)¶

Enter libyt interactive mode.

Only enter this mode flag_file_name is detected.
Display inline script execute result success/failed.
Enter interactive mode, user will be operating in inline script’s name space using Python script and libyt command.
Execute characters should be less than INT_MAX.
This API deals with user inputs, and direct jobs to other functions.

Note

This API is only available when libyt is compiled with -DINTERACTIVE_MODE=ON.

Parameters:: flag_file_name[in] – Stop and enter interactive mode if this file is detected
Returns:: YT_SUCCESS or YT_FAIL

group libyt API: yt_run_ReloadScript

Functions

int yt_run_ReloadScript(const char *flag_file_name, const char *reload_file_name, const char *script_name)¶

This API and yt_run_InteractiveMode has the same feature, but this one uses file base to interact with the prompt.
It simply loads each line in a file line-by-line.
Using reload_file_name_EXIT/SUCCESS/FAILED for a series of instructions.

libyt command needs to be commented out and at the end of the file. For example:

# Reload this Python script
print("Hello, World!")
#LIBYT_COMMANDS
# %libyt status

Note

This API is only available when libyt is compiled with -DINTERACTIVE_MODE=ON.

Warning

It stops and enters the API if flag file is detected or there is an error in in situ analysis. In the latter case, it will generate the flag file to indicate it enters the mode, and will remove the flag file once it exits the API.

Parameters:

flag_file_name[in] – Flag file name exists means it will enter reload script mode
reload_file_name[in] – Reload operation indicator file name
script_name[in] – Full Python script name to reload, include .py

Returns:

YT_SUCCESS or YT_FAIL

group libyt API: yt_run_JupyterKernel

Functions

int yt_run_JupyterKernel(const char *flag_file_name, bool use_connection_file)¶

Start libyt kernel for Jupyter Notebook access.

This API provides an access point for Jupyter Notebook.
This API forces kernel to be on MPI process 0 (root).
Jupyter Notebook/JupyterLab are launched in separated process.

Important

Connection file must be libyt_kernel_connection.json if use_connection_file is true.

Note

This API is only available when libyt is compiled with -DJUPYTER_KERNEL=ON.

Parameters:

flag_file_name[in] – Flag file name exists means it will activate libyt kernel
use_connection_file[in] – Use connection file set by user or not

Returns:

group libyt API: yt_free

Functions

int yt_free()¶

Free all libyt initialized and allocated array and refresh the inline Python state.

Call this after finishing in situ analysis in this round, or when we want to free everything allocated by libyt.

Returns:: YT_SUCCESS or YT_FAIL

group libyt API: yt_finalize

Functions

int yt_finalize()¶

Finalize libyt workflow.

Do not reinitialize libyt (i.e., calling yt_initialize()) after calling this function. Some extensions (e.g., NumPy) may not work properly.
Make sure that the user has follow the full libyt workflow. Like calling yt_free before calling this function.

Returns:: YT_SUCCESS or YT_FAIL

Define, Enums, Struct¶

This is the API header to be included by simulation codes.

Defines

LIBYT_MAJOR_VERSION¶

LIBYT_MINOR_VERSION¶

LIBYT_MICRO_VERSION¶

Functions

int yt_initialize(int argc, char *argv[], const yt_param_libyt *param_libyt)

Initialize libyt.

This function should not be called more than once.
Initialize libyt workflow, Python interpreter, and import libyt module.

Parameters:

argc[in] –
argv[in] –
param_libyt[in] – libyt runtime parameters

Returns:

YT_SUCCESS or YT_FAIL

int yt_finalize()

Finalize libyt workflow.

Do not reinitialize libyt (i.e., calling yt_initialize()) after calling this function. Some extensions (e.g., NumPy) may not work properly.
Make sure that the user has follow the full libyt workflow. Like calling yt_free before calling this function.

Returns:: YT_SUCCESS or YT_FAIL

int yt_set_Parameters(yt_param_yt *input_param_yt)

Set YT-specific parameters and parameters for initializing AMR data structure.

Store yt relevant data to libyt Python module libyt.param_yt.
Initialize AMR data structure and storage.
Should be called after yt_initialize.

Parameters:: input_param_yt[in] – YT-specific parameters and parameters for initializing AMR data structure
Returns:: YT_SUCCESS or YT_FAIL

int yt_get_FieldsPtr(yt_field **field_list)

Get pointer of field information array.

User should call this function after yt_set_Parameters, because the AMR structure is initialized there.

Todo:

The setting up of field info is just bad. Should fix it in libyt-v1.0. Probably should make setting of field info field-by-field

Parameters:: field_list[out] – Pointer to the array of yt_field is stored here
Returns:: YT_SUCCESS or YT_FAIL

int yt_get_ParticlesPtr(yt_particle **particle_list)

Get pointer of particle information array.

User should call this function after yt_set_Parameters, because the AMR structure is initialized there.

Todo:

The setting up of particle info is just bad. Should fix it in libyt-v1.0.

Parameters:: particle_list[out] – Pointer to the array of yt_particle is stored
Returns:: YT_SUCCESS or YT_FAIL

int yt_get_GridsPtr(yt_grid **grids_local)

Get pointer of local grids information array.

User should call this function after yt_set_Parameters, because the AMR structure is initialized there.

Todo:

Loading grid hierarchy and data is so inefficient, should fix it in libyt-v1.0.

Parameters:: grids_local[out] – Pointer to the array of yt_grid is stored
Returns:: YT_SUCCESS or YT_FAIL

int yt_set_UserParameterInt(const char *key, const int n, const int *input)

Set user parameter int.

Key-value pair will be appended to libyt.param_user.
Data is copied.

Parameters:

key[in] – key
n[in] – length of value array to be set in dictionary
input[in] – value array

Returns:

YT_SUCCESS or YT_FAIL

int yt_set_UserParameterLong(const char *key, const int n, const long *input)

Set user parameter long.

Key-value pair will be appended to libyt.param_user.
Data is copied.

Parameters:

key[in] – key
n[in] – length of value array to be set in dictionary
input[in] – value array

Returns:

YT_SUCCESS or YT_FAIL

int yt_set_UserParameterLongLong(const char *key, const int n, const long long *input)

Set user parameter long long.

Key-value pair will be appended to libyt.param_user.
Data is copied.

Parameters:

key[in] – key
n[in] – length of value array to be set in dictionary
input[in] – value array

Returns:

YT_SUCCESS or YT_FAIL

int yt_set_UserParameterUint(const char *key, const int n, const unsigned int *input)

Set user parameter unsigned int.

Key-value pair will be appended to libyt.param_user.
Data is copied.

Parameters:

key[in] – key
n[in] – length of value array to be set in dictionary
input[in] – value array

Returns:

YT_SUCCESS or YT_FAIL

int yt_set_UserParameterUlong(const char *key, const int n, const unsigned long *input)

Set user parameter unsigned long.

Key-value pair will be appended to libyt.param_user.
Data is copied.

Parameters:

key[in] – key
n[in] – length of value array to be set in dictionary
input[in] – value array

Returns:

YT_SUCCESS or YT_FAIL

int yt_set_UserParameterFloat(const char *key, const int n, const float *input)

Set user parameter float.

Key-value pair will be appended to libyt.param_user.
Data is copied.

Parameters:

key[in] – key
n[in] – length of value array to be set in dictionary
input[in] – value array

Returns:

YT_SUCCESS or YT_FAIL

int yt_set_UserParameterDouble(const char *key, const int n, const double *input)

Set user parameter double.

Key-value pair will be appended to libyt.param_user.
Data is copied.

Parameters:

key[in] – key
n[in] – length of value array to be set in dictionary
input[in] – value array

Returns:

YT_SUCCESS or YT_FAIL

int yt_set_UserParameterString(const char *key, const char *input)

Set user parameter string.

Key-value pair will be appended to libyt.param_user.
Data is copied.

Parameters:

key[in] – key
input[in] – value

Returns:

YT_SUCCESS or YT_FAIL

int yt_commit()

Add local grids, append field list and particle list info to the libyt Python module.

Must call yt_get_FieldsPtr (if num_fields>0), yt_get_ParticlesPtr (if num_par_types>0), and yt_get_GridsPtr.
Call DataStructureAmr to bind info, bind hierarchy, and bind local data to Python.

Returns:: YT_SUCCESS or YT_FAIL

int yt_free()

Free all libyt initialized and allocated array and refresh the inline Python state.

Call this after finishing in situ analysis in this round, or when we want to free everything allocated by libyt.

Returns:: YT_SUCCESS or YT_FAIL

int yt_run_FunctionArguments(const char *function_name, int argc, ...)

Call Python function with args in in situ process.

The function is run inside the inline script namespace, which is the script passed in yt_initialize and yt_param_libyt. Which means the script contains the function name you called.
Must give argc (argument count), even if there are no arguments.
libyt wraps function and its arguments using either """ or ''' triple quotes, so we must avoid using both of these triple quotes in function arguments.
Under INTERACTIVE_MODE, function will be wrapped inside try/except. If an error occurred, it will be stored under libyt.interactive_mode.

// Equivalent to Python: function_name(1, 'string', var_name)
yt_run_FunctionArguments("function_name", 3, "1", "'string'", "var_name");

Parameters:

function_name[in] – Python function name
argc[in] – Number of arguments
...[in] – List of arguments, should be input as strings

Returns:

YT_SUCCESS or YT_FAIL

int yt_run_Function(const char *function_name)

Call Python function without args in in situ process.

Route to yt_run_FunctionArguments.

// Equivalent to Python: function_name()
yt_run_Function("function_name");

Parameters:: function_name[in] – Python function name
Returns:: YT_SUCCESS or YT_FAIL

int yt_run_InteractiveMode(const char *flag_file_name)

Enter libyt interactive mode.

Only enter this mode flag_file_name is detected.
Display inline script execute result success/failed.
Enter interactive mode, user will be operating in inline script’s name space using Python script and libyt command.
Execute characters should be less than INT_MAX.
This API deals with user inputs, and direct jobs to other functions.

Note

This API is only available when libyt is compiled with -DINTERACTIVE_MODE=ON.

Parameters:: flag_file_name[in] – Stop and enter interactive mode if this file is detected
Returns:: YT_SUCCESS or YT_FAIL

int yt_run_ReloadScript(const char *flag_file_name, const char *reload_file_name, const char *script_name)

This API and yt_run_InteractiveMode has the same feature, but this one uses file base to interact with the prompt.
It simply loads each line in a file line-by-line.
Using reload_file_name_EXIT/SUCCESS/FAILED for a series of instructions.

libyt command needs to be commented out and at the end of the file. For example:

# Reload this Python script
print("Hello, World!")
#LIBYT_COMMANDS
# %libyt status

Note

This API is only available when libyt is compiled with -DINTERACTIVE_MODE=ON.

Warning

Parameters:

flag_file_name[in] – Flag file name exists means it will enter reload script mode
reload_file_name[in] – Reload operation indicator file name
script_name[in] – Full Python script name to reload, include .py

Returns:

YT_SUCCESS or YT_FAIL

int yt_run_JupyterKernel(const char *flag_file_name, bool use_connection_file)

Start libyt kernel for Jupyter Notebook access.

This API provides an access point for Jupyter Notebook.
This API forces kernel to be on MPI process 0 (root).
Jupyter Notebook/JupyterLab are launched in separated process.

Important

Connection file must be libyt_kernel_connection.json if use_connection_file is true.

Note

This API is only available when libyt is compiled with -DJUPYTER_KERNEL=ON.

Parameters:

flag_file_name[in] – Flag file name exists means it will activate libyt kernel
use_connection_file[in] – Use connection file set by user or not

Returns:

int yt_getGridInfo_Dimensions(const long gid, int (*dimensions)[3])

Get grid dimensions in [x][y][z] coordinates of grid with grid id = gid.

It searches full hierarchy loaded in Python, and returns YT_FAIL if error occurs.
grid_dimensions is defined in [x][y][z] <-> [0][1][2] coordinate.
gid is grid id passed in by user, it doesn’t need to be 0-indexed.

long gid = 0;
int dim[3];
yt_getGridInfo_Dimensions( gid, &dim );

Parameters:

gid[in] – grid id
dimensions[out] – grid dimensions

Returns:

YT_SUCCESS or YT_FAIL

int yt_getGridInfo_LeftEdge(const long gid, double (*left_edge)[3])

Get grid left edges in [x][y][z] coordinates of grid with grid id = gid.

It searches full hierarchy loaded in Python, and returns YT_FAIL if error occurs.
Returned left edge is defined in [x][y][z] <-> [0][1][2] coordinate.
gid is grid id passed in by user, it doesn’t need to be 0-indexed.

long gid = 0;
double left_edge[3];
yt_getGridInfo_LeftEdge( gid, &left_edge );

Parameters:

gid[in] – grid id
left_edge[out] – grid left edge

Returns:

YT_SUCCESS or YT_FAIL

int yt_getGridInfo_RightEdge(const long gid, double (*right_edge)[3])

Get grid right edges in [x][y][z] coordinates of grid with grid id = gid.

It searches full hierarchy loaded in Python, and returns YT_FAIL if error occurs.
Returned right edge is defined in [x][y][z] <-> [0][1][2] coordinate.
gid is grid id passed in by user, it doesn’t need to be 0-indexed.

long gid = 0;
double right_edge[3];
yt_getGridInfo_RightEdge( gid, &right_edge );

Parameters:

gid[in] – grid id
right_edge[out] – grid right edge

Returns:

YT_SUCCESS or YT_FAIL

int yt_getGridInfo_ParentId(const long gid, long *parent_id)

Get parent id of grid with grid id = gid.

It searches full hierarchy loaded in Python, and returns YT_FAIL if error occurs.
gid is grid id passed in by user, it doesn’t need to be 0-indexed.

long parent_id;
yt_getGridInfo_ParentId( gid, &parent_id );

Parameters:

gid[in] – grid id
parent_id[out] – parent id

Returns:

YT_SUCCESS or YT_FAIL

int yt_getGridInfo_Level(const long gid, int *level)

Get level of grid with grid id = gid.

It searches full hierarchy loaded in Python, and returns YT_FAIL if error occurs.
gid is grid id passed in by user, it doesn’t need to be 0-indexed.
Root level starts at 0.

int level;
yt_getGridInfo_Level( gid, &level );

Parameters:

gid[in] – grid id
level[out] – level

Returns:

YT_SUCCESS or YT_FAIL

int yt_getGridInfo_ProcNum(const long gid, int *proc_num)

Get processor number (mpi rank) of grid with grid id = gid.

It searches full hierarchy loaded in Python, and returns YT_FAIL if error occurs.
gid is grid id passed in by user, it doesn’t need to be 0-indexed.
Processor number starts at 0.

int proc_num;
yt_getGridInfo_ProcNum( gid, &proc_num );

Parameters:

gid[in] – grid id
proc_num[out] – processor number

Returns:

YT_SUCCESS or YT_FAIL

int yt_getGridInfo_ParticleCount(const long gid, const char *ptype, long *par_count)

Get particle count of a particle type inside grid with grid id = gid.

It searches full hierarchy loaded in Python, and returns YT_FAIL if error occurs.
gid is grid id passed in by user, it doesn’t need to be 0-indexed.

long par_count;
yt_getGridInfo_ParticleCount( gid, "io", &par_count );

Parameters:

gid[in] – grid id
ptype[in] – particle type
par_count[out] – particle count

int yt_getGridInfo_FieldData(const long gid, const char *field_name, yt_data *field_data)

Get field data of grid with grid id = gid.

It searches simulation field data registered under libyt Python module, and returns YT_FAIL if error occurs.
gid is grid id passed in by user, it doesn’t need to be 0-indexed.
User should cast to their own datatype after receiving the pointer.
Returns an existing data pointer and data dimensions user passed in, and does not make a copy of it!!
Works only for 3-dim data.

yt_data data;
yt_getGridInfo_FieldData(gid, "field_name", &data);
double *field_data = (double *) data.data_ptr;

Parameters:

gid[in] – grid id
field_name[in] – queried field name
field_data[out] – field data pointer and metadata

Returns:

YT_SUCCESS or YT_FAIL

int yt_getGridInfo_ParticleData(const long gid, const char *ptype, const char *attr, yt_data *par_data)

Get particle data of grid with grid id = gid.

It searches particle data registered under libyt Python module, and returns YT_FAIL if error occurs.
gid is grid id passed in by user, it doesn’t need to be 0-indexed.
User should cast to their own datatype after receiving the pointer.
Returns an existing data pointer and data dimensions user passed in, and does not make a copy of it!!
For 1-dim data (like particles), the higher dimensions is set to 0.

yt_data data;
yt_getGridInfo_ParticleData(gid, "io", "PosX", &data);
double *par_data = (double *) data.data_ptr;

Parameters:

gid[in] – grid id
ptype[in] – queried particle type
attr[in] – queried attribute
par_data[out] – particle data pointer and metadata

Returns:

YT_SUCCESS or YT_FAIL

Defines

NULL¶

YT_SUCCESS¶

YT_FAIL¶

FLT_UNDEFINED¶

DBL_UNDEFINED¶

INT_UNDEFINED¶

LNG_UNDEFINED¶

Enums

enum yt_verbose¶

Values:

enumerator YT_VERBOSE_OFF¶: Turn off log

enumerator YT_VERBOSE_INFO¶: Log level info

enumerator YT_VERBOSE_WARNING¶: Log level warning

enumerator YT_VERBOSE_DEBUG¶: Log level debug

enum yt_dtype¶

Values:

enumerator YT_FLOAT¶: float

enumerator YT_DOUBLE¶: double

enumerator YT_LONGDOUBLE¶: long double

enumerator YT_CHAR¶: char

enumerator YT_UCHAR¶: unsigned char

enumerator YT_SHORT¶: short

enumerator YT_USHORT¶: unsigned short

enumerator YT_INT¶: int

enumerator YT_UINT¶: unsigned int

enumerator YT_LONG¶: long

enumerator YT_ULONG¶: unsigned long

enumerator YT_LONGLONG¶: long long

enumerator YT_ULONGLONG¶: unsigned long long

enumerator YT_DTYPE_UNKNOWN¶: unknown data type

struct yt_param_libyt¶

#include <yt_type_param_libyt.h>

Data structure of libyt runtime parameters.

Caution

The lifetime of script should cover the whole in situ process in libyt.

Public Members

yt_verbose verbose¶: Verbose log level

const char *script¶: Script name without the file extension .py

long counter¶: Number of iteration doing in situ analysis

bool check_data¶: Check the input data (e.g., hierarchy, grid information…)

struct yt_param_yt¶

#include <yt_type_param_yt.h>

Data structure to store YT-specific parameters and parameters to initialize the storage for AMR structure.

Note

Only support dim 3 AMR grid for now.

Public Members

const char *frontend¶: Name of the simulation code frontend in yt

const char *fig_basename¶: Base name of the output figures

double domain_left_edge[3]¶: Left edge of the simulation domain in code units

double domain_right_edge[3]¶: Right edge of the simulation domain in code units

double current_time¶: Simulation time in code units

double current_redshift¶: Redshift

double omega_lambda¶: Dark energy mass density

double omega_matter¶: Dark matter mass density

double hubble_constant¶: Dimensionless Hubble parameter at the present day

double length_unit¶: Simulation length unit in cm (CGS unit)

double mass_unit¶: Simulation mass unit in g (CGS unit)

double time_unit¶: Simulation time unit in s (CGS unit)

double velocity_unit¶: Simulation velocity unit in cm / s (CGS unit)

double magnetic_unit¶: Simulation magnetic unit in gauss

int periodicity[3]¶: Periodicity along each x,y,z dimension. (0/1 ==> No/Yes)

int cosmological_simulation¶: Cosmological simulation dataset (0/1 ==> No/Yes)

int dimensionality¶: Dimensionality (1/2/3), only support 3.

int domain_dimensions[3]¶: Number of cells along each x,y,z dimension on the root AMR level

int refine_by¶: Refinement factor between a grid and its subgrid

int index_offset¶: Offset of the index

long num_grids¶: Total number of grids

int num_fields¶: Number of fields

int num_par_types¶: Number of particle types

yt_par_type *par_type_list¶: Particle type list, the array has length num_par_types

int num_grids_local¶: Number of local grids in current rank

struct yt_array¶

#include <yt_type_array.h>

Data structure to store data generated by derived function or get particle functions.

Public Members

long gid¶: grid id

long data_length¶: length of the data pointer

void *data_ptr¶: data pointer

struct yt_field¶

#include <yt_type_field.h>

Data structure to store a field’s label and its definition of data representation.

field_unit, field_name_alias, field_display_name, are set corresponding to yt frontend ( "name", ("units", ["fields", "to", "alias"], "display_name")).

Caution

The lifetime of field_name and field_type should cover the whole in situ process.

The lifetime of field_unit, field_name_alias, field_display_name should cover ref yt_commit.

Public Members

const char *field_name¶: Field name

const char *field_type¶: Define type ("cell-centered", "face-centered", "derived_func")

yt_dtype field_dtype¶: Field data type

bool contiguous_in_x¶: true for x address alter-first ([z][y][x]); false for z address alter-first ([x][y][z])

short field_ghost_cell[6]¶: Number of cell to ignore at the beginning and the end of each dimension of a data pointer.

const char *field_unit¶: Field unit

int num_field_name_alias¶: Number of field name alias

const char **field_name_alias¶: A list of field name alias

const char *field_display_name¶: Field display name

void (*derived_func)(const int, const long*, const char*, yt_array*)¶: Derived function

struct yt_par_type¶

#include <yt_type_particle.h>

Data structure to store particle type names and their number of attributes.

Caution

For now, libyt only borrows the particle type par_type from simulation. The lifetime of par_type should cover the whole in situ process.

Public Members

const char *par_type¶: Particle type name

int num_attr¶: Number of attributes in this type

struct yt_attribute¶

#include <yt_type_particle.h>

Data structure to store particle attributes.

attr_unit, attr_name_alias, attr_display_name, are set corresponding to yt ( "name", ("units", ["alias1", "alias2"], "display_name"))

Caution

The lifetime of attr_name should cover the whole in situ analysis process.

The lifetime of attr_unit, attr_name_alias, attr_display_name should cover ref yt_commit

Public Members

const char *attr_name¶: Attribute name

yt_dtype attr_dtype¶: Attribute data type

const char *attr_unit¶: Attribute unit

int num_attr_name_alias¶: Number of attribute name alias

const char **attr_name_alias¶: A list of attribute name alias

const char *attr_display_name¶: Attribute display name

struct yt_particle¶

#include <yt_type_particle.h>

Data structure to store particle info and get particle function.

Caution

libyt only borrows the particle type par_type from simulation. The lifetime of par_type should cover the whole in situ process.

Public Members

const char *par_type¶: Particle type

int num_attr¶: Number of attributes

yt_attribute *attr_list¶: Attribute list

const char *coor_x¶: Attribute name of coordinate x

const char *coor_y¶: Attribute name of coordinate y

const char *coor_z¶: Attribute name of coordinate z

void (*get_par_attr)(const int, const long*, const char*, const char*, yt_array*)¶: Get particle function

struct yt_data¶

#include <yt_type_grid.h>

Data structure to store a field and particle data’s pointer and its array dimensions.

This struct will be used in yt_grid data member field_data and particle_data.
If data_dtype is set as YT_DTYPE_UNKNOWN, then libyt will use field_dtype defined in yt_field as input field data type.

Public Members

void *data_ptr¶: Data pointer

int data_dimensions[3]¶: Dimension of the data to be passed to Python for wrapping, which is the actual dimension of the array in its pov.

yt_dtype data_dtype¶: Data type

struct yt_grid¶

#include <yt_type_grid.h>

Data structure to store a full single AMR grid with data pointers.

Note

Only support dim 3 AMR grid for now.

Public Members

double left_edge[3]¶: Grid left edge in code units

double right_edge[3]¶: Grid right edge in code units

long *par_count_list¶: Array that records number of particles in each species, the input order should be the same as the input particle_list

long id¶: Grid id

long parent_id¶: Parent grid id (if no parent grid, set to -1)

int grid_dimensions[3]¶: Number of cells along each direction in [x][y][z]

int level¶: AMR level (0 for the root level)

int proc_num¶: Process number, grid belongs to which MPI rank

yt_data *field_data¶: Each element stores an info of field data to be wrapped

yt_data **particle_data¶: Ex: particle_data[0][1] represents particle data for particle_list[0].attr_list[1]