Document behavior of simple_efficiency when load_loss = 0

[kumaradityaapril]

Is your feature request related to a problem? Please describe.

The behavior of pvlib.transformer.simple_efficiency when load_loss = 0
is currently not documented.

In this case, the quadratic formulation leads to a division-by-zero
situation, resulting in NaN outputs or runtime warnings depending on
the execution context. While this behavior is being addressed in code,
the expected behavior and limitations of the model are not clearly
communicated to users.

Describe the solution you'd like

Add clarification to the simple_efficiency docstring and/or
documentation to explicitly state:

• That the model assumes load_loss > 0
• What happens when load_loss = 0
• Whether this represents an unsupported or degenerate case

This would help users understand model assumptions without needing to
inspect the implementation or encounter runtime warnings.

Additional context

Related issues and PRs:

• simple_efficiency raises ZeroDivisionError when load_loss=0 #2645 (division by zero when load_loss = 0)
• Fix ZeroDivisionError in simple_efficiency when load_loss=0 #2646 (code changes addressing this behavior)

This issue focuses only on documentation and user-facing clarity.
@

[AdamRJensen]

While the issue description might be technically correct, it is important to consider if it is worth the resources to solve it.

@kumaradityaapril How did you encounter this issue?

[kumaradityaapril]

@AdamRJensen
This came up when I was adding tests for simple_efficiency to increase test coverage.
I experimented with load_loss = 0 during edge case testing to better understand the model's behavior and noticed runtime warnings and NaN outputs as a result of division by zero.

This prompted me to examine the docstring, where I discovered that this restriction—that is, the presumption that load_loss > 0—is not made clear. Even if the underlying math stays the same, I felt it would be helpful to record the expected behavior and limitations because users might legitimately attempt to represent an idealized or simplified transformer with load_loss = 0.

I agree that this might not call for more complicated code, but I think making the documented assumptions clearer would help users avoid confusion.

[aman-coder03]

#2646 covers the docs part docs/sphinx/source/whatsnew/v0.14.1.rst

[kumaradityaapril]

Thank you for bringing that up.

I understand that this PR would be redundant because #2646 already addresses the whatsnew documentation for this behavior.

To prevent overlap, will close this issue