save format

Аннотация

Целью данного документа является определения формата HDF5, используемого Scilab'ом для хранения своих данных.

Этот формат называется SOD от английского Scilab Open Data ("открытые данные Scilab'а").

Первый публичный релиз SOD был сделан в Scilab 5.4.0.

Основная причина

Интероперабельность является одним из ключевых аспектов современного программного обеспечения. Для того, чтобы больше и больше улучшать этот аспект был предложено стандартное определение формата HDF5.

Со времён Scilab 5.2.0 была разработана возможность экспорта/импорта, которая используется для обмена данными. Это уже один из основных компонентов Xcos для хранения и обмена данными.

Поддерживаемые типы данных

Поддерживаются все типы данных Scilab'а. Например:

A=32;
b=[32,2];
c=[2,2;3,4];
d=rand(10,10);

a="my string";
b=["string 1";"my string 2"];

a=%t;
b=[%t, %f];

int8([1 -120 127 312])
x=int32(-200:100:400)

s=poly([2 3],"s")
poly(1:4,'s','c')

sp=sparse([1,2;4,5;3,10],[1,2,3])

dense=[%F, %F, %T, %F, %F
%T, %F, %F, %F, %F
%F, %F, %F, %F, %F
%F, %F, %F, %F, %T];
sp=sparse(dense)

l = list(1,["a" "b"])

t = tlist(["listtype","field1","field2"], [], []);

M=mlist(['V','name','value'],['a','b';'c' 'd'],[1 2; 3 4]);

Несколько "типов" основаны на tlist или mlist. Это rational, state-space, cell и struct. Следовательно, они явно сохраняются.

void и undefined - это два особых элемента, созданных для управления особыми случаями в управлении списками. Они описаны ниже.

Структура файла HDF5

Архитектура HDF5 Scilab'а довольно проста.

Для каждой переменной Scilab'а декларируется набор данных в корне. Имя набора данных - это имя переменной Scilab'а.

Например, следующий код:

emptyuint32matrix = uint32([]);
uint32scalar = uint32(1);
uint32rowvector = uint32([1 4 7]);
uint32colvector = uint32([1;4;7]);
uint32matrix = uint32([1 4 7;9 6 3]);
save("uint32.sod","emptyuint32matrix","uint32scalar","uint32rowvector","uint32colvector","uint32matrix");

формирует:

Каждый корневой набор данных имеет атрибут, именуемый SCILAB_Class. Этот атрибут определяет какие типы переменных хранятся в HDF5-файле.

Если переменная является основным типом и без связанных с ним комплексных значений, то данные сохраняются непосредственно в набор данных. В противном случае, набор данных содержит ссылки на фактические данные.

Каждый SOD-файл содержит две особые переменные:

• SCILAB_scilab_version - описывает какая версия Scilab'а использовалась для сохранения SOD-файла.

  Например, для Scilab 5.4.0 эти данные будут иметь вид:

  SCILAB_scilab_version = scilab-5.4.0

• SCILAB_sod_version - описывает какая версия спецификации SOD использовалась для сохранения файла.

  Например, для Scilab 5.4.0 эти данные будут иметь вид:

  SCILAB_sod_version = 2

Типы, данные которых сохраняются непосредственно в набор данных.

Для этих типов, как в Scilab'е, данные хранятся в одномерном массиве. Данные сохраняются столбец на столбцом.

Для восстановления матрицы, вектора или скаляра, два атрибута дают количество столбцов и строк.

Начиная с релиза 5.4.0 Scilab'а и SOD v2, SCILAB_cols и SCILAB_rows больше не используются для матриц типа double, integer, polynomial и string. SOD использует родную многомерную возможность HDF5.

Пример

Сохранение декларации: int32([1 -4 7;-9 6 -3]) будет отображено как:

в hdfview.

А метаданные будут отображены как:

Скалярное значение хранится в виде матрицы размером 1 на 1.

Пустая переменная ([]) будет иметь атрибут SCILAB_empty, установленный в значение ИСТИНА.

Типы, в которых данные хранятся в соответствующей группе

Многие типы данных Scilab'а хранятся с помощью групп. Это позволяет не только явно разделять значения, но и иметь лёгкий доступ к ним.

Группы именуются по переменным, заключённым в знак "#". Например, для матрицы значений типа double, названной matrixofdouble, имя корневого набора данных будет matrixofdouble, имя связанной с ней группы будет #matrixofdouble#.

Для рекурсивного типа данных (list, mlist, tlist и т. д.) имена подгрупп построены следующим образом:

Знак # позволяет создавать уникальный идентификатор. Количество начальных знаков # показывает уровень глубины. Следовательно подсписок ###listnested#_#2##_#1## будет указывать, что он помещён на второй уровень.

Символ подчёркивания "_" является способом представить глубину. Обычно в таких случаях используется символ "/", но это зарезервированное ключевое слово в спецификации HDF5.

Целые числа, используемые в названии, показывают положение в структуре данных, оба в терминах положения в текущей структуре, но также относительно родительского элемента. В примере ###listnested#_#2##_#1##, 1 показывает, что мы имеем дело со вторым элементом третьей структуры главного элемента (элементы индексируются начиная с 0).

В следующем примере, группа, названная ###listnested#_#2##_#1##, будет указывать на значение [32, 42]:

listnested=list(2,%i,'f',ones(3,3))
listnested(3) = list( %t, [32,42]);

Разрежённая матрица

Тип Scilab'а: sparse

атрибут HDF5 типа Scilab'а: SCILAB_Class = sparse

атрибуты HDF5:

SCILAB_rows = <int>

Количество строк

SCILAB_cols = <int>

Количество столбцов

SCILAB_items = <int>

Определение количества элементов разрежённой матрице

Значения корневого набора данных:

Первое значение (#0#): каждый элемент из этой структуры данных показывает количество ненулевых элементов на строку. Следовательно, первый элемент показывает количество элементов в первой строке разрежённой матрицы.

Второе значение (#1#): указывает положение столбца каждого элемента разрежённой матрицы.

Третье значение (#2#): хранит ссылку на фактические значения элементов в разрежённой матрице (каждое будет сохранено в особой группе).

Например, взяв такую матрицу:

0. 1. 0. 0. 0. 0. 0. 0. 0. 0.
0. 0. 0. 0. 0. 0. 0. 0. 0. 0.
0. 0. 0. 0. 0. 0. 0. 0. 0. 3.
0. 0. 0. 0. 2. 0. 0. 0. 0. 0.

которая формируется функцией:

sparse([1,2;4,5;3,10],[1,2,3])

будем иметь:

#0# содержит 1;0;1;1

#1# содержит 2;10;5

#2# обращается к матрице чисел типа double (в этом примере они не комплексные), которая содержит 1.0; 3.0; 2.0.

Разрежённая матрица логических значений

Тип Scilab'а: boolean sparse

атрибут HDF5 типа Scilab'а: SCILAB_Class = boolean sparse

атрибуты HDF5:

SCILAB_rows = <int>

Количество строк

SCILAB_cols = <int>

Количество столбцов

SCILAB_items = <int>

Определение количества элементов в разрежённой матрице

Значения корневого набора данных: в то время как разрежённая матрица имеет 3 набора данных, разрежённая матрица логических значений имеет только 2, поскольку определяемые значения автоматически рассматриваются как истинные.

Первое значение (#0#): каждый элемент этой структуры данных показывает количество ненулевых элементов в строке.

Следовательно, первый элемент показывает количество элементов в первой строке разрежённой матрицы.

Второе значение (#1#): указывает положение столбца каждого из элементов разрежённой матрицы.

В разрежённой матрице логических значений:

dense=[%F, %F, %T, %F, %F
%T, %F, %F, %F, %F
%F, %F, %F, %F, %F
%F, %F, %F, %F, %T];

#0# содержит 1;1;0;1.

#1# содержит 3;1;5.

Для восстановления разрежённой матрицы логических значений требуется только два значения.

Расположение типов данных HDF :32-битное целое

Числа удвоенной точности

Тип Scilab'а: double

атрибут HDF5 типа Scilab'а: SCILAB_Class = double

Значения корневого набора данных:

Как вещественные так и комплексные значения хранятся в группе, именуемой #<имя переменной>#.

Первое значение: ссылка на вещественные значения. Названо #0#.

Если матрица комплексная, то второе значение будет ссылаться на комплексные значения. Названо #1#.

Расположение типов данных HDF 64-битное с плавающей запятой

Полином

Тип Scilab'а: polynomial

атрибут HDF5 типа Scilab'а: SCILAB_Class = polynomial

атрибуты HDF5:

SCILAB_Class = polynomial

SCILAB_varname = <string>

Имя символьной переменной

SCILAB_Complex = <boolean>

Если полином комплексный (не устанавливается, если ложь).

Значения корневого набора данных:

Коэффициенты хранятся в виде матрицы чисел удвоенной точности (сравни соответствующий раздел, посвящённый хранению чисел удвоенной точности). Интересно отметить, что коэффициенты могут быть комплексными и, следовательно, могут храниться в виде матрицы комплексных значений. Правила наименования (под-)групп и набора данных описаны в начале этого раздела.

Расположение типов данных HDF ссылка на объект

Список

Тип Scilab'а: list

атрибут HDF5 типа Scilab'а:

SCILAB_Class = list

атрибуты HDF5: SCILAB_items = <количество пунктов в списке>

Значения корневого набора данных:

Привязанные к корневому набору данных значения хранятся в этом наборе и являются ссылками на значения, хранимые в списке. Значения хранятся в группе, названной #<имя переменной>#. В группе #<имя переменной># данные могут быть любого типа. Они прямо включены в группу. Их представления те же самые, что и в других случаях, основанных на рекурсивной структуре (имеется в виду, что можно сохранить и загрузить список списка списка различных типов).

Правила наименования (под-)групп и набора данных описаны в начале этого раздела.

Расположение типов данных HDF ссылка на объект

Типизированный список

Тип Scilab'а: tlist

атрибут HDF5 типа Scilab'а:

SCILAB_Class = tlist

атрибуты HDF5: см. список

матричноориентированный список

Тип Scilab'а: mlist

атрибут HDF5 типа Scilab'а:

SCILAB_Class = mlist

атрибуты HDF5: см. список

Пустое значение

Тип Scilab'а: void

атрибут HDF5 типа Scilab'а:

SCILAB_Class = void

Пустое значение можно найти только в очень особых случаях использования списков, типизированных списков и матричноориентированных списков. Оно может быть создано с помощью следующего синтаксиса:

voidelement_ref=list(1,,3);

Неопределённое значение

Тип Scilab'а: undefined

атрибут HDF5 типа Scilab'а:

SCILAB_Class = undefined

Неопределённое значение формируется, когда размер списка увеличивается, а некоторые элементы не определены. Они будут сформированы с помощью следующего синтаксиса:

undefinedelement_ref=list(2,%i,'f',ones(3,3));
undefinedelement_ref(6)="toto"

Примеры из жизни

Файлы с образцами всех этих переменных прилагаются к дистрибутиву Scilab'а. Они лежат в директории: SCI/modules/hdf5/tests/sample_scilab_data/

На момент редактирования этого документа были приложены следующие файлы:

История развития формата

Смотрите также

• save — Save a variable or a serie of variables in a binary file
• load — Load a saved variable or a serie of variables
• listvarinfile — список переменных в файле сохранённых данных
• type — возвращает тип переменной
• typeof — explicit type or overloading code of an object