Using H2 Matrix File Storage

H2Pack supports storing/loading an H2 representation to/from a set of files following the H2 Matrix File Storage Scheme (draft).

Storing an H2 representation

To store an H2 representation to a set of files, you can use the H2P_store_to_file() function. The declaration of H2P_store_to_file() is:

// Store constructed H2 representation to files 
// Input parameters:
//   h2pack          : H2Pack structure after calling H2P_build()
//   meta_json_fname : Metadata JSON file name
//   aux_json_fname  : Auxiliary JSON file name
//   binary_fname    : Binary data file name
void H2P_store_to_file(
    H2Pack_p h2pack, const char *meta_json_fname, 
    const char *aux_json_fname, const char *binary_fname
);

This function requires an auxiliary python script examples/meta_txt_to_json.py in the H2Pack directory. Please copy this python script to the working directory of your application.

Reading an H2 representation

To load an H2 representation from a set of files, you can use the H2P_read_from_file() function. The declaration of H2P_read_from_file() is:

// Load a constructed H2 representation from a set of files
// Input parameters:
//   meta_json_fname : Metadata JSON file name
//   aux_json_fname  : Auxiliary JSON file name, can be NULL
//   binary_fname    : Binary data file name
//   BD_JIT          : If H2Pack should use just-in-time matvec mode, 0 or 1
//   krnl_param      : Pointer to the krnl_eval parameter buffer
//   krnl_eval       : Pointer to the kernel matrix evaluation function, can be NULL
//   krnl_bimv       : Pointer to the kernel matrix bi-matvec function, can be NULL
//   krnl_bimv_flops : Number of flops required for each bi-matvec operation, for performance statistic only
// Output parameter:
//   *h2pack_ : H2Pack structure constructed from given files
// Notes:
//   If only meta_json_fname and binary_fname are valid non-empty values, the constructed
//   H2Pack matrix can only be used to perform H2P_matvec(). Performing other operations
//   may crash the program. 
void H2P_read_from_file(
    H2Pack_p *h2pack_, const char *meta_json_fname, const char *aux_json_fname, 
    const char *binary_fname, const int BD_JIT, void *krnl_param, 
    kernel_eval_fptr krnl_eval, kernel_bimv_fptr krnl_bimv, const int krnl_bimv_flops
);

This function requires an auxiliary python script examples/meta_json_to_txt.py in the H2Pack directory. Please copy this python script to the working directory of your application.

H2Pack H2 file storage examples

H2Pack provides two H2 file storage example programs. These example programs are located in the examples directory and you can compile all example programs using make -f GCC-OpenBLAS.make or make -f ICC-MKL.make (see Installing H2Pack for choosing the makefile).

To generate a set of example H2 storage files, you can run examples/example_H2.exe. No parameters are needed. The generated H2 storage files are Coulomb_3D_1e-6_meta.json, Coulomb_3D_1e-6_aux.json, and Coulomb_3D_1e-6.bin. The generated H2 storage file names can be changed in examples/example_H2.c.

To construct an H2Pack structure from a set of H2 storage files, you can run examples/example_read_H2_file.exe. No parameters are needed. The target H2 storage files to read are Coulomb_3D_1e-6_meta.json, Coulomb_3D_1e-6_aux.json, and Coulomb_3D_1e-6.bin. The target H2 storage file names can be changed in examples/example_read_H2_file.c.