jcmwave_loadtable.m

Usage: table = jcmwave_loadtable(tableFile, [options])

Purpose:
  Loads a .jcm table file.

Input:
  tableFile -> path to a .jcm table file
  options -> key-value list (or matlab structure) used to configure the
             output format (see below). Currently, the only key is
             format with allowed values 'named', 'cell', 'matrix',

Output:
  The output depends on the optional format specification:
    format -> 'named' (default): The output is a matlab structure with
      entries (in fixed, non-alphabetical order)
        table.title -> title of the table
        table.header -> structure containing meta-information.
        table.<Data1>
         ...
        table.<DataN>  -> fields containing the table's data. <Data1>, ...
          <DataN> are the column names as found in the .jcm file. A column
          is not necessarily a (n_row x 1) vector. For example, the
          xyz-components of n_rows wave vectors are stored as a
          (n_row x 3) matrix. Numbered data of the same type are stored in
          cell arrays (see the example of a Fourier table below).
    format -> 'cell': returns data as a cell array ordered as above:
      table{1} -> table.title
      table{2} -> table.header
      table{3 : end} -> {table.<Data1>, ... table.<DataN>}

    format -> 'matrix': drops title and header entry returns complete
      table data as a (n_row x ?) matrix:
        table = [table.<Data1> ...
                 ...
                 table.<DataN>]

Examples:
  (1) Load table containing computed eigenvalues of a resonance mode
      or propagating mode problem:
        ev = jcmwave_loadtable('project_results/eigenvalues.jcm');

      In case of a propagating mode problem, the structure ev will contain
      the following fields (in given order)
        'title' -> title of the table
        'effective_refractive_index' -> computed propagating modes
        'precision' -> estimated accuracy of the computed modes

  (2) Load Fourier coefficient table as produced by post-process
      FourierTransform for a electromagnetic field scattering problem:
        ft = jcmwave_loadtable('project_results/fourier_transform.jcm')

      When the electric field components were computed, ft is a structure
      with the following fields (in given order):

        'title' -> title of the table
        'header' -> header containing meta-information, i.e. incoming
           field specifcation, permittivities of the lower and upper half
           space, reciprocal grid vectors for periodic problem, etc.
        'K' -> k-vectors of the sampling in k-space (n_row x 3) matrix
        'N1' ...
        'N2' -> defractions order with respect to first and second
                reciprocal grid vectors as given in the header (only
                present for periodic problems)
        'ElectricFieldStrength' -> electric field vectors of the Fourier
           modes. This is a cell array, where ft.ElectricFieldStrength{iF}
           refers to the iF-th computed electric field.

  (3) Load Fourier coefficients in matrix form:
        ft = jcmwave_loadtable('project_results/fourier_transform.jcm', ...
        'format', 'matrix');
      This yields a (n_row x ?) matrix containing the data as in (2):
        ft = [ft.N1;
              ft.N2;
              ft.ElectricFieldStrength{1};
              ...
              ft.ElectricFieldStrength{nF}]
      where nF is the number of computed electric fields.