Guide for MATLAB

Installation

Copy the folder libebf_multi-x.x.x/extra/libebf_matlab to a location of our choice. Now add the libebf_matlab folder to your search path by using set Path dialog box (File->Set Path->Add Folder->Save)

Then from MATLAB prompt (hereafter >>>) run the following command. After this you can start using the library.

>>> mex ebfc_lthash.c

For 32 bit machines, this might not work. In that case, in file EbfTable.m change

function ehash=ebflthash(mystr,capacity)
    ehash=ebfc_lthash(mystr,double(capacity));
end
to
function ehash=ebflthash(mystr,capacity)
    ehash=ebflthashm(mystr,double(capacity));
end

To load up the guide on matlab prompt do

>>> showdemo ebf_demo

To see if everything is working okay do

>>> ebf_test

Examples

Generate test data

>>> x1=linspace(1,10,10);
>>> x2=linspace(10,100,10);

Write data to an ebf file.

Ebf.write function is used for writing data. It can take upto a maximum of 6 arguments. First four are mandatory and the last two are optional.

• Optional fifth argument specifies the units of the data.
• Data to be written must be an array or a string.
• The data type of an array can be any one of the following
  • char
  • int8
  • int16
  • int16
  • int32
  • uint8
  • uint16
  • uint32
  • uint64
  • float32 (single)
  • float64 (double)

>>> Ebf.write('check.ebf','/x1',x1,'w','km/s')

Append data to an existing file

>>> Ebf.write('check.ebf','/x2',x2,'a')

Append to a new location

>>> Ebf.write('check.ebf','/test/x1',x2,'a')

Get a summary of the file

>>> Ebf.info('check.ebf')

file name: check.ebf
         data-name  data-type size      units  rank  dims
-----------------------------------------------------------
        /.ebf/info     *int64   8                1     5
      /.ebf/htable      *int8   1                1  1256
               /x1   *float64   8       km/s     1    10
               /x2   *float64   8                1    10
          /test/x1   *float64   8                1    10

Note on redundant dimensions

• Normally reduntant dimensions are removed i,e 1xN or Nx1 matrix is written as a rank 1 i.e one dimensional array array.
• If the optional 6th argument is ‘matlab’ then the shape of the array is exactly as given by matlab function size()

>>> Ebf.write('check.ebf','/x1_matlab',x1,'a','m/s','matlab')
>>> Ebf.write('check.ebf','/x1prime_matlab',transpose(x1),'a','m/s','matlab')
>>> Ebf.info('check.ebf')

 file name: check.ebf
          data-name  data-type size      units  rank  dims
-----------------------------------------------------------
         /.ebf/info     *int64   8                1     5
       /.ebf/htable      *int8   1                1  1256
                /x1   *float64   8       km/s     1    10
                /x2   *float64   8                1    10
           /test/x1   *float64   8                1    10
         /x1_matlab   *float64   8        m/s     2     1 10
    /x1prime_matlab   *float64   8        m/s     2    10 1

Check if a data object exists in a file.

Output is either 0 or 1. Note, the file specified must exist or else an error will be thrown.

>>> Ebf.containsKey('check.ebf','/x1')

ans =

     1

Read the data from an ebf file

>>> y1=Ebf.read('check.ebf','/x1')

y1 =
     1
     2
     3
     4
     5
     6
     7
     8
     9
     10

Read as a struct, multiple items in a specified path

The code below read everything in directory ‘/’ as a struct. This does not work recursively. For example this will not read /test/x1

>>> data=Ebf.read('check.ebf','/')

data =
         x1_matlab: [1 2 3 4 5 6 7 8 9 10]
                x1: [10x1 double]
                x2: [10x1 double]
    x1prime_matlab: [10x1 double]

Read as a structure, recursively traversing items in the path. This feature is experimental

>>> data=Ebf.read('check.ebf','/',1)

data =
        x1_matlab: [1 2 3 4 5 6 7 8 9 10]
               x1: [10x1 double]
               x2: [10x1 double]
   x1prime_matlab: [10x1 double]
             test: [1x1 struct]

Overwrite prevention.

Trying to overwrite as shown below will generate error

>>> Ebf.write('check.ebf','/x1',x1,'a')

Rename a data item in an ebf file

‘/x1’ is renamed to ‘/x3’ If one wishes to remove an item to trash the last argument should be ‘’

>>> Ebf.rename('check.ebf','/x1','/x3')
>>> Ebf.info('check.ebf')
>>> Ebf.rename('check.ebf','/x2','')
>>> Ebf.info('check.ebf')

  file name: check.ebf
           data-name  data-type size      units  rank  dims
-----------------------------------------------------------
          /.ebf/info     *int64   8                1     5
        /.ebf/htable      *int8   1                1  1256
                 /x3   *float64   8       km/s     1    10
                 /x2   *float64   8                1    10
            /test/x1   *float64   8                1    10
          /x1_matlab   *float64   8        m/s     2     1 10
     /x1prime_matlab   *float64   8        m/s     2    10 1
  file name: check.ebf
           data-name  data-type size      units  rank  dims
-----------------------------------------------------------
          /.ebf/info     *int64   8                1     5
        /.ebf/htable      *int8   1                1  1256
                 /x3   *float64   8       km/s     1    10
          /.tr/x2.t0   *float64   8                1    10
            /test/x1   *float64   8                1    10
          /x1_matlab   *float64   8        m/s     2     1 10
     /x1prime_matlab   *float64   8        m/s     2    10 1