Additional variable names request

[steve-ransome]

I'm trying to get my code for the Loss Factors and Mechanistic Performance Models working using this naming convention before the workshop on 5th Aug https://pvpmc.sandia.gov/7865-2/

There are a few parameters I found missing that may be useful to all and there will be a few that are maybe MLFM specific.
I've made a list with suggested variable names, maybe they can be added, or let me know whether they already exist, or if they should just be calculations in my code..

Useful for all

_norm (suffix for normalised measurements)
	
date_time	(suggest format YYYY-MM-DDTHH:MM:SS) or maybe pandas datetime?
wind_speed	(ms^-1)
wind_direction	(degrees)
poa_global_cSi	(unfiltered ref cell)
poa_global_cSi_kg3	(filtered reference cell)
gni	(global normal irradiance) (kW/m2)
relative_humidity	(%)
air_mass	(number)
xbi	(extraterrestrial beam irradiance) or xni?? (kW/m2)
xhi	(extraterrestrial horizontal  irradiance) (kW/m2)
kTh	(clearness index horizontal = ghi/xhi) (%)
kTn	(clearness index normal gni/xbi) (%)

beam_fraction	= (1- dhi/ghi) (%)
direct_fraction	= (dhi/ghi) (%)

Used by MLFM
rsc = -1/(dV/dI)|V=0 (Ohms)
roc = -1/(dV/dI)|V=Voc (Ohms)
i_half_vmp = current at Vmp/2 (A)
v_half_imp =voltage at Imp/2 (V)

Any help welcome!

[cwhanse]

We should add extraterrestrial irradiance and clearness index terms. 'xni' is too cryptic, but 'extraterrestiral_normal' is perhaps too long. Maybe 'extra_irrad' as the base, with '_normal', '_hor' as suffixes.

What is extraterrestrial 'beam' irradiance? Does beam refer to the plane of measurement?

'clearness_index' is understood to be GHI / extraterrestrial on the same plane, I'd prefer spelt out over 'kT' or any of the various symbols I've seen.

xbi (extraterrestrial beam irradiance) or xni?? (kW/m2)
xhi (extraterrestrial horizontal irradiance) (kW/m2)
kTh (clearness index horizontal = ghi/xhi) (%)
kTn (clearness index normal gni/xbi) (%)

[steve-ransome]

Sorry xbi or xni mean "normal to the sun" so around 1366 ± a few percent depending on the earth-sun distance from the orbit ellipticity.

[toddkarin]

Some of these parameters are already there: relative_humidity, wind_speed, wind_direction, airmass.
I just added date_time.

Small question: should we change airmass to air_mass? This would be more consistent with the rest of the variables.

I think we do not want to add a specific suffix for a reference cell measurement.

It would be good to have alignment with the choice of names for ground irradiance values. We currently have:

• poa_diffuse, poa_direct, poa_global, poa_ground_diffuse, poa_sky_diffuse, ghi, dhi

where poa stands for "plane-of-array irradiance."

I don't like using extra because that has another meaning. What about using xt or ext?

• ghi_xt, xti_direct, poa_global_xt, etc.

I could also get behind xbi and xhi.

We chose direct over beam in the past, but I think beam is a little more descriptive.

As with all these small decisions, nothing's perfect, but it's way better to just pick something than not finish this scheme.

[cwhanse]

I'm not fond of 'extra' either. I'm not strongly opposed to 'xni' or similar but haven't seen those terms used anywhere else. The common notation is H_extra or I_(some subscript) which doesn't translate to any particular words.

I also think the only extraterrestrial irradiance quantity in common use is extraterrestrial normal irradiance, i.e., outside the atmosphere on a plane normal to the the earth-sun line. Other terms may not be worth adding.

I would have no idea what 'ghi_xt' or 'poa_global_xt' meant - outside the atmosphere (xt) but measured on a what plane, exactly? 'global' doesn't add anything here, since irradiance from sources other than the sun aren't being considered.

[steve-ransome]

@toddkarin Thanks, where were the names listed? I looked on https://duramat.github.io/pv-terms/ and didn't see them

[toddkarin]

@steve-ransome I just rebuilt the docs, they should be there now.

@cwhanse I'm happy to add xbi and xhi if that's the only thing used. Do people never use a plane-of-array projection of extra-terrestrial irradiance?

[steve-ransome]

@toddkarin Thanks it has changed, wind is there now

[cwhanse]

I have only seen extraterrestrial irradiance calculated for planes normal to the sun, or horizontal to earth surface i.e. normal * cos(zenith). As far as 'xbi', since the middle character identifies the plane of measurement, I would use 'xni' so that the 'n' means the same thing as in 'dni'.

[toddkarin]

Okay, so I will add xni and xhi. Better to have an extra variable even if it is not typically used.

Are there any objections to adding these suggested values for xTh and xTn?

I'd suggest changing rsc to resistance_sc and including. Any objections?

Note that pvlib uses FD to mean the fraction of diffuse irradiance used by the module, so we should be a little careful here. I'm not sure how commonly used beam_fraction is but we can include this as well if it is a useful term.

[steve-ransome]

I'd prefer if possible to have rsc and roc as they are more tied in with isc and voc than resistance_shunt and resistance_series.

Also I use extraterrestrial irradiance on the poa as it is useful for some arrays with limited sensors as it gives a reasonable value of clearness index for a few hours around noon/

[toddkarin]

Okay, do we prefer poa_xti,xpoa or something else?

[steve-ransome]

Can we have a fill_factor?

How does interval work, is it _minute, _hour, day? How about _5min or _3hour (are they valid).

Several of the deprecated lines are wrong e.g. "imp [A]: Current at the maximum power point. [Deprecated/alternates: v_mp]"

Are the orders of the inverters going to be changed ? e.g. max_inv_dc_current should have current to the left.

Thanks

[wholmgren]

I've never cared for "extraterrestrial". The atmospheric sciences literature refers to top of atmosphere radiation, abbreviated TOA. toani? toa_ni? top_of_atmosphere_ni?

[toddkarin]

@steve-ransome Just added fill factor and fixed the deprecated lines.

For inverter inverter parameters, we should decide which style to use. E.g.

• min_inv_operating_temperature vs. temperature_inv_operating_min
• max_inv_dc_voltage vs. voltage_inv_dc_max

any preferences? The second style is more consistent with the rest of pv-terms, but I think it is also less easily understandable.

@wholmgren Yes extraterrestrial sounds like little green men. What about dni_toa, poa_toa, ghi_toa?

[wholmgren]

yes much better

[cwhanse]

I'd prefer to place '_min', '_max' at the end of a name, and begin the name with the quantity: "temperature_inv_operating_min" It's less readable but much easier to find in a long list of terms.

[toddkarin]

I've added toa variables, kTh, kTn, and changed the ordering for inverter parameters.

For direct_fraction and beam_fraction, is this supposed to be a poa variable? This is what I've added so far:

• Irradiance,beam_fraction,dimensionless,"Fraction of irradiance in beam component, beam_fraction = 1 - poa_diffuse/poa",
• Irradiance,diffuse_fraction,dimensionless,"Fraction of irradiance in diffuse component, beam_fraction = poa_diffuse/poa ",

I agree rsc is not a resistance like shunt resistance, but I think it would be better to write it out more since it is not a super commonly used variable. What about didv_oc and didv_sc, or impedance_oc?

For current_half_vmp, do we prefer this or the i_x notation from the Sandia 2004 paper? I think @cwhanse mentioned that he wanted to get away from the x and xx notation.

[cwhanse]

'rsc' is the dynamic resistance at short circuit, suggest 'resistance_dynamic_sc'?

what is 'kTh'? This is too cryptic for me. The notation for clearness index, or clearsky index, is not consistent in usage or literature.

[steve-ransome]

@toddkarin
current_half_vmp and voltage_half_imp are not the same as I_x and I_xx. When I developed the LFM I wanted to calculate the deviation measured from "extrapolated from isc,rsc and voc,roc" so chose these points rather than the SAPM I@0.5Voc and I@0.5(Voc+Vmp) as it seemed more symmetrical and easier to calculate the curvature parameters.

This is how my code currently looks, I use dataframes of ref, meas and norm and sim with the variables as columns at the moment so I am using meas['isc'] rather than isc_meas which would be equivalent.

I hadn't asked for ic and vc names tio be added, if they become common then I would welcome suggestions/

# calculate curvature parameters ic, vc to identify curvature/steps
# ic = "I@Vmp/2 measured value" / "expected from extrapolating Isc,Rsc" 
# indicates if shading or mismatch v<vmp if ic not ~1.00
norm['icurve'] = meas['i_half_vmp'] / (meas['isc']-meas['vmp'] / (2 * meas['rsc']))
    
# vc = "V@Imp/2 measured value" / "expected from extrapolating Voc,Roc"
# shows rollover/other problems v>vmp if vc not ~1.00
norm['vcurve'] = meas['v_half_imp'] / (meas['voc'] - meas['imp'] / 2 * meas['roc'])     

@cwhanse
I realise you are trying to keep things readable but I found it easier in the past with naming conventions to do

1. variable name
2. modifier(s)
3. level
4. id

if you do "temperature_inv_operating_min" then the inv (level) is mixed in with the modifiers, it might be better to do "temperature_operating_min_inv" as that would be easier to parse if you are measuring something at different levels.

You could maybe use double underscores to indicate the positions between them such as
"variable_modifier1_modifier2__level__id"

@toddkarin
rsc and roc to me are similar to isc and roc in that they are "something" at sc or oc. I also use rmp as similar format to imp, vmp and pmp (where rmp = - 1/ (dI/dV|V=Vmp). They look like they go together and I'd rather not change their names,

ALL
I'm finding that some of my code becomes incredibly long and it's difficult to see past a lot of code filled with long names such as "temperature_module" and "resistance_series". Also some of the variable names will be too long for some of the systems I have to write for.

I may have to use a long_form name (as you are doing) for contributions to PVLIB and a short_form name to actually use in systems.

I'm sure this could be converted with automated translations such as

resistance_series <-> rs

temperature_module <-> tmod

Is it worth having long and short forms in this? Or should I just work on this on my own?

I've used these in the past
diffuse_fraction = dhi/ghi,
beam_fraction = 1 - direct_fraction so these are on the horizontal plane.

[steve-ransome]

sorry I closed this by mistake and have reopened it

[cwhanse]

it might be better to do "temperature_operating_min_inv"

OK with me

I may have to use a long_form name (as you are doing) for contributions to PVLIB and a short_form name to actually use in systems.

I think the intent here is that a function signature (the argument list and the returned variables) uses long names. That's what creates compatibility across packages. Inside the function you can convert to whatever notation is convenient.

[steve-ransome]

I may have to use a long_form name (as you are doing) for contributions to PVLIB and a short_form name to actually use in systems.

I think the intent here is that a function signature (the argument list and the returned variables) uses long names. That's what creates compatibility across packages. Inside the function you can convert to whatever notation is convenient.

@cwhanse OK thanks, I'll use the long form for compatibility and a "consistent short form" inside the code. If an automated translation facility is of any use I can share.

One thing I think we haven't touched on is corrected data

Previously I had used these codes for example for isc --> isc_AGTS

isc or isc_U = uncorrected (default)

A = corrected for AOI/beam fraction/reflectivity
G = corrected for irradiance
T = corrected for Temperature
S = corrected for spectrum
etc.

I'd used capital, initial letters and concatenated them in alphabetical order e.g. isc_AT or isc_TS

I can't see an easy way of doing this that fits in with your conventions. Is this something we should consider or will it only be used internally?

For now I have used "tcorr" as in
norm['isc_tcorr'] = norm['isc'] * (1 - isc_a_ref * deltaT)

I would probably agtscorr if I did them all.

[toddkarin]

@steve-ransome I would say that the notation for temperature/irradiance/etc corrected values should be up to the user.

For clearness index, pvsyst uses kT = ghi/ghi_toa. Is there a downside to defining a variable clearness_ghi = ghi/ghi_toa? I would typically advocate for including a variable even if it is only sometimes used, however if this is not the universal definition it could be confusing.

[steve-ransome]

@steve-ransome I would say that the notation for temperature/irradiance/etc corrected values should be up to the user.

@toddkarin thanks

For clearness index, pvsyst uses kT = ghi/ghi_toa. Is there a downside to defining a variable clearness_ghi = ghi/ghi_toa? I would typically advocate for including a variable even if it is only sometimes used, however if this is not the universal definition it could be confusing.

@toddkarin That's the definition I use for what I called kTh, I also had versions for plane of array kTi and 2D tracker kTn for normal where you take the global/extraterrestrial ratios on horizontal, tilted fixed and 2d tracked planes.. I'm happy with names like clearness_ghi as it's clear what it means.

[toddkarin]

What about this for a set. Do you want different clearness_poa for poa_global and poa_direct?

Irradiance,clearness_ghi,dimensionless,"Horizontal clearness index, clearness_ghi = ghi/ghi_toa ",
Irradiance,clearness_dni,dimensionless,"Normal clearness index, clearness_dni = dni/dni_toa ",
Irradiance,clearness_poa_global,dimensionless,"Clearness index in plane-of-array, clearness_poa_global = poa_global/poa_toa ",
Irradiance,clearness_poa_direct,dimensionless,"Clearness index in plane-of-array, clearness_poa_direct = poa_direct/poa_toa ",
Irradiance,fraction_beam,dimensionless,"Fraction of irradiance in beam component, beam_fraction = 1 - poa_diffuse/poa",
Irradiance,fraction_diffuse,dimensionless,"Fraction of irradiance in diffuse component, beam_fraction = poa_diffuse/poa ",

[steve-ransome]

1. I couldn't see anything for Performance Ratio. I tend to use the terms prdc or prac. I'm not so keen on the terms performance_factor or module_ratio or anything that isn't clear exactly what it means.

2. Do we have a method to show if we use other than default measurement units? Here all irradiances are in W/m^2, I've always used kW/m^2 as I find it far easier for normalised measurement such as isc_norm or anything with kWh/m^2/d as we don't need to keep multiplying or dividing by 1000. In my code I have used the term poa_global_kw_m2 to signify that it's in kW/m^2.

input comes in W/m2 but is needed in kW/m2

meas['poa_global_kw_m2'] = meas['poa_global']/1000

calculate normalised mlfm values

norm['isc'] = meas['isc'] / (meas['poa_global_kw_m2'] * isc_ref )

3. With percentages of say 80% (e.g. relative humidity), this is listed as dimensionless, is this stored as 0.80 or as 80? I often see percentages stored as "80" but prefer the more meaningful "0.80"

[steve-ransome]

What about this for a set. Do you want different clearness_poa for poa_global and poa_direct?

Irradiance,clearness_ghi,dimensionless,"Horizontal clearness index, clearness_ghi = ghi/ghi_toa ",
Irradiance,clearness_dni,dimensionless,"Normal clearness index, clearness_dni = dni/dni_toa ",
Irradiance,clearness_poa_global,dimensionless,"Clearness index in plane-of-array, clearness_poa_global = poa_global/poa_toa ",
Irradiance,clearness_poa_direct,dimensionless,"Clearness index in plane-of-array, clearness_poa_direct = poa_direct/poa_toa ",
Irradiance,fraction_beam,dimensionless,"Fraction of irradiance in beam component, beam_fraction = 1 - poa_diffuse/poa",
Irradiance,fraction_diffuse,dimensionless,"Fraction of irradiance in diffuse component, beam_fraction = poa_diffuse/poa ",

@toddkarin that's quite a comprehensive list, although beam fraction and diffuse fraction will be dependent on poa and I had always used them as I said previously
"diffuse_fraction = dhi/ghi,
beam_fraction = 1 - direct_fraction so these are on the horizontal plane."

What do others think?

[toddkarin]

@mdeceglie what variable name do you prefer for performance ratio?

[toddkarin]

@steve-ransome Yes, there is an optional suffix for non-standard units.

Also, I prefer the more meaningful 0.80 over 80, i.e. stored as a fraction, not in percent.

[steve-ransome]

Here are a few more comments on version 0.1.1

Keep the variables in order "variable - modifier(s) - level - id"
so voltage_inv_ac_max --> voltage_ac_max_inv (or vac_max_inv)

Optional suffixes should be split into level identifiers and others as in

Optional Suffixes
These optional suffixes can be appended to a variable in order to further clarify which quantity the variable refers to. In the following * refers to another variable.

Levels
*_cell: Quantity relating to a single PV cell
*_array: Quantity relating to a number of PV strings.
*_module: Quantity relating to a single PV module
*_string: Quantity relating to a string of PV modules.
*_inv: Quantity relating to an inverter.
...
*_site: Quantity relating to a whole site.

Types of measurements
*_meas: Parameter measured from field data, e.g. voc_meas
*_norm: Normalized quantity
*_rated: Parameter on the datasheet or as-built.
*_sim: Parameter predicted from a model, e.g. voc_sim

Aggregated measurements (How are these to be used? show an example "_summed_day" ?)
*_summed: Quantity integrated over a specific length of time, e.g. day or month.
*_cumulative: Quantity integrated over a specific length of time, usually the full lifetime of the system.
*_interval: Quantity integrated over a specific length of time, usually a shorter timespan e.g. day or hour.

why not idc?
current_dc [A]: DC current.
isc [A]: Short circuit current. [Deprecated/alternates: i_sc]

inv or inverter ?
efficiency_inverter_eu [dimensionless]: Nominal inverter efficiency using European standard.
power_inv_ac_max [W]: Maximum inverter AC output power

modifiers relative or apparent first or last?
airmass_relative [dimensionless]: relative airmass
relative_humidity [dimensionless]: The ratio of the partial pressure of water vapor to the
apparent_solar_elevation [degrees]: Refraction-corrected solar elevation angle
energy_apparent [kWh]: Integral of apperent power over time.

random order
current_ac_inv_max [A]: Maximum inverter AC output current.
current_inv_dc_max [A]: Maximum inverter DC input current.

I think the beam fraction is usually specified on the horizontal plane not poa, this needs to be clear in the name.
fraction_beam [dimensionless]: Fraction of irradiance in beam component, beam_fraction = 1 - poa_diffuse/poa
fraction_diffuse [dimensionless]: Fraction of irradiance in diffuse component, beam_fraction = poa_diffuse/poa

measurement first, modifier second if possible e.g. height_array
array_height [m]: Height above ground of the bottom edge of the module for a fixed tilt system.

DateTime usually has a T as in date_time [YYYY-MM-DDTHH:MM:SS]: Date and time of measurement interval
Need to allow timezones too as in "2007-04-05T12:30-02:00"

[toddkarin]

Good suggestion, I've split the optional suffixes.

Anyone else have opinions about idc, current_dc, etc?

I'll switch to _inverter unless there are objections.

Regarding modifiers, there seemed to be a strong desire to make these "human readable" for certain variables.

Thanks for the random order suggestion.

I changed the definition for fraction diffuse:
Irradiance,fraction_beam,dimensionless,"Fraction of irradiance in beam component, beam_fraction = 1 - dhi/ghi",
Irradiance,fraction_diffuse,dimensionless,"Fraction of irradiance in diffuse component, beam_fraction = dhi/ghi",

Changed to height_array.

The standard pandas date time doesn't have the T in this document:
https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.to_datetime.html

Do we want a different variables for date_time_local vs. date_time_utc?

[cwhanse]

IMO, pvterms should recommend ISO 8601 datetime values, although this is getting a bit far from recommending a common name for datetime.

pandas understands ISO 8601, although I don't know why a space is substituted for the 'T' separator when values are displayed, perhaps to be more human friendly.

[steve-ransome]

Thanks for making many of the changes @toddkarin

I had suggested yesterday
Keep the variables in order "variable - modifier(s) - level - id"
so voltage_inv_ac_max --> voltage_ac_max_inv (or vac_max_inv)

But are still in this order "voltage_inv_ac_max", I think it makes more sense to put the "voltage" next to "ac", then the aggregator "max" followed by the level "inv"

I understand about "human readable" and agree that "relative humidity" sounds better than "humidity relative".
Maybe we can try to have the naming order I had suggested and list the terms that that don't follow it (e.g. relative_humidity).

I see there's been talk on what other coding conventions for pvwatts, pvsyst, rdtools etc which all differ

Couldn't we have a dictionary of approved terms for this work and then maintain look up terms for other conventions? e.g.

Name          :  unit  :     pvlib  : pvwatts :   pvsyst   :   rdtools   :   Definition  : Deprecated 
pmp [W]      :  [W]   :               :              :                :                  :  power at maximum power : p_mp
pmp_ref [W ]: [W]   :               :              :                :                  :  Power at maximum power point at reference conditions. etc. :

I think this would make it easier to follow and allow automated translation. I'd be happy to contribute to this work.`

What about
apparent_solar_elevation --> solar_elevation_apparent
surface_tilt --> tilt_surface
and similar
If not these should be listed in the non conforming list

What is the status of this convention , how much other code has been already translated to use it?

[steve-ransome]

My suggestions in bold

On the user guide page I suggest having the following,
a) change the naming order to keep the variable/modifier, then the level
b) Please show an example for interval as it is not clear
c) Also if you have an interval you can have an aggregation such as day_sum or hour_avg.
d) I'm not sure if we could do kWh/m^2 as a unit as the / and ^ characters may not be valid so have used kW_m2**

In order to standardize some common naming modifications, we have chosen a common order.

(1) _XX, where XX is the name of the particular system.
(2) _rated, _sim, _meas, _norm (select 0 or 1 only)
(3a) _interval,
(3b) _cumulative, **_sum, _mean, std (select 0 or 1 only) **
(4) _UNITS, where UNITS are the non-standard units of a variable. e.g. poa_global_kW_m2, module_area_feet2
**(5) ** _cell, _module, _string, _array, _inv, _site. (select 0 or 1 only)

For simplicity, it is not necessary to use all modifications for a particular variable, you must only use one option from each variable e.g. you can't have _rated_sim or _string_array.

Some examples:

temperature_module_12 Module temperature sensor 12.
current_dc_inv_2132: dc-side current from inverter 2132. --> current_dc_2132_inv
temperature_module_meas, temperature_module_sim: measured and simulated module temperature respectively.
beta_voc_module, beta_voc_string: beta_voc for a module and a string respectively.
alpha_isc_module_rated, alpha_isc_module_meas: rated and measured module alpha_isc.
energy_real_inv_12_sim_interval real energy for inverter 12 simulated on a specified interval. --> energy_real_12_sim_inv
temperature_cell_K Cell temperature in Kelvin.