Skip to content

Commit 50dcc7f

Browse files
authored
Rename eta_m and eta_m_ref to module_efficiency (#1218)
1 parent ca61503 commit 50dcc7f

File tree

7 files changed

+65
-42
lines changed

7 files changed

+65
-42
lines changed

docs/sphinx/source/whatsnew/v0.9.0.rst

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -67,6 +67,9 @@ Deprecations
6767
* ``ModelChain.weather``
6868
* ``ModelChain.times``
6969

70+
* The ``eta_m`` parameter for :py:func:`~pvlib.temperature.pvsyst_cell` is
71+
replaced by parameter ``module_efficiency``. (:issue:`1188`, :pull:`1218`)
72+
7073
Enhancements
7174
~~~~~~~~~~~~
7275
* Add :func:`~pvlib.iotools.read_bsrn` for reading BSRN solar radiation data

pvlib/modelchain.py

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -977,7 +977,7 @@ def infer_temperature_model(self):
977977
return self.faiman_temp
978978
elif {'noct_installed'} <= params:
979979
return self.fuentes_temp
980-
elif {'noct', 'eta_m_ref'} <= params:
980+
elif {'noct', 'module_efficiency'} <= params:
981981
return self.noct_sam_temp
982982
else:
983983
raise ValueError(f'could not infer temperature model from '

pvlib/pvsystem.py

Lines changed: 6 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -671,7 +671,9 @@ def pvsyst_celltemp(self, poa_global, temp_air, wind_speed=1.0):
671671
wind_speed = self._validate_per_array(wind_speed, system_wide=True)
672672

673673
def build_celltemp_kwargs(array):
674-
return {**_build_kwargs(['eta_m', 'alpha_absorption'],
674+
# TODO remove 'eta_m' after deprecation of this parameter
675+
return {**_build_kwargs(['eta_m', 'module_efficiency',
676+
'alpha_absorption'],
675677
array.module_parameters),
676678
**_build_kwargs(['u_c', 'u_v'],
677679
array.temperature_model_parameters)}
@@ -843,10 +845,10 @@ def _build_kwargs_noct_sam(array):
843845
# bundled with kwargs for simplicity
844846
temp_model_kwargs['noct'] = \
845847
array.temperature_model_parameters['noct']
846-
temp_model_kwargs['eta_m_ref'] = \
847-
array.temperature_model_parameters['eta_m_ref']
848+
temp_model_kwargs['module_efficiency'] = \
849+
array.temperature_model_parameters['module_efficiency']
848850
except KeyError:
849-
msg = ('Parameters noct and eta_m_ref are required.'
851+
msg = ('Parameters noct and module_efficiency are required.'
850852
' Found {} in temperature_model_parameters.'
851853
.format(array.temperature_model_parameters))
852854
raise KeyError(msg)

pvlib/temperature.py

Lines changed: 19 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,7 @@
66
import numpy as np
77
import pandas as pd
88
from pvlib.tools import sind
9+
from pvlib._deprecation import warn_deprecated
910

1011
TEMPERATURE_MODEL_PARAMETERS = {
1112
'sapm': {
@@ -285,7 +286,7 @@ def sapm_cell_from_module(module_temperature, poa_global, deltaT,
285286

286287

287288
def pvsyst_cell(poa_global, temp_air, wind_speed=1.0, u_c=29.0, u_v=0.0,
288-
eta_m=0.1, alpha_absorption=0.9):
289+
eta_m=None, module_efficiency=0.1, alpha_absorption=0.9):
289290
r"""
290291
Calculate cell temperature using an empirical heat loss factor model
291292
as implemented in PVsyst.
@@ -313,12 +314,14 @@ def pvsyst_cell(poa_global, temp_air, wind_speed=1.0, u_c=29.0, u_v=0.0,
313314
u_v : float, default 0.0
314315
Combined heat loss factor influenced by wind. Parameter :math:`U_{v}`
315316
in :eq:`pvsyst`.
316-
:math:`\left[ \frac{\text{W}/\text{m}^2}{\text{C}\ \left( \text{m/s} \right)} \right]`
317+
:math:`\left[ \frac{\text{W}/\text{m}^2}{\text{C}\ \left( \text{m/s} \right)} \right]` # noQA: E501
318+
319+
eta_m : numeric, default None (deprecated, use module_efficiency instead)
317320
318-
eta_m : numeric, default 0.1
319-
Module external efficiency as a fraction, i.e.,
320-
:math:`DC\ power / (POA\ irradiance \times module\ area)`.
321-
Parameter :math:`\eta_{m}` in :eq:`pvsyst`.
321+
module_efficiency : numeric, default 0.1
322+
Module external efficiency as a fraction. Parameter :math:`\eta_{m}`
323+
in :eq:`pvsyst`. Calculate as
324+
:math:`\eta_{m} = DC\ power / (POA\ irradiance \times module\ area)`.
322325
323326
alpha_absorption : numeric, default 0.9
324327
Absorption coefficient. Parameter :math:`\alpha` in :eq:`pvsyst`.
@@ -370,8 +373,13 @@ def pvsyst_cell(poa_global, temp_air, wind_speed=1.0, u_c=29.0, u_v=0.0,
370373
37.93103448275862
371374
"""
372375

376+
if eta_m:
377+
warn_deprecated(
378+
since='v0.9', message='eta_m overwriting module_efficiency',
379+
name='eta_m', alternative='module_efficiency', removal='v0.10')
380+
module_efficiency = eta_m
373381
total_loss_factor = u_c + u_v * wind_speed
374-
heat_input = poa_global * alpha_absorption * (1 - eta_m)
382+
heat_input = poa_global * alpha_absorption * (1 - module_efficiency)
375383
temp_difference = heat_input / total_loss_factor
376384
return temp_air + temp_difference
377385

@@ -719,7 +727,7 @@ def _adj_for_mounting_standoff(x):
719727
[0., 18., 11., 6., 2., 0.])
720728

721729

722-
def noct_sam(poa_global, temp_air, wind_speed, noct, eta_m_ref,
730+
def noct_sam(poa_global, temp_air, wind_speed, noct, module_efficiency,
723731
effective_irradiance=None, transmittance_absorptance=0.9,
724732
array_height=1, mount_standoff=4):
725733
r'''
@@ -744,9 +752,9 @@ def noct_sam(poa_global, temp_air, wind_speed, noct, eta_m_ref,
744752
Nominal operating cell temperature [C], determined at conditions of
745753
800 W/m^2 irradiance, 20 C ambient air temperature and 1 m/s wind.
746754
747-
eta_m_ref : float
755+
module_efficiency : float
748756
Module external efficiency [unitless] at reference conditions of
749-
1000 W/m^2 and 20C. Calculate as
757+
1000 W/m^2 and 20C. Denoted as :math:`eta_{m}` in [1]_. Calculate as
750758
:math:`\eta_{m} = \frac{V_{mp} I_{mp}}{A \times 1000 W/m^2}`
751759
where A is module area [m^2].
752760
@@ -810,6 +818,6 @@ def noct_sam(poa_global, temp_air, wind_speed, noct, eta_m_ref,
810818
# [1] Eq. 10.37 isn't clear on exactly what "G" is. SAM SSC code uses
811819
# poa_global where G appears
812820
cell_temp_init = poa_global / 800. * (noct_adj - 20.)
813-
heat_loss = 1 - eta_m_ref / tau_alpha
821+
heat_loss = 1 - module_efficiency / tau_alpha
814822
wind_loss = 9.5 / (5.7 + 3.8 * wind_adj)
815823
return temp_air + cell_temp_init * heat_loss * wind_loss

pvlib/tests/test_modelchain.py

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -201,7 +201,7 @@ def pvwatts_dc_pvwatts_ac_faiman_temp_system():
201201
@pytest.fixture(scope="function")
202202
def pvwatts_dc_pvwatts_ac_pvsyst_temp_system():
203203
module_parameters = {'pdc0': 220, 'gamma_pdc': -0.003}
204-
temp_model_params = {'u_c': 29.0, 'u_v': 0.0, 'eta_m': 0.1,
204+
temp_model_params = {'u_c': 29.0, 'u_v': 0.0, 'module_efficiency': 0.1,
205205
'alpha_absorption': 0.9}
206206
inverter_parameters = {'pdc0': 220, 'eta_inv_nom': 0.95}
207207
system = PVSystem(surface_tilt=32.2, surface_azimuth=180,
@@ -226,7 +226,7 @@ def pvwatts_dc_pvwatts_ac_fuentes_temp_system():
226226
@pytest.fixture(scope="function")
227227
def pvwatts_dc_pvwatts_ac_noct_sam_temp_system():
228228
module_parameters = {'pdc0': 220, 'gamma_pdc': -0.003}
229-
temp_model_params = {'noct': 45, 'eta_m_ref': 0.2}
229+
temp_model_params = {'noct': 45, 'module_efficiency': 0.2}
230230
inverter_parameters = {'pdc0': 220, 'eta_inv_nom': 0.95}
231231
system = PVSystem(surface_tilt=32.2, surface_azimuth=180,
232232
module_parameters=module_parameters,
@@ -710,7 +710,7 @@ def test_run_model_with_weather_noct_sam_temp(sapm_dc_snl_ac_system, location,
710710
weather['wind_speed'] = 5
711711
weather['temp_air'] = 10
712712
sapm_dc_snl_ac_system.temperature_model_parameters = {
713-
'noct': 45, 'eta_m_ref': 0.2
713+
'noct': 45, 'module_efficiency': 0.2
714714
}
715715
mc = ModelChain(sapm_dc_snl_ac_system, location)
716716
mc.temperature_model = 'noct_sam'
@@ -941,7 +941,7 @@ def test__prepare_temperature_arrays_weather(sapm_dc_snl_ac_system_same_arrays,
941941
ModelChain.faiman_temp),
942942
({'noct_installed': 45},
943943
ModelChain.fuentes_temp),
944-
({'noct': 45, 'eta_m_ref': 0.2},
944+
({'noct': 45, 'module_efficiency': 0.2},
945945
ModelChain.noct_sam_temp)])
946946
def test_temperature_models_arrays_multi_weather(
947947
temp_params, temp_model,

pvlib/tests/test_pvsystem.py

Lines changed: 13 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -392,7 +392,7 @@ def two_array_system(pvsyst_module_params, cec_module_params):
392392
temperature_model['noct_installed'] = 45
393393
# parameters for noct_sam temperature model
394394
temperature_model['noct'] = 45.
395-
temperature_model['eta_m_ref'] = 0.2
395+
temperature_model['module_efficiency'] = 0.2
396396
module_params = {**pvsyst_module_params, **cec_module_params}
397397
return pvsystem.PVSystem(
398398
arrays=[
@@ -471,8 +471,9 @@ def test_PVSystem_pvsyst_celltemp(mocker):
471471
temp_model_params = temperature.TEMPERATURE_MODEL_PARAMETERS['pvsyst'][
472472
parameter_set]
473473
alpha_absorption = 0.85
474-
eta_m = 0.17
475-
module_parameters = {'alpha_absorption': alpha_absorption, 'eta_m': eta_m}
474+
module_efficiency = 0.17
475+
module_parameters = {'alpha_absorption': alpha_absorption,
476+
'module_efficiency': module_efficiency}
476477
system = pvsystem.PVSystem(module_parameters=module_parameters,
477478
temperature_model_parameters=temp_model_params)
478479
mocker.spy(temperature, 'pvsyst_cell')
@@ -481,8 +482,9 @@ def test_PVSystem_pvsyst_celltemp(mocker):
481482
wind = 0.5
482483
out = system.pvsyst_celltemp(irrad, temp, wind_speed=wind)
483484
temperature.pvsyst_cell.assert_called_once_with(
484-
irrad, temp, wind, temp_model_params['u_c'], temp_model_params['u_v'],
485-
eta_m, alpha_absorption)
485+
irrad, temp, wind_speed=wind, u_c=temp_model_params['u_c'],
486+
u_v=temp_model_params['u_v'], module_efficiency=module_efficiency,
487+
alpha_absorption=alpha_absorption)
486488
assert (out < 90) and (out > 70)
487489

488490

@@ -500,16 +502,16 @@ def test_PVSystem_faiman_celltemp(mocker):
500502

501503

502504
def test_PVSystem_noct_celltemp(mocker):
503-
poa_global, temp_air, wind_speed, noct, eta_m_ref = (1000., 25., 1., 45.,
504-
0.2)
505+
poa_global, temp_air, wind_speed, noct, module_efficiency = (
506+
1000., 25., 1., 45., 0.2)
505507
expected = 55.230790492
506-
temp_model_params = {'noct': noct, 'eta_m_ref': eta_m_ref}
508+
temp_model_params = {'noct': noct, 'module_efficiency': module_efficiency}
507509
system = pvsystem.PVSystem(temperature_model_parameters=temp_model_params)
508510
mocker.spy(temperature, 'noct_sam')
509511
out = system.noct_sam_celltemp(poa_global, temp_air, wind_speed)
510512
temperature.noct_sam.assert_called_once_with(
511513
poa_global, temp_air, wind_speed, effective_irradiance=None, noct=noct,
512-
eta_m_ref=eta_m_ref)
514+
module_efficiency=module_efficiency)
513515
assert_allclose(out, expected)
514516
# dufferent types
515517
out = system.noct_sam_celltemp(np.array(poa_global), np.array(temp_air),
@@ -533,8 +535,8 @@ def test_PVSystem_noct_celltemp(mocker):
533535

534536

535537
def test_PVSystem_noct_celltemp_error():
536-
poa_global, temp_air, wind_speed, eta_m_ref = (1000., 25., 1., 0.2)
537-
temp_model_params = {'eta_m_ref': eta_m_ref}
538+
poa_global, temp_air, wind_speed, module_efficiency = (1000., 25., 1., 0.2)
539+
temp_model_params = {'module_efficiency': module_efficiency}
538540
system = pvsystem.PVSystem(temperature_model_parameters=temp_model_params)
539541
with pytest.raises(KeyError):
540542
system.noct_sam_celltemp(poa_global, temp_air, wind_speed)

pvlib/tests/test_temperature.py

Lines changed: 19 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,7 @@
66
from numpy.testing import assert_allclose
77

88
from pvlib import temperature, tools
9+
from pvlib._deprecation import pvlibDeprecationWarning
910

1011

1112
@pytest.fixture
@@ -72,7 +73,7 @@ def test_pvsyst_cell_default():
7273

7374
def test_pvsyst_cell_kwargs():
7475
result = temperature.pvsyst_cell(900, 20, wind_speed=5.0, u_c=23.5,
75-
u_v=6.25, eta_m=0.1)
76+
u_v=6.25, module_efficiency=0.1)
7677
assert_allclose(result, 33.315, 0.001)
7778

7879

@@ -96,6 +97,13 @@ def test_pvsyst_cell_series():
9697
assert_series_equal(expected, result)
9798

9899

100+
def test_pvsyst_cell_eta_m_deprecated():
101+
with pytest.warns(pvlibDeprecationWarning):
102+
result = temperature.pvsyst_cell(900, 20, wind_speed=5.0, u_c=23.5,
103+
u_v=6.25, eta_m=0.1)
104+
assert_allclose(result, 33.315, 0.001)
105+
106+
99107
def test_faiman_default():
100108
result = temperature.faiman(900, 20, 5)
101109
assert_allclose(result, 35.203, 0.001)
@@ -215,24 +223,24 @@ def test_fuentes_timezone(tz):
215223

216224

217225
def test_noct_sam():
218-
poa_global, temp_air, wind_speed, noct, eta_m_ref = (1000., 25., 1., 45.,
219-
0.2)
226+
poa_global, temp_air, wind_speed, noct, module_efficiency = (
227+
1000., 25., 1., 45., 0.2)
220228
expected = 55.230790492
221229
result = temperature.noct_sam(poa_global, temp_air, wind_speed, noct,
222-
eta_m_ref)
230+
module_efficiency)
223231
assert_allclose(result, expected)
224232
# test with different types
225233
result = temperature.noct_sam(np.array(poa_global), np.array(temp_air),
226234
np.array(wind_speed), np.array(noct),
227-
np.array(eta_m_ref))
235+
np.array(module_efficiency))
228236
assert_allclose(result, expected)
229237
dr = pd.date_range(start='2020-01-01 12:00:00', end='2020-01-01 13:00:00',
230238
freq='1H')
231239
result = temperature.noct_sam(pd.Series(index=dr, data=poa_global),
232240
pd.Series(index=dr, data=temp_air),
233241
pd.Series(index=dr, data=wind_speed),
234242
pd.Series(index=dr, data=noct),
235-
eta_m_ref)
243+
module_efficiency)
236244
assert_series_equal(result, pd.Series(index=dr, data=expected))
237245

238246

@@ -242,7 +250,7 @@ def test_noct_sam_against_sam():
242250
# NOCT cell temperature model), with the only change being the soiling
243251
# loss is set to 0. Weather input is TMY3 for Phoenix AZ.
244252
# Values are taken from the Jan 1 12:00:00 timestamp.
245-
poa_total, temp_air, wind_speed, noct, eta_m_ref = (
253+
poa_total, temp_air, wind_speed, noct, module_efficiency = (
246254
860.673, 25, 3, 46.4, 0.20551)
247255
poa_total_after_refl = 851.458 # from SAM output
248256
# compute effective irradiance
@@ -259,7 +267,7 @@ def test_noct_sam_against_sam():
259267
array_height = 1
260268
mount_standoff = 4.0
261269
result = temperature.noct_sam(poa_total, temp_air, wind_speed, noct,
262-
eta_m_ref, effective_irradiance,
270+
module_efficiency, effective_irradiance,
263271
transmittance_absorptance, array_height,
264272
mount_standoff)
265273
expected = 43.0655
@@ -268,14 +276,14 @@ def test_noct_sam_against_sam():
268276

269277

270278
def test_noct_sam_options():
271-
poa_global, temp_air, wind_speed, noct, eta_m_ref = (1000., 25., 1., 45.,
272-
0.2)
279+
poa_global, temp_air, wind_speed, noct, module_efficiency = (
280+
1000., 25., 1., 45., 0.2)
273281
effective_irradiance = 1100.
274282
transmittance_absorptance = 0.8
275283
array_height = 2
276284
mount_standoff = 2.0
277285
result = temperature.noct_sam(poa_global, temp_air, wind_speed, noct,
278-
eta_m_ref, effective_irradiance,
286+
module_efficiency, effective_irradiance,
279287
transmittance_absorptance, array_height,
280288
mount_standoff)
281289
expected = 60.477703576

0 commit comments

Comments
 (0)