BjnIO - библиотека
ввода/вывода сеточных функций
BjnIO_3D - библиотека ввода/вывода сеточных функций, заданных в узлах трёхмерных регулярных решёток, топологически эквивалентных индексным параллелепипедам. Функции библиотека являются последовательными и предназначены для выполнения на одном процессоре. Они могут быть использованы для вывода разных блоков с разных процессоров в разные файлы. При необходимости вывода в один файл с нескольких процессов синхронизация должна обеспечиваться дополнительными средствами. Основной целью создания библиотеки являлось обеспечение возможности компактного хранения и быстрого чтения сеточных функций, заданных в узлах одномерных, двумерных и трехмерных решеток большого размера (10^9 и более узлов).
Запись и чтение данных выполняется блоками произвольного размера, топологически эквивалентными индексным прямоугольникам. При записи выполняется сжатие без потери точности данных каждого из блоков. Для увеличения степени сжатия предусмотрена возможность игнорирования части младших разрядов мантиссы каждого из значений сеточной функции. Относительная ошибка огрубления данных, полученная в результате отбрасывания k двоичных разрядов мантиссы, приближенно может быть оценена как 2^(k-24). Для каждого из записываемых блоков параметр огрубления задаётся отдельно, что позволяет записывать значения сеточной функции, соответствующие разным фрагментам сетки, с разной точностью.
В каждом файле могут храниться блоки нескольких сеточных функций. Возможно чтение значений сеточной функции, соответствующих узлам произвольного, имеющего форму параллелепипеда, фрагмента сетки, но требуется, что бы все запрашиваемые значения были ранее записаны в составе некоторого набора блоков именно в том файле, из которого выполняется чтение.
Значение сеточной функции, соответствующее каждому из узлов сетки может быть записано в каждом из файлов не более одного раза – не допускается запись в один файл пересекающихся фрагментов сетки.
В качестве примера, приведем возможную двумерную конфигурацию записи двух сеточных функций (число узлов по первому индексу равно одному). В один файл в произвольном порядке могут быть записаны блоки, представленные на Рис. 1. Значения сеточной функции F1, соответствующие заштрихованному фрагменту сетки (Рис. 2) могут быть прочитаны, но чтение значений сеточной функции F2, соответствующих такому же фрагменту сетки, приведет к ошибке, поскольку не все значения присутствуют в файле.
Функция F1 Функция F2
Рисунок 1.
Функция F1 Функция F2
Рисунок 2.
Ограничения версии v.1
В версии v.1:
- число узлов по каждому направлению ограничено величиной 2^32;
- размер каждого из создаваемых файлов не должен превышать 2^31 байт;
- поддерживается ввод/вывод 32х битных вещественных чисел одинарной точности.
На число файлов, используемых для хранения значений сеточной функции, ограничений не накладывается.
Описание библиотечных функций
Используемые типы данных
typedef unsigned long big_size;
// в
версии v.1.х
беззнаковое целое 32х битное число
typedef float ***LPLPLPFLOAT;
// указатель
на трехмерный массив вещественных чисел
typedef void ***LPLPLPVOID;
// указатель на трехмерный массив
alloc_float_mas_n1_n2_n3
Выделение трехмерного массива вещественных чисел одинарной точности
LPLPLPFLOAT alloc_float_mas_n1_n2_n3 (
int n1, // число элементов по измерению 1
int n2, // число элементов по измерению 2
int n3 // число элементов по измерению 3
);
Функция возвращает указатель на выделенный массив, или NULL в случае ошибки.
free_mas_n1_n2_n3
Освобождение трехмерного массива, выделенного функцией alloc_float_mas_n1_n2_n3
void free_mas_n1_n2_n3(
LPLPLPVOID *p, // адрес указателя на трехмерный массив
int n1, // число элементов по измерению 1
int n2, // число элементов по измерению 2
int n3 // число элементов по измерению 3
);
Пример использования.
{
LPLPLPFLOAT f;
int n1=3,n2=2,n3=5;
f= alloc_float_mas_n1_n2_n3(n1,n2,n3);
if(!f)
printf(“Error\n”);
else
{
// обработка массива f
free_mas_n1_n2_n3((LPLPLPVOID *) &f);
}
}
WriteBjnGzippedScalar8RecInit
Создание и инициализация файла для записи значений сеточных функций
int WriteBjnGzippedScalar8RecInit(
LPCHAR target, // имя файла
LPCHAR grid_name, // имя файла сетки или ""
big_size n1, // число узлов сетки по направлению 1
big_size n2, // число узлов сетки по направлению 2
big_size n3 //
число узлов сетки по направлению 3
);
Возвращаемое значение: 0 - в случае успешного выполнения, код ошибки – в другом случае.
WriteBjnGzippedScalar8RecFuncMinMax
Запись минимального и максимального значения сеточной функции funcName.
int WriteBjnGzippedScalar8RecFuncMinMax(
LPCHAR target, // имя файла
LPCHAR funcName, // название сеточной функции
float fmin, //
минимальное значение сеточной функции
float fmax //
максимальное значение сеточной функции
);
Возвращаемое значение: 0 - в случае успешного выполнения, код ошибки – в другом случае.
WriteBjnGzippedScalar8RecFunc
Запись в файл очередной функции
int WriteBjnGzippedScalar8RecFunc(
LPCHAR target, // имя файла
LPCHAR funcName, // название сеточной функции
LPLPLPFLOAT f, //
трехмерный массив значений функции
big_size n1, // число узлов сетки по направлению 1
big_size n2, // число узлов сетки по направлению 2
big_size n3 // число узлов сетки по направлению 3
int nBitsReduce // число отбрасываемых бит мантиссы
);
Возвращаемое значение: 0 - в случае успешного выполнения, код ошибки – в другом случае.
WriteBjnGzippedScalar8RecFuncByBlock
Запись в файл очередного блока функции
int WriteBjnGzippedScalar8RecFuncByBlock(
LPCHAR target, // имя файла
LPCHAR funcName, // название сеточной функции
LPLPLPFLOAT f, //
трехмерный массив значений блока функции
big_size i0, // положение начала блока по направлению 1
big_size j0, // положение начала блока по направлению 2
big_size k0 // положение начала блока по направлению 3
big_size ni, // число узлов блока по направлению 1
big_size nj, // число узлов блока по направлению 2
big_size nk // число узлов блока по направлению 3
int nBitsReduce // число
отбрасываемых бит мантиссы
);
Возвращаемое значение: 0 - в случае успешного выполнения, код ошибки – в другом случае.
ReadBjnGzippedScalar8RecFunc
Чтение трехмерного массива значений сеточной функции
int ReadBjnGzippedScalar8RecFunc(
LPCHAR target, // имя файла
LPCHAR funcName, // название сеточной функции
LPLPLPFLOAT *pf, // адрес указателя на массив значений функции
big_size *pni, // указатель на число узлов по направлению 1
big_size *pnj, // указатель на число узлов по направлению 2
big_size *pnk // указатель на число узлов по направлению 3
);
Возвращаемое значение: 0 - в случае успешного выполнения, код ошибки – в другом случае.
ReadBjnGzippedScalar8RecFuncByBlock
Чтение трехмерного массива части значений сеточной функции
int ReadBjnGzippedScalar8RecFuncByBlock(
LPCHAR target, // имя файла
LPCHAR funcName, // название сеточной функции
LPLPLPFLOAT *pf, // адрес указателя на массив значений функции
big_size i0, // положение начала блока по направлению 1
big_size j0, // положение начала блока по направлению 2
big_size k0 // положение начала блока по направлению 3
big_size ni, // число узлов блока по направлению 1
big_size nj, // число узлов блока по направлению 2
big_size nk // число узлов блока по направлению 3
);
Возвращаемое значение: 0 - в случае успешного выполнения, код ошибки – в другом случае.