Uniaxial equivalent stress amplitude functionality

[KarasTomas]

Pull request following issue #60 and is prepared for other stress based uniaxial fatigue criteria like #40, #44 , #45 and #46.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[Vybornak2]

typo in the file name iniaxial

[Vybornak2]

This function seems to implement DRY principle, but to me seems a bit clunky and hard to extend

reason might be, that it is trying to do multiple things, so it does not have 1 responsibility only, thus it branches in its logic and is harder to fit to use cases.

think it through if it could not be improved

[Vybornak2]

I would convert ArrayLike to np.ndarray here and check for positive values
It is more explicit and does not create too much boilerplate code

In this case validate function seems as overkill to me

[Vybornak2]

I am not saying that we have to do that. Just going through cases of usage of validate function

[Vybornak2]

** 0.5 might be more readable than np.sqrt but it does not matter as much, just is more consistent with the mathematical formulas

[Vybornak2]

what about case, where user inputs real values, where some are simply too high, so some results are negative?
Is it okay to disallow user from calculating all values ?

I personally would rather raise warning and exclude it from this validation function

[Vybornak2]

validate function requires more then it brings value

[Vybornak2]

I would recommend using test classes to separate different test baste on function tested

[Vybornak2]

Test class than would be more generic, where each test case within the test class repeats for each tested function

class TestFunctioon1:
    def test_feature1():
        pass
    
    def test_feature2(): ...
 
# now same thing for class TestFunction2

[Vybornak2]

it puts a bit more structure into the test file, so it is easier to navigate
also you can run tests based on the test class and more

[Vybornak2]

Additionally the things should be added / considered:

• additional eq methods (please contact @MartinNesladek)
• STW for HCF docstring should include usage requirements and reference to SWT LCF (for now create issue placeholder until implementation)
• for each equivalent stress function should be specified what is it equivalent of (R = -1 standard or R=0, ....) and potentially other descriptive information
• consider/consult whether we should raise error for some conditions when mean stress is lower then zero or rather return stress amp as is

[KarasTomas]

On top of equivalent stress amplitude functionality requested by issues, several other functions were added based on this source: Mean stress effect in stress-life fatigue prediction re-evaluated

Use-case info blocks in docstrings still need to be revised.

[pavkukula]

SWT's validity condition σ_a > |σ_m| is incorrect — it rejects R≥0 loading, which is the canonical SWT case; should be σ_a + σ_m > 0.

invalid = (stress_amp_arr + mean_stress_arr) <= 0

[pavkukula]

ASME is more strict than Bagci/Gerber for no good reason
ASME raises for ratio >= 1.0 (combined). Bagci and Gerber raise only for ratio == 1.0 and merely warn for ratio > 1.0. The trouble: Bagci with σ_a=100, σ_m=600, R_e=500 returns σ_aeq ≈ -93 MPa with a warning — a non-physical negative equivalent amplitude that the caller can easily miss. Either align ASME's strict policy across all three (preferred — Papuga's §4 explicitly excludes such cases anyway, requiring σ_m < 0.75·R_e for these methods), or document why they differ.

[pavkukula]

ratio == 1.0 is a fragile float comparison
Exact float equality is brittle when inputs come from upstream computation rather than test literals.
np.isclose(ratio, 1.0) or ratio >= 1.0 (then warn separately for > 1.0) would be more robust.

[pavkukula]

Strongly compressive σ_m is silently accepted by Goodman/Linear/Morrow/Soderberg/Smith
E.g., Goodman with σ_a=100, σ_m=-1000, R_m=500 returns σ_aeq = 33.3 MPa (less than σ_a) — mathematically defined, physically dubious. Worth at least a Note: in the docstrings; an optional σ_m > -R_m-style sanity check would also be reasonable.

[pavkukula]

The structure is good — approved as the template, with three additions to bake in before you propagate, so all 11 get them:

1. Add a near-singularity test. test_mean_stress_close_to_yield_strength_error uses ms=500, ys=500 — that's ratio exactly 1.0, which a plain == 1.0 would also catch. Add a case with ms=499.97, ys=500 (ratio ≈ 0.99994) so the np.isclose tolerance is actually exercised — right now it isn't.
2. Assert the return dtype (np.float64) somewhere in test_broadcasting — assert_allclose only checks values.
3. Add a mixed-sign array case for allow_neg_mean_stress=False — e.g. σ_m=[-100,0,100] — the elementwise np.where is the point of the flag and no test covers it.

Also note for the warning-based methods (Bagci/Gerber/etc.): they'll each need a pytest.warns(UserWarning) test, which the ASME template doesn't include since ASME raises instead of warns (Bagci and Gerber do have a warning path, and that path needs to be tested.)

Question is whether Bagci and Gerber should warn-and-continue at all, or whether they should raise like ASME. Returning a negative equivalent stress amplitude with only a warning is arguably worse than just stopping, because a caller can easily miss a warning but can't miss an exception. That's a design decision for us: either make all three exponential methods raise (consistent, and then no pytest.warns test is needed anywhere), or keep the warn-vs-raise split deliberately (and then make sure each warning path gets a pytest.warns test). Either is defensible — it just needs to be decided rather than left as an accident of how the original code happened to be written.