Adopt dni_clear variable name for clearsky DNI

[RDaxini]

• Related: Standardise variable name for clearsky GHI and DNI, add to glossary #2272
• I am familiar with the contributing guidelines
• Tests added modified
• Updates entries in docs/sphinx/source/reference for API changes.
• Adds description and name entries in the appropriate "what's new" file in docs/sphinx/source/whatsnew for all changes. Includes link to the GitHub Issue with :issue:`num` or this Pull Request with :pull:`num`. Includes contributor name and/or GitHub username (link with :ghuser:`user`).
• New code is fully documented. Includes numpydoc compliant docstrings, examples, and comments where necessary.
• Pull request is nearly complete and ready for detailed review.
• Maintainer: Appropriate GitHub Labels (including remote-data) and Milestone are assigned to the Pull Request and linked Issue.

dni_clear is already in the variables and symbols list
Also related: #1253, #2306

[AdamRJensen]

In both this PR and in #2273, you should use the decorate added in #2237.

The reason is that simply changing the parameter name would be a breaking change.

[RDaxini]

In both this PR and in #2273, you should use the decorate added in #2237.

The reason is that simply changing the parameter name would be a breaking change.

ah I asked about this in the linked issue as I thought it might be, thanks @AdamRJensen

[kandersolar]

These PRs will certainly need a whatsnew entry.

Has anyone audited iotools to see if we can standardize any clearsky DNI names there too?

[echedey-ls]

Mostly rST comments. PR looks good 🚀

Shall any .. deprecated or .. versionchanged directives be used? I'm +1 for the latter, I have the mild impression the former is for complete removals.

Docs at: https://pvlib-python--2274.org.readthedocs.build/en/2274/

• https://pvlib-python--2274.org.readthedocs.build/en/2274/whatsnew.html
• https://pvlib-python--2274.org.readthedocs.build/en/2274/reference/generated/pvlib.irradiance.dni.html#pvlib-irradiance-dni

[RDaxini]

Has anyone audited iotools to see if we can standardize any clearsky DNI names there too?

Variable maps exist.
psm3.py, solargis.py, sodapro.py, solcast.py, and solaranywhere.py map to *_clear, e.g:

pvlib-python/pvlib/iotools/psm3.py

Lines 28 to 30 in 6af80da

	'Clearsky GHI': 'ghi_clear',
	'Clearsky DHI': 'dhi_clear',
	'Clearsky DNI': 'dni_clear',

pvlib-python/pvlib/iotools/solargis.py

Lines 29 to 37 in 6af80da

	ParameterMap('GHI_C', 'ghi_clear'), # this is stated in documentation
	ParameterMap('GHIc', 'ghi_clear'), # this is used in practice
	ParameterMap('DNI', 'dni'),
	ParameterMap('DNI_C', 'dni_clear'),
	ParameterMap('DNIc', 'dni_clear'),
	ParameterMap('DIF', 'dhi'),
	ParameterMap('GTI', 'poa_global'),
	ParameterMap('GTI_C', 'poa_global_clear'),
	ParameterMap('GTIc', 'poa_global_clear'),

I'm not 100% familiar with how these maps work but I guess instances of other variable names that are part of the map, e.g.:

pvlib-python/pvlib/iotools/solcast.py

Lines 355 to 363 in 6af80da

	you can pass any of the parameters listed in the API docs, like
	>>> df, meta = pvlib.iotools.solcast.get_solcast_live(
	>>> latitude=-33.856784,
	>>> longitude=151.215297,
	>>> terrain_shading=True,
	>>> output_parameters=['ghi', 'clearsky_ghi', 'snow_soiling_rooftop'],
	>>> api_key="your-key"
	>>> )

do not matter because they will be mapped to *_clear(?)

I think the variable name on the left is external and right is pvlib internal, but then it looks like *_clear was already there before it was used in these functions in pvlib...? I might have misunderstood something here.

Can someone advise whether additional revisions are needed?

[kandersolar]

Thanks for checking. I think no action is needed in iotools then.

Shall any .. deprecated or .. versionchanged directives be used? I'm +1 for the latter, I have the mild impression the former is for complete removals.

Yes, I think so. Right now the docstring doesn't have any indication that the name changed. I like how @echedey-ls did it here: https://github.com/echedey-ls/pvlib-python/blob/1eb44a5d5788b398ae3333ae5f96a04df6567dea/pvlib/solarposition.py#L1351-L1356

[kandersolar]

LGTM. Any comments from others (@echedey-ls?)

[echedey-ls]

LGTM too!

[echedey-ls]

After some thought, I think stating the version when the legacy param names will be removed (clarifying edit: in the docstring admonition) would be useful, but neither essential nor a blocker for merging this PR. We can do that in the future or after taking care of #2325.