[IMPL] Implement 1D rainflow cycle counting algorithm

[MartinNesladek]

ℹ️ General Information

Component Name: Rainflow in 1D

Component Location: core/decompositions/uniaxial/

Suggested Python Name: rainflow

FABER WG Relation: 4.5

Brief Description: The rain-flow process on the chosen signal. Outputs positions in the original vector forming each cycle - these are referred to later and together with the input form the stress/strain levels

Priority: (1-10 scale) 10

Technical Complexity: (1-10 scale) 5

Estimated Effort: (1-10 scale) 5

Dependencies: structural_mechanics.stress

---

Implementation Details

The algorithm follows the standard rainflow counting procedure applied to a sequence of reversal points. It returns pairs of indices corresponding to stress values that form individual cycles. The reversal extraction procedure is included. However, all returned cycle indices MUST refer to the original stress vector, not to the reduced reversal sequence.

📋 Specification

1. Reversal extraction with index mapping

Given stress signal:

$$ S = {S_0, S_1, ..., S_n} $$

Extract reversal sequence:

$$ R = {R_0, R_1, ..., R_m} $$

together with index mapping:

$$ I = {i_0, i_1, ..., i_m}, \quad i_k \in {0, ..., n} $$

where:

$$ R_k = S_{i_k} $$

Important constraint: All further operations use $R_k$ for values but $i_k$ for indexing into $S$

---

2. Rainflow condition

For three most recent points:

$$ S_0 = R_{k-2}, \quad S_1 = R_{k-1}, \quad S_2 = R_k $$

Define ranges:

$$ \Delta_1 = |S_1 - S_0| $$ $$ \Delta_2 = |S_2 - S_1| $$

Cycle closure condition:

$$ \Delta_2 \ge \Delta_1 $$

---

3. Cycle definition

A closed cycle is formed between:

$$ (R_{k-2}, R_{k-1}) $$

but must be reported as indices in original signal:

$$ (i_{k-2}, i_{k-1}) $$

NOT:

$$ (k-2, k-1) $$

---

4. Half cycles

Remaining stack elements define half cycles:

$$ (i_j, i_{j+1}) $$

again referencing the original signal.

Inputs

Parameter	Symbol	Type	Description	Units	Constraints

Outputs

Parameter	Symbol	Type	Description	Units	Range

Expected Behavior

🔧 Implementation Guidelines

Function Signature

# Suggested function signature
def function_name():
    pass

Code Structure

Error Handling

✅ Validation & Testing

Test Cases

Test Case	Inputs	Expected Outputs	Notes
Example 1
Example 2

Validation Criteria

• Mathematical accuracy verified against literature
• Edge cases handled appropriately
• Output format matches specification

📚 References & Resources

📝 Technical Notes

Performance Considerations

Edge Cases to Handle

Special Requirements