Implement the Bagci equivalent stress amplitude function

[MartinNesladek]

ℹ️ General Information

Component Name: Bagci

Component Location: core/stress_life/damage_params/uniaxial_stress_eq_amp/

Suggested Python Name: calc_stress_eq_amp_bagci

FABER WG Relation: WG4.1

Priority: (1-10 scale) 2

Technical Complexity: (1-10 scale) 2

Estimated Effort: (1-10 scale) 2

Dependencies:

Related Issues: #60

---

📋 Problem Description

Implement the Bagci equivalent stress amplitude function enabling mean stress effect correction in stress-life calculation.

Mathematical Formulation

$$ \sigma_{a,eq}=\frac{\sigma_a}{1-\left( \frac{\sigma_m}{\sigma_y} \right)^4} $$

Latex text:

$$
\sigma_{a,eq}=\frac{\sigma_a}{1-\left( \frac{\sigma_m}{\sigma_y} \right)^4}
$$

🔧 Implementation Guideline

Function Signature

import numpy as np
from numpy.typing import ArrayLike, Optional, NDArray

def calc_stress_eq_amp_bagci(
    stress_amp: ArrayLike | np.float64,
    mean_stress: ArrayLike | np.float64,
    yield_strength: ArrayLike | np.float64,
    allow_neg_mean_stress: bool = True,
    rtol: float = _RTOL,
    atol: float = _ATOL,
) -> NDArray[np.float64]:
    """Calculate equivalent stress amplitude using Bagci criterion.

    The Bagci equivalent stress amplitude is calculated as:

    $$
    \sigma_{aeq}=\frac{\sigma_a}{1-\left(\frac{\sigma_m}{\sigma_y}\right)^4}
    $$

    Args:
        stress_amp: Array-like of stress amplitudes. Leading dimensions are preserved.
        mean_stress: Array-like of mean stresses. Must be broadcastable with
            stress_amp. Leading dimensions are preserved.
        yield_strength: Array-like of yield strengths. Must be broadcastable with
            stress_amp and mean_stress. Leading dimensions are preserved.
        allow_neg_mean_stress: A flag to control the calculation method.
            Defaults to True. If set to False, the equivalent stress amplitude will be
            set equal to the original stress amplitude for cases where the mean stress
            is negative, ignoring the correction.
        rtol: Relative tolerance for checking if mean stress magnitude is close to
            yield strength.
        atol: Absolute tolerance for checking if mean stress magnitude is close to
            yield strength.

    Returns:
        Array of equivalent stress amplitudes. Shape follows NumPy broadcasting
            rules for the input arrays.

    Raises:
        Warning: If mean stress magnitude exceeds yield strength ($|\sigma_m| > R_e$).
        Warning: If stress amplitude is negative ($\sigma_a < 0$).
        ValueError: If yield strength is not positive ($R_e > 0$).
        ValueError: If mean stress magnitude is close to yield strength
            (within tolerance), the equivalent stress amplitude tends to infinity.
            ($\left|\frac{\sigma_m}{R_e}\right| \approx 1.0$ within tolerance).
    """        
    pass  # Implementation goes here

Inputs

1. Static tensile parameters

   Parameter	Symbol	Type	Description	Units	Constraints
   yield_strength	$\sigma_{y}$	array of floats	Tensile yield strength	MPa	$>0$

2. Stress / Strain values

   Parameter	Symbol	Type	Description	Units	Range
   stress_amp	$\sigma_a$	array of floats	stress amplitude	MPa	$(0; \infty)$
   mean_stress	$\sigma_m$	array of floats	mean stress	MPa	$(-\infty;\infty)$

3. Additional inputs

   Parameter	Type	Description
   allow_neg_mean_stress	bool	Flag control for negative mean stress
   rtol	float	Relative tolerance used in np.close()
   atol	float	Absolute tolerance used in np.close()

Outputs

Parameter	Type	Description	Units	Range
$\sigma_{aeq}$	array of floats	Equivalent stress amplitude by Bagci	-	$(0;\infty)$

Expected Behavior

• Catch invalid material parameter $\sigma_y < 0$
• Catch invalid mathematical case, where the expression in denominator: $\left|\frac{\sigma_m}{\sigma_y}\right| \approx 1.0$ (use np.close() with accessible values of tolerances)
• Raise warning for cases where ($|\sigma_m| > \sigma_y$)
• Raise warning for cases where ($\sigma_a < 0$)
• Allow for negative mean stress handling based on user selected flag control: allow_neg_mean_stress
  • True $\rightarrow$ negative mean stress is used in calculation of equivalent stress amplitude $\sigma_{aeq}$
  • False $\rightarrow$ equivalent stress amplitude $\sigma_{aeq}$ is set to the original stress amplitude $\sigma_a$ in cases where mean stress is negative

✅ Validation & Testing

Test Cases for numerical calculation

Test Case	Inputs	Expected Outputs	Notes
Case 1	$\sigma_y = 500 MPa; \sigma_a = 180 MPa, \sigma_m = 100 MPa$	$\sigma_{aeq} = 180.29 MPa$	correct numerical calculation
Case 2	$\sigma_y = 500 MPa; \sigma_a = 180 MPa, \sigma_m = -100 MPa$	$\sigma_{aeq} = -180.29 MPa$	negative mean stress
Case 3	$\sigma_y = 500 MPa; \sigma_a = 180 MPa, \sigma_m = 0 MPa$	$\sigma_{aeq} = \sigma_a = 180 MPa$	zero mean stress
Case 4	$\sigma_y = 500 MPa; \sigma_a = 180 MPa, \sigma_m = -100 MPa$, allow_neg_mean_stress = False	$\sigma_{aeq} = \sigma_a = 180 MPa$	negative mean stress + flag control
Case 5	$\sigma_y = 500 MPa; \sigma_a = 180 MPa, \sigma_m = [-100, 0.0, 100] MPa$, allow_neg_mean_stress = False	$\sigma_{aeq} = [180, 180, 180.29] MPa$	flag control on array

Test cases for Broadcasting

test broadcasting of different combinations of 1D arrays with 2D arrays:

• one or more inputs 1D with other scalar inputs
• all inputs 1D
• one or more inputs 2D with other scalar inputs
• combination of 1D, 2D and scalar inputs

Test cases for raising Errors and Warnings

• test if ValueError is raised when $\sigma_y < 0$
• test if ValueError is raised when $\left|\frac{\sigma_m}{\sigma_y}\right| \approx 1.0$
• test if Warning is raised when $|\sigma_m| > \sigma_y$
• test if Warning is raised when $\sigma_a < 0$

Acceptance Criteria

• Implementation meets all specified requirements
• Code is well-documented and follows style guidelines
• All test cases pass successfully

📚 References & Resources

• Papuga 2018
• Bagci 1981