Add option to control airmass/perez enhancement factor in clearsky.ineichen

[wholmgren]

See #435 for context.

• Closes Artefact in Ineichen clearsky model for sun close to horizon #435
• Fully tested. Added and/or modified tests to ensure correct behavior for all reasonable inputs. Tests must pass on the TravisCI and Appveyor testing services.
• Code quality and style is sufficient. Passes git diff upstream/master -u -- "*.py" | flake8 --diff and/or landscape.io linting service.
• New code is fully documented. Includes sphinx/numpydoc compliant docstrings and comments in the code where necessary.
• Updates entries to docs/sphinx/source/api.rst for API changes.
• Adds description and name entries in the appropriate docs/sphinx/source/whatsnew file for all changes.

Examples of ineichen with and without the enhancement at a few latitudes, with simplied solis as a reference:

While the differences at higher latitudes are more noticeable, the differences at lower latitudes are still notable: a few % difference at solar noon, unphysical pedestals near the horizon.

Many tests failed when I changed the default, so still work to do on that.

[wholmgren]

Some test failures are due to #481.

[wholmgren]

This PR is going to end up accomplishing most of the remaining work for #394.

To do includes:

• decouple ModelChain tests from clear sky calculation. would like to use new fixtures proposed in add PVSystem.losses_parameters, add support for custom pvwatts losses parameters in ModelChain #491
• update values in test_ineichen* failures
• figure outdetect_clearsky failures

[wholmgren]

I think this is close to ready to go. It needs someone to review it, especially the changes to clearsky.py and test_clearsky.py.

The majority of the other changes are cleaning up the test suite so that it's not tightly coupled to this function. The perez_enhancement change made all of those test functions fail so I think we had no choice but to address the broader changes here.

The detect_clearsky failures were caused by the scaling factor, alpha, changing in response to the ~1% change in ghi returned by the ineichen function. I adjusted the expected test values to get them to pass.

to do:

• add mock to min and py2 test environments
• fix failing test_location tests in py 3.4, 3.5 (syntax issue with mock)

[adriesse]

For what it's worth, I browsed through the changes and didn't notice any problems.

Is it possible to have tests that compare outputs to the previous stable release, instead of hard coding lists of constants?

[wholmgren]

Thanks @adriesse. Interesting idea to compare test results to previous stable releases. Maybe there is a framework/package for that?

[cwhanse]

In clearsky.py:

I recommend we remove the comment paragraphs at line 88 starting with "Dan's note..." and "Create the corrected TL..." This was developmental material in PVLib which was not included in the release.

We should revise the paragraph at line 104 to point to the Ineichen / Perez paper [1] as the reference. We should clarify that [2] implements a different version of the model in [1]. Suggest the following:

# ghi is calculated using either the equations in [1] by setting perez_enhancement=False (default behavior) or using the model in [2] by setting perez_enhancement=True.

[wholmgren]

@cwhanse I changed the comments. I'm not 100% sure I captured what you were going for.

I think this is ready to merge. The test pass on all Travis CI configurations. The appveyor test failures are intermittent and unrelated.

[cwhanse]

I think the comments are fine. My intent was to discard the no-longer relevant text from the Matlab file, and to clarify how this code implements the equations in those two Ineichen/Perez papers.

Any comments from others before this is merged?

[mikofski]

The changes to ineichen look good to me, I briefly glanced at some of the tests and mocker stuff, but not thoroughly. Thanks for making these changes.