### Navigation

- index
- modules |
- previous |
- fcres v0.1 Documentation »

# `fcres`

Load and analyze results from FCSys.

The “fcres.py” file can be executed at the command line. It will accept as an argument the name of a results file or a directory with multiple files. If no arguments are provided, then it gives a dialog to choose the file or folder. Finally, it provides a working session of Python with those results preloaded.

Example:

>     $ ./fcres.py demos/Polarization.mat
>     Cell simulation results have been loaded from "demos/Polarization.mat".
>     The CellSimRes instance is sim.
>     In [1]:

class `fcres.``CellLinRes`(fname='dslin.mat')

  Bases: `modelicares.LinRes`

  Fuel cell linearization results from FCSys and methods to analyze those results

  On initialization, load and preprocess the Dymola linearization file fname (MATLAB format).

class `fcres.``CellSimRes`(fname='Cell.mat', cell='cell')

  Bases: `fcres.SimRes`

  Fuel cell simulation results from FCSys and methods to analyze those results

  On initialization, load and preprocess the data.

  Arguments:

  - fname: Name of the Dymosim results trajectory file (*.mat)

  - cell: Name of the cell model in the trajectory file.

    > This should be relative to the top level of the simulated model and expressed in Modelica dot notation. If the cell is the simulated model, then this should be an empty string.

  `animate_quiverfig_current`(times, fname='current_eminus_xy')

    Create an animation of the x-direction current in the x-y plane.

    Arguments:

    - times: Times at which the frames should be generated

    - fname: Filename for the movie

      > ”.mpg” will be appended if necessary.

  `colorfig`(suffix, times=[0], n_rows=1, title='', subtitles=[], label='color', slice_axis='z', slice_index=0, xlabel='', xticklabels=[], xticks=[], ylabel='', yticklabels=[], yticks=[], clabel='', cbar_orientation='vertical', margin_left=0.125, margin_right=0.09999999999999998, margin_bottom=0.15, margin_top=0.050000000000000044, margin_cbar=0.2, wspace=0.1, hspace=0.25, cbar_space=0.1, cbar_width=0.05, **kwargs)

    Create a figure with 2D scalar data at given time(s) on a color axis in 2D Cartesian coordinates.

    Arguments:

    - suffix: Name of the variable to be plotted (relative to the names of the subregions)

    - times: List of times at which the data should be sampled

      > If multiple times are given, then subfigures will be generated.

    - n_rows: Number of rows of (sub)plots

    - title: Title for the figure

    - subtitles: List of subtitles (i.e., titles for each subplot)

      > If not provided, “t = xx s” will be used, where xx is the time of each entry. “(initial)” or “(final)” are appended if appropriate.

    - label: Label for the figure

      > This will be used as a base filename if the figure is saved.

    - slice_axis: Axis normal to the screen or page (‘x’, ‘y’, or ‘z’)

    - slice_index: Position along slice_axis

    - xlabel: Label for the x-axes (only shown for the subplots on the bottom row)

    - xticklabels: Labels for the x-axis ticks (only shown for the subplots on the bottom row)

    - xticks: Positions of the x-axis ticks

    - ylabel: Label for the y axis (only shown for the subplots on the left column)

    - yticklabels: Labels for the y-axis ticks (only shown for the subplots on the left column)

    - yticks: Positions of the y-axis ticks

    - clabel: Label for the color- or c-bar axis

    - cbar_orientation: Orientation of the colorbar (“vertical” or “horizontal”)

    - margin_left: Left margin

    - margin_right: Right margin (ignored if `cbar_orientation == 'vertical'`)

    - margin_bottom: Bottom margin (ignored if `cbar_orientation == 'horizontal'`)

    - margin_top: Top margin

    - margin_cbar: Margin reserved for the colorbar (right margin if `cbar_orientation == 'vertical'` and bottom margin if `cbar_orientation == 'horizontal'`)

    - wspace: The amount of width reserved for blank space between subplots

    - hspace: The amount of height reserved for white space between subplots

    - cbar_space: Space between the subplot rectangles and the colorbar

    - cbar_width: Width of the colorbar if vertical (or height if horizontal)

    - **kwargs: Propagated to `res.color()`

  `colorfig_pressure`(title='Pressure Profile', label='pressureprofile', times=None)

    Plot the pressure profiles of the subregions.

    Arguments:

    - title: Title for the figure

    - label: Label for the figure

      > This will be used as a base filename if the figure is saved.

    - times: List of times at which the data should be sampled

      > If multiple times are given, then subfigures will be generated.

  `currdenfig`(title=None, times=[0], z_index=0, leg_kwargs={}, **kwargs)

    Plot current densities of the cell segments at times.

    Arguments:

    - title: Title for the figure

    - times: List of times at which the data should be sampled

      > If multiple times are given, then subfigures will be generated.

    - z_index: z-index at which the current densities are taken

    - leg_kwargs: Dictionary of keyword arguments for `matplotlib.pyplot.legend()`

      > If leg_kwargs is None, then no legend will be shown.

    - **kwargs: Propagated to `barfig()`

  `gen_subtitles_time`(times)

    Generate titles for subplots at a list of times.

  `get_vector_comps2D`(axis, index, vect, times)

    Retrieve 2-dimensional vector components at specified times.

    Arguments:

    - axis: Slice axis (‘x’, ‘y’, or ‘z’)

    - index: Position along axis

    - vect: Name of the vector to be extracted (relative to the subregions)

      > vect should contain ‘%i’ where the vector indices should be inserted; the vector will be indexed according to the choice of slice_axis (see below). vect will be appended to the names of the subregions (separated by ‘.’) in order to determine the full names of the vectors.

    - times: Times at which to sample the vectors

    Returns:

    1. Tuple of the x-axis vector component (u) and the y-axis vector component (v)

       > Here, the x axis is in screen coordinates (left/right)—not model coordinates. The y axis is in also screen coordinates (bottom/top).

    2. Tuple of the number of subregions along the x- and y- axes

       > This will not be the same as (self.n_x, self.n_y) if a chemical component is not modeled within one or more of the subregions.

    3. Unit of the vector components

    4. 2D Boolean list indicating if a subregion actually contains the species)

  `label_layers`(axs, y=-0.11, ygap=0.03, shrink=0.2)

    Label the layers along the x axis of plot(s).

    Arguments:

    - axs: List of axes which should be labeled

    - y: Vertical position of the horizontal grouping bar

    - ygap: Vertical gap between the grouping bar and the top of the labels

    - shrink: Fraction that each grouping bar should shrink away from touching its neighbor

      > A value of 0.5 causes the bar to disappear.

  `layer`(i)

    Return the (abbreviated) name of the layer at a given x index (within the entire cell) and the x index within that layer.

    Arguments:

    - i: Index of the x axis (zero-based) within the entire cell—anode to cathode
  `plotfig_subregions`(prop, **kwargs)

    Plot a property within all subregions (by default, vs. time).

    Arguments:

    - prop: Name of the property

      > This will be appended to the names of the subregions (separated by ‘.’) in order to determine the names of the variables to plot on the primary y axis.

    - **kwargs: Propagated to `modelicares.plotfig()` (and thus to `res.plot()` and finally to `matplotlib.pyplot.plot()`)

  `quiverfig_subregions`(vect, times=[0], n_rows=1, title='', subtitles=None, label='quiver', slice_axis='z', slice_index=0, xlabel=None, xticklabels=None, ylabel=None, yticklabels=None, margin_left=0.125, margin_right=0.09999999999999998, margin_bottom=0.15, margin_top=0.050000000000000044, wspace=0.1, hspace=0.25, **kwargs)

    Create a figure with 2D vector data at given time(s) as arrows in 2D Cartesian coordinates.

    Arguments:

    - vect: Name of the vector to be plotted

      > vect should contain “%i” where the vector indices should be inserted; the vector will be indexed according to the choice of slice_axis (see below). vect will be appended to the names of the subregions (separated by ‘.’) in order to determine the full names of the vectors.

    - times: List of times at which the data should be sampled

      > If multiple times are given, then subfigures will be generated.

    - n_rows: Number of rows of (sub)plots

    - title: Title for the figure

    - subtitles: List of subtitles (i.e., titles for each subplot)

      > If not provided, “t = xx s” will be used, where xx is the time of each entry. “(initial)” or “(final)” is appended if appropriate.

    - label: Label for the figure

      > This will be used as a base filename if the figure is saved.

    - slice_axis: Axis normal to the screen or page (‘x’, ‘y’, or ‘z’)

    - slice_index: Position along slice_axis

    - xlabel: Label for the x-axes (only shown for the subplots on the bottom row)

      > If xlabel is None, then the axis is labeled with “X Axis”, “Y Axis”, or “Z Axis” (as appropriate).

    - xticklabels: Labels for the x-axis ticks

      > X-axis ticks are only shown for the subplots on the bottom row. If xticklabels is None, then the tick labels are “1”, “2”, ...

    - ylabel: Label for the y axis (only shown for the subplots on the left column)

      > If ylabel is None, then the axis is labeled with “X Axis”, “Y Axis”, or “Z Axis” (as appropriate).

    - yticklabels: Labels for the y-axis ticks

      > Y-axis ticks are only shown for the subplots on the left column. If None, then the tick labels are “1”, “2”, ...

    - margin_left: Left margin

    - margin_right: Right margin

    - margin_bottom: Bottom margin

    - margin_top: Top margin

    - wspace: The amount of width reserved for blank space between subplots

    - hspace: The amount of height reserved for white space between subplots

    - **kwargs: Propagated to `res.quiver()` (and thus to `matplotlib.pyplot.quiver()`)

  `sankeyfig_energy`()

    TODO

  `subregions_slice2D`(axis, index)

    Return a 2-dimensional slice of the names of the subregions.

    Arguments:

    - axis: The slice axis (‘x’, ‘y’, or ‘z’)
    - index: The index of the slice axis
  `subregions_w_prop`(prop)

    Return a list of the names of the subregions appended with the name of a property.

    Arguments:

    - prop: Name of the property to be appended

      > The ‘.’ separator is automatically inserted (between the names of the subregion and property).

class `fcres.``Conditions`

  Bases: `tuple`

  Conditions(cell_temp, composition, pressure, humidity, inlet_temp, flow)

  `cell_temp`

    Alias for field number 0

  `composition`

    Alias for field number 1

  `flow`

    Alias for field number 5

  `humidity`

    Alias for field number 3

  `inlet_temp`

    Alias for field number 4

  `pressure`

    Alias for field number 2

class `fcres.``SimRes`(fname='Cell.mat', cell='cell')

  Bases: `modelicares.SimRes`

  On initialization, load and preprocess the data.

  Arguments:

  - fname: Name of the Dymosim results trajectory file (*.mat)

  - cell: Name of the cell model in the trajectory file.

    > This should be relative to the top level of the simulated model and expressed in Modelica dot notation. If the cell is the simulated model, then this should be an empty string.

  `get_dimension`(names)

    Return the dimension(s) of trajectory variable(s).

    Arguments:

    - names: Name(s) of the variable(s) from which to get the dimension(s)

      > This may be a single string or (possibly nested) list of strings representing the names of the variables.

    If names is a string, then the output will be a single unit. If names is a (optionally nested) list of strings, then the output will be a (nested) list of units.

    Example:

        >>> from fcres import CellSimRes

        >>> sim = CellSimRes('demos/Polarization.mat')
        >>> sim.get_dimension('defaults.p')
        'm/(l.T2)'
        >>> sim.get_dimension([[['defaults.p', 'defaults.T']]])
        [[['m/(l.T2)', 'l2.m/(N.T2)']]]

  `get_unit`(names)

    Return the unit(s) for trajectory variable(s).

    The unit is the variable’s displayUnit attribute unless it is empty (‘’). In that case, the unit is taken from the global default_unit dictionary based on the variable’s dimension.

    Arguments:

    - names: Name(s) of the variable(s) from which to get the unit(s)

      > This may be a single string or (possibly nested) list of strings representing the names of the variables.

    If names is a string, then the output will be a single display unit. If names is a (optionally nested) list of strings, then the output will be a (nested) list of units.

    Note

    This method (`fcres.CellSimRes.get_unit()`) is different than `modelicares.SimRes.get_unit()`. In FCSys, the unit attribute is used to indicate the dimension of a quantity. The unit is given by the variable’s displayUnit attribute or the default unit based on the variable’s dimension, as described above.

    Example:

        >>> from fcres import CellSimRes

        >>> sim = CellSimRes('demos/Polarization.mat')
        >>> sim.get_unit('defaults.p')
        'kPa'
        >>> sim.get_unit([[['defaults.p', 'defaults.T']]])
        [[['kPa', 'K']]]

  `plotfig`(title='', label='xy', xname='Time', xlabel=None, xunit=None, ax1=None, ynames1=[], ylabel1=None, legends1=[], yunit1=None, leg1_kwargs={'loc': 'best'}, ax2=None, ynames2=[], ylabel2=None, legends2=[], yunit2=None, leg2_kwargs={'loc': 'best'}, prefix=False, **kwargs)

    Create a figure (or subfigure) of 1D data as points and/or curves in 2D Cartesian coordinates.

    Arguments:

    - title: Title of the figure

    - label: Label for the figure (ignored if ax is provided)

      > This will be used as a base filename if the figure is saved.

    - xname: Name of the x-axis data

    - xlabel: Label for the x-axis

      > If not provided, the variable’s Modelica description string will be used.

    - xunit: String indicating the unit for the x axis

      > If xunit is None, the Modelica variable’s displayUnit or the default unit based on the variable’s dimension will be used (in decreasing priority).

      > Note

      > Dimension checking is not currently performed, so it is important to ensure that a proper unit is chosen.

    - ax1: Primary y axes

      > If ax1 is not provided, then axes will be created in a new figure.

    - ynames1: Names of variables for the primary y axis

      > If any names are invalid, then they will be skipped.

    - ylabel1: Label for the primary y axis

      > If ylabel1 is None (default) and all of the variables have the same Modelica description string, then the common description will be used.

    - yunit1: String indicating the unit for the primary y-axis (see note for xunit)

      > If yunit1 is None, the Modelica displayUnit of the first entry of ynames1 or the default unit based on that variable’s dimension will be used (in decreasing priority).

    - legends1: List of legend entries for variables assigned to the primary y axis

      > If legends1 is an empty list ([]), ynames1 will be used. If legends1 is None, then no legend will be shown.

    - leg1_kwargs: Dictionary of keyword arguments for the primary legend

    - ax2, ynames2, ylabel2, legends2, leg2_kwargs: Similar to ax1, ynames1, ylabel1, legends1, and leg1_kwargs, but for the secondary y axis

    - prefix: If True, prefix the legend strings with the base filename of the class.

    - **kwargs: Propagated to `res.plot()` (and thus to `matplotlib.pyplot.plot()`)

      > If both y axes are used (primary and secondary), then the dashes argument is ignored. The curves on the primary axis will be solid and the curves on the secondary axis will be dotted.

    Returns:

    1. ax1: Primary y axes
    2. ax2: Secondary y axes

    Example:

        >>> import res
        >>> from fcres import CellSimRes

        >>> sim = CellSimRes('demos/Polarization.mat')
        >>> sim.plotfig(xname='cell.I',
        ...             ynames1='cell.v', ylabel1="Potential", legends1="Average voltage",
        ...             ynames2='cell.Wdot', ylabel2="Power", legends2="Power output",
        ...             title="Cell Polarization", label='demos/Polarization')
        (<matplotlib.axes.AxesSubplot object at 0x...>, <matplotlib.axes.Axes object at 0x...>)
        >>> res.save_figs()
        Saved demos/Polarization.pdf
        Saved demos/Polarization.png

  `unitmap`(unitstr)

    Return a function to map a quantity to a number in terms of a unit.

    Arguments:

    - unitstr: Unit string in Modelica notation

      > See also

      > Modelica Specification, version 3.3, p. 235–236 (https://www.modelica.org/documents)

      > In summary, ‘.’ indicates multiplication. The denominator is enclosed in parentheses and begins with ‘/’. Exponents directly follow the significand (e.g., no carat (‘^’)).

    Example:

        >>> from fcres import CellSimRes
        >>> sim = CellSimRes('demos/Polarization.mat')
        >>> kPa = sim.unitmap('kPa')

        >>> # Method 1:
        >>> p = sim.get_IV('defaults.p')
        >>> print("The pressure is %.1f kPa."%kPa(p))
        The pressure is 149.6 kPa.

        >>> # Method 2:
        >>> p_kPa = sim.get_IV('defaults.p', kPa)
        >>> print("The pressure is %.1f kPa."%p_kPa)
        The pressure is 149.6 kPa.

        >>> # In other units:
        >>> print("The pressure is %.1f kPag."%sim.unitmap('kPag')(p))
        The pressure is 48.3 kPag.
        >>> print("The pressure is %.0f Pa."%sim.unitmap('Pa')(p))
        The pressure is 149600 Pa.
        >>> print("The pressure is %.3f atm."%sim.unitmap('atm')(p))
        The pressure is 1.476 atm.
        >>> print("The pressure is %.3f bar."%sim.unitmap('bar')(p))
        The pressure is 1.496 bar.

`fcres.``gen_subtitle_conditions`(params, details)

  Create a description of the operating conditions (to be used as a subtitle).

  params: TODO details: TODO

`fcres.``multi_load`(location)

  Load multiple FCSys cell simulation and/or linearization results.

  Arguments:

  - location: Input directory, filename, or list of filenames

  Returns:

  1. List of cell simulations (`CellSimRes` instances)
  2. List of cell linearizations (`CellSimRes` instances)

  Either list may be empty.

`fcres.``multi_plotfig`(sims)

  Plot a property across a list of simulations.

  Arguments:

  - sims: List of simulations

`fcres.``presuffix`(items, prefix='', suffix='')

  Add a prefix and/or suffix to every entry in a list.

  The list may be multi-dimensional. This is useful to join names of subregions with the name of a property.

  Arguments:

  - items: The list of items
  - prefix: The prefix to add
  - suffix: The suffix to add

  Example:

      >>> presuffix(['fix', 'historic', 'date', 'view'], 'pre')
      ['prefix', 'prehistoric', 'predate', 'preview']

### Navigation

- index
- modules |
- previous |
- fcres v0.1 Documentation »