Costa reference¶

The `Permap` class¶

Permap extends the class pandas.DataFrame by registering a DataFrame accessor named pm. Once Costa is imported, all Permap methods and attributes can be invoked by DataFrames in this way: df.pm.normalized.

class costa.permap.Permap(pandas_obj)¶

Complete missing values in a performance map.

Permap objects are accessible through the DataFrame accessor pm. They provide a handful of methods to help extend an initially incomplete performance map, given as a DataFrame.

Parameters: pandas_obj (pandas.DataFrame) – The DataFrame representing the performance map.

mode¶

The operating mode associated with the performance data.

Type: {‘heating’, ‘cooling’}, default None

normalized¶

True if the performance data is normalized. It is automatically set to True after using the normalize method.

Type: bool, default False.

entries¶

Entries for the missing quantities in the performance map. Particular entries can be set using self.entries[quantity] = list_of_entries

Type: dict, default {‘freq’: [0.2, 0.5, 1], ‘AFR’: [0, 1]}

corrections¶

Two-levels nested dictionary with single variable correction functions used to extend the performance map. A different correction should be provided for each input and output quantity. The keys of the first level are the input quantities and those of the second level are the output quantities. Dictionary values (the corrections) must be provided as functions with one argument. See examples for more details.

Type: dict, default None

initial_norm_values¶

Manufacturer tables are not always provided in rated conditions; for example, some performance tables are provided at maximum compressor frequency and not at the rated frequency value. For each normalized input quantity that is not in the initial performance table, this attributes specifies the value corresponding to the initial data, normalized by the actual rated value. If none have been set, the default dict {'freq': 1, 'AFR': 1} is assigned when the operating mode is set.

Type: dict, default None

ranges¶

Operating ranges for the input quantities of the performance map. The limits of the performance map are used for the default ranges.

Type: dict

restricted_levels¶

Each key corresponds to a level name of the performance map. The associated value is either None, 'left', 'right' or 'both', i.e. the side(s) where the level has already been restricted.

Type: dict

Examples

Build an incomplete performance map and set (missing) normalized frequency entries:

>>> hm = costa.build_heating_permap()
>>> hm.pm.entries['freq'] = np.arange(0.1, 2.1, 0.1)

There are no corrections or manufacturer values factors by default until the operating mode is set:

>>> hm.pm.corrections is None and hm.pm.initial_norm_values is None
True
>>> hm.pm.mode = 'heating'
>>> hm.pm.initial_norm_values
{'freq': 1, 'AFR': 1}
>>> corr = hm.pm.corrections['freq']['power']
>>> corr(0.5)
0.20785906320354824
>>> corr(1)
0.9999997589861805

If performances are not given at rated frequency, a correction factor must be set. Assuming performances are given at maximum frequency (120 Hz) and rated frequency is 60 Hz, the frequency correction ratio should be

>>> hm.pm.initial_norm_values['freq'] = 120 / 60

This value will affect the output of the method correct, and thus also extend and fill.

copyattr(other)¶: Return a copy of the Permap with some selected attributes copied from other.

correct(corrections, entry, initial=1)¶

Apply corrections to ouput quantities.

Parameters

corrections (dict) – A dict with output quantities to adjust as keys, and correction functions as values.
entry (int or float) – Value of the input quantity for which corrections are to be applied.
initial (int or float, default 1) – Initial normalized value (see attribute initial_norm_values).

Returns

A corrected copy of the original DataFrame.

Return type

DataFrame

Raises

RuntimeError – If there is an incoherence between the column index and the corrections keys (the ouput quantities to be corrected).

See also

extend: extend performance map using corrections.
fill: fill missing values in performance map.

extend(corrections, entries, name='new dim')¶

Extend the performance map along a new dimension.

Parameters

corrections (dict) – A dict with output quantities to adjust as keys, and correction functions as values.
entries (iterable of int or float) – Values of the input quantity for which corrections are to be applied.
name (str, default 'new dim') – Name of the quantity corresponding to the new dimension.

Returns

An extended copy of the original DataFrame.

Return type

DataFrame

Raises

RuntimeError – If there is an incoherence between the column index and the corrections keys (the ouput quantities to be corrected).

See also

correct: apply corrections to ouput quantities.
fill: fill missing values in performance map.

fill(norm=None)¶

Extend the performance to include frequency, air flow rate and (in cooling mode) wet-bulb temperature entries.

Parameters

norm (DataFrame, optional) – DataFrame with the rated values used for normalizing the data (see values argument in the normalize method documentation). If not provided, the data is not normalized.

Returns

An extended copy of the original DataFrame.

Return type

DataFrame

Raises

RuntimeError – If there is an incoherence between the column index and the corrections keys (the ouput quantities to be corrected).
RuntimeError – If the data is already normalized (normalized is True).
RuntimeError – If the operating mode is not yet set.

See also

correct: apply corrections to ouput quantities.
extend: extend performance map using corrections.
write: write performance map to file.

Examples

Build cooling performance map and set the missing frequency entries

>>> cm = costa.build_cooling_permap()
>>> cm.pm.mode = 'cooling'
>>> cm.pm.entries['freq'] =  np.arange(0.1, 1.5, 0.1)
>>> cm
cooling          capacity  power
Tdbr Twbr Tdbo
17.8 12.2 -10.0      3.03   0.28
          -5.0       3.01   0.33
           0.0       2.98   0.36
           5.0       2.96   0.39
           10.0      2.94   0.40
...                   ...    ...
32.2 22.8  25.0      4.44   0.65
           30.6      4.20   0.73
           35.0      3.94   0.81
           40.0      3.33   0.75
           46.0      3.07   0.75
[72 rows x 2 columns]

Fill values for frequency (‘freq’), wet-bulb room temperature (‘Twbr’) and air flow rate (‘AFR’), and normalize data:

>>> rated_values = pd.DataFrame({'capacity': [3.52], 'power': [0.79]})
>>> cm.pm.fill(norm=rated_values)
cooling                          power  sensible_capacity  latent_capacity
Tdbr Twbr Tdbo  AFR     freq
17.8 12.2 -10.0 0.00001 0.1   0.003268           0.010849         0.013296
                        0.2   0.015247           0.050620         0.062037
                        0.3   0.037015           0.122602         0.150254
                        0.4   0.068330           0.206249         0.252767
                        0.5   0.108010           0.264530         0.324193
                                ...                ...              ...
32.2 22.8  46.0 1.00000 0.9   0.821848           0.571090         0.206256
                        1.0   0.949367           0.640746         0.231413
                        1.1   1.064119           0.712520         0.257335
                        1.2   1.163336           0.777625         0.280849
                        1.3   1.245864           0.832545         0.300684
[11232 rows x 3 columns]

get_correction(input_quantity, output_quantity=None)¶

Retrieve some specific correction functions.

Parameters

input_quantity (str) – The input of the performance table, wich is the argument of the correction function to retrieve.
output_quantity (str, optional) – The output of the performance table to which the returned correction apply. By default, corrections for all outputs are returned in the form of a dictionary.

Returns

The correction function used to correct the value of the output quantity depending on the value of the input quantity, if the output quantity is specified. Otherwise, the correction function for each output quantity assembled in a dictionary.

Return type

callable or dict

Raises

RuntimeError – If the operating mode is not yet set.

See also

corrections: get all corrections as a dictionary.
set_correction: Equivalent of get_correction for setting a single correction.
set_corrections: Equivalent of get_correction for setting multiple corrections for a specific input quantity.

classmethod index_range(index, level)¶

Return the range of a pandas MultiIndex along a given level.

Parameters

index (pandas MultiIndex) – The index must have min and max methods.
level – The name of the level for which the range must be returned.

Returns

range of the index along the specified level, in the form (lower bound, upper bound).

Return type

pandas Interval

classmethod index_ranges(index)¶: Get ranges for each level of a pandas MultiIndex as a dict.

normalize(values=None)¶

Normalize values in the performance map.

Parameters

values (DataFrame, optional) – A DataFrame with one row containing the rated values of the performance map output quantities in its columns. The performance data will be normalized by those values. By default, values is None and in that case the original performance map is returned.

Returns

pm – A copy of the original performance map with performance values normalized according to the rated values, and the normalized attribute set to True.

Return type

DataFrame

Raises

RuntimeError – If the data is already normalized (normalized is True).
ValueError – If there is an inconsistency between the Permap column index and the rated values DataFrame column index.

See also

fill: Fill the missing values and optionally normalize the data in one go.

Examples

>>> cm = costa.build_cooling_permap()
>>> cm.pm.entries['freq'] =  np.arange(0.1, 1.5, 0.1)
>>> cm.pm.mode = 'cooling'
>>> cm
cooling          capacity  power
Tdbr Twbr Tdbo
17.8 12.2 -10.0      3.03   0.28
          -5.0       3.01   0.33
           0.0       2.98   0.36
           5.0       2.96   0.39
           10.0      2.94   0.40
...                   ...    ...
32.2 22.8  25.0      4.44   0.65
           30.6      4.20   0.73
           35.0      3.94   0.81
           40.0      3.33   0.75
           46.0      3.07   0.75
[72 rows x 2 columns]

>>> rated_values = pd.DataFrame({'capacity': [3.52], 'power': [0.79]})
>>> cm_norm = cm.pm.normalize(rated_values)
>>> cm_norm
cooling          capacity     power
Tdbr Twbr Tdbo
17.8 12.2 -10.0  0.860795  0.354430
          -5.0   0.855114  0.417722
           0.0   0.846591  0.455696
           5.0   0.840909  0.493671
           10.0  0.835227  0.506329
                   ...       ...
32.2 22.8  25.0  1.261364  0.822785
           30.6  1.193182  0.924051
           35.0  1.119318  1.025316
           40.0  0.946023  0.949367
           46.0  0.872159  0.949367
[72 rows x 2 columns]

Trying to normalize again will fail:

>>> cm_norm.pm.normalize(rated_values)
Traceback (most recent call last):
...
RuntimeError: values are already normalized.

set_correction(input_quantity, output_quantity, new_correction, inplace=False)¶

Set a correction function to adjust the value of a specific output quantity depending on a specific input quantity.

Parameters

input_quantity (str) – The input of the performance table, wich is the argument of the correction function to set.
output_quantity (str) – The output of the performance table to which the correction apply.
new_correction (callable) – The new correction to be set.
inplace (bool, default False) – If True, performs operation in-place and returns None.

Returns

If inplace is False, a copy of the DataFrame with the new correction is returned.

Return type

DataFrame or None

Raises

RuntimeError – If the operating mode is not yet set.

See also

corrections: get all corrections as a dictionary.
get_correction: Equivalent of set_correction for getting specific corrections.
set_corrections: Equivalent of set_correction for setting multiple corrections for a specific input quantity.

set_corrections(input_quantity, new_corrections)¶

Set a correction functions to adjust the value of all output quantities depending on a specific input quantity.

Parameters

input_quantity (str) – The input of the performance table, wich is the argument of the correction functions to set.
new_corrections (dict of callables) – The new corrections to be set, with keys corresponding to output quantities names.

Returns

A copy of the DataFrame with the new corrections is returned.

Return type

DataFrame

Raises

RuntimeError – If the operating mode is not yet set.

See also

corrections: get all corrections as a dictionary.
get_correction: Equivalent of set_corrections for getting specific corrections.
set_correction: Equivalent of set_corrections for setting a single correction.

update_data(df, update_ranges=True, keep_restrictions=False)¶

Return a new performance map with updated data.

Parameters

df (DataFrame) – The updated data.
update_ranges (bool, default True) – If False, the original operating ranges will be kept.
keep_restrictions (bool, default False) – If True, any level already restricted will keep the same restriction (‘left’, ‘right’ or ‘both’).

Returns

Data in df with attributes ranges and restricted_levels adjusted accordingly from the index of df.

Return type

DataFrame

write(filename, majororder='row')¶

Write performance map to a file using a format compatible with the TRNSYS Type 3254.

Parameters

filename (str) – The name of the file to be written to.
majororder ({'row', 'col'}) – Choose to write the performance map either in row- or column-major order.

The `defaults` module¶

The defaults module provide default correction functions used to obtain missing values in a performance map.

costa.defaults.build_default_corrections(mode)¶

Return a dict with all corrections for a certain operating mode.

Parameters: mode ({'cooling', 'heating'}) – The operating mode corresponding to the desired corrections.
Returns: default_corrections – Corrections for the specified mode.
Return type: dict

costa.defaults.compexp(x, amp, scale, shape, lift, shift)¶: Lifted and shifted version of the compressed exponential function.

costa.defaults.default_correction(mode, pminput, pmoutput=None)¶

Return performance map output correction.

Get a callable correction of a given output quantity depending on a certain input quantity in a specific operating mode.

Parameters

mode ({'cooling', 'heating'}) – The operating mode corresponding to the desired correction.
pminput ({'freq', 'AFR', 'Twbr', 'SHR'}) – The quantity which the desired correction should depend on. The ‘SHR’ option is only available in cooling mode.
pmoutput ({'COP', 'power'}, optional) – The quantity to which the desired correction should apply. Should not be specified when pminput is ‘SHR’.

Returns

correction – Correction for the specified quantities in the given mode.

Return type

callable

Examples

>>> corr = default_correction('heating', 'freq', 'power')
>>> corr(0)
0.0
>>> corr(0.8)
0.6267813236509203
>>> corr(1)
0.9999997589861805

costa.defaults.weibull(x, amp, scale, shape)¶: Scaled Weibull cumulative distribution function.

Costa reference¶

The `Permap` class¶

The `defaults` module¶

Navigation

Related Topics

Costa reference¶

The Permap class¶

The defaults module¶

The `Permap` class¶

The `defaults` module¶