cable_strength

AdditiveLayerRts

AdditiveLayerRts(cable_data: DataFrame)

Bases: ITensileStrength

Tensile strength model based on additive per-layer RTS contributions.

Computes RRTS as:

\[RRTS = RTS_{cable} - \sum_{i} cut\_strands_i \times rts\_layer_i\]

Parameters:

Name	Type	Description	Default
cable_data	DataFrame	Unit-converted cable data snapshot (e.g. from CableArray.data, validated against CableArrayInput). The class reads the following columns — all values must already be expressed in SI units (N for forces) as delivered by CableArray: rts_cable (int, optional/nullable): Rated Tensile Strength of the whole cable in N. Required by rrts and rts_coverage; raises RtsDataNotAvailable when absent or NaN. rts_layer_1 … rts_layer_8 (int, optional/nullable): RTS contribution of a single strand in each layer, in N. Used by rrts (when the corresponding cut_strands entry is non-zero) and by rts_coverage. Missing or NaN values are treated as 0 in rts_coverage but raise RtsDataNotAvailable in rrts if the layer has cut strands. nb_strand_layer_1 … nb_strand_layer_8 (int, optional/nullable): Number of strands in each layer. Used by nb_strand_per_layer, rts_coverage, and to enforce the cut_strands upper bound. Missing or NaN values are treated as 0. safety_coefficient (float, optional/nullable): Cable- specific safety coefficient. Falls back to options.data.safety_coefficient_default when absent or NaN.	required

Source code in src/mechaphlowers/core/models/cable/cable_strength.py

def __init__(self, cable_data: pd.DataFrame) -> None:
    self._cable_data: pd.DataFrame = cable_data
    self._cut_strands: np.ndarray = np.zeros(8, dtype=int)
    self._high_safety: bool = False

cut_strands property writable

cut_strands: ndarray

Number of cut strands per layer, as an 8-element integer array.

Index 0 = layer 1, …, index 7 = layer 8. Defaults to all zeros until explicitly set.

high_safety property writable

high_safety: bool

Enable or disable the additional safety coefficient security mechanism.

When enabled, the effective safety_coefficient is multiplied by 1.5, which tightens the utilization rate limit computed by utilization_rate.

nb_strand_per_layer property

nb_strand_per_layer: ndarray

Number of strands per layer, as an 8-element integer array.

Index 0 = layer 1, …, index 7 = layer 8. Returns zeros for layers whose column is absent or NaN in the catalog.

This value is informational. Cut strand enforcement is controlled by MAX_ALLOWED_CUT_STRANDS: when MAX_ALLOWED_CUT_STRANDS[i] > 0, cut_strands[i] cannot exceed that value.

rrts property

rrts: float

Residual Rated Tensile Strength (RRTS) in N.

RRTS = rts_cable - sum(cut_strands[i] * rts_layer{i+1} for i in 0..7)

Defaults to rts_cable when no cut strands have been set (all zeros).

Warning: rrts is designed to act globally for the section. If one strand is cut on a span, the whole section gets the same reduced RRTS, even if the cut strand is not on this span.

Raises:

Type	Description
RtsDataNotAvailable	if rts_cable is missing or NaN, or if cut_strands[i] > 0 but the corresponding rts layer column is missing or NaN in the catalog data.

safety_coefficient property

safety_coefficient: float

Effective safety coefficient used in the utilization rate.

Returns the catalog safety_coefficient value, or options.data.safety_coefficient_default when the column is absent or NaN. If high_safety is True, the value is multiplied by options.data.safety_security_factor.

rts_coverage

rts_coverage() -> float

Ratio of cable RTS to the sum of strand-level RTS contributions.

\[\text{rts_coverage} = \frac{\sum_{i} rts_{layer,i} \times nb_{strand,i}}{rts_{cable}}\]

This method is a checker for catalog data consistency: the output should ideally be close to 1.0 for a well-documented cable, but may be lower if the catalog is missing some strand-level RTS data (NaN values are treated as 0). A very low value may indicate that the cable-level RTS is not properly documented by the catalog.

Returns:

Name	Type	Description
float	float	sum(rts_layer_i * nb_strand_layer_i) / rts_cable.

Raises:

Type	Description
RtsDataNotAvailable	if rts_cable is missing or NaN.

Source code in src/mechaphlowers/core/models/cable/cable_strength.py

def rts_coverage(self) -> float:
    """Ratio of cable RTS to the sum of strand-level RTS contributions.

    $$\\text{rts_coverage} = \\frac{\\sum_{i} rts_{layer,i} \\times nb_{strand,i}}{rts_{cable}}$$

    This method is a checker for catalog data consistency: the output should ideally be close to 1.0 for a well-documented cable, but may be lower if the catalog is missing some strand-level RTS data (NaN values are treated as 0). A very low value may indicate that the cable-level RTS is not properly documented by the catalog.

    Returns:
        float: ``sum(rts_layer_i * nb_strand_layer_i) / rts_cable``.

    Raises:
        RtsDataNotAvailable: if ``rts_cable`` is missing or NaN.
    """
    rts_layers = np.nan_to_num(self._rts_layers_array(), nan=0.0)
    nb_strands = self.nb_strand_per_layer.astype(float)
    rts_layer_sum = float(rts_layers @ nb_strands)
    rts_cable_col = self._cable_data.get("rts_cable")
    if rts_cable_col is None or pd.isna(rts_cable_col.iloc[0]):
        raise RtsDataNotAvailable(
            "Cannot compute rts_coverage: 'rts_cable' is missing or NaN."
        )
    rts_cable = float(rts_cable_col.iloc[0])
    return rts_layer_sum / rts_cable

utilization_rate

utilization_rate(tension_sup_N: ndarray) -> ndarray

Utilization rate as a percentage of RTS, one value per span.

rate (%) = tension_sup_N / (RRTS * safety_coefficient) * 100

Parameters:

Name	Type	Description	Default
tension_sup_N	ndarray	Cable tensions in N, one value per span (e.g. tension_sup from BalanceEngine.get_data_spans()).	required

Returns:

Type	Description
ndarray	Array of utilization rates in % of RTS, same length as tension_sup_N.

Source code in src/mechaphlowers/core/models/cable/cable_strength.py

def utilization_rate(self, tension_sup_N: np.ndarray) -> np.ndarray:
    """Utilization rate as a percentage of RTS, one value per span.

    rate (%) = tension_sup_N / (RRTS * safety_coefficient) * 100

    Args:
        tension_sup_N: Cable tensions in N, one value per span (e.g.
            tension_sup from BalanceEngine.get_data_spans()).

    Returns:
        Array of utilization rates in % of RTS, same length as tension_sup_N.
    """
    return (
        np.asarray(tension_sup_N)
        / self.rrts
        * self.safety_coefficient
        * 100
    )

ITensileStrength

Bases: ABC

Abstract interface for cable tensile strength models.

Implementations are responsible for computing the Residual Rated Tensile Strength (RRTS) of a cable and the associated utilization rate, taking into account optional strand damage (cut_strands) and safety margins (high_safety).

cut_strands abstractmethod property writable

cut_strands: ndarray

Number of cut strands per layer, as an 8-element integer array.

high_safety abstractmethod property writable

high_safety: bool

Whether the additional safety coefficient security mechanism is enabled.

nb_strand_per_layer abstractmethod property

nb_strand_per_layer: ndarray

Number of strands per layer, as an 8-element integer array.

rrts abstractmethod property

rrts: float

Residual Rated Tensile Strength (RRTS) in N.

safety_coefficient abstractmethod property

safety_coefficient: float

Effective safety coefficient used in the utilization rate.

rts_coverage abstractmethod

rts_coverage() -> float

Ratio of cable RTS to the sum of strand-level RTS contributions.

Source code in src/mechaphlowers/core/models/cable/cable_strength.py

@abstractmethod
def rts_coverage(self) -> float:
    """Ratio of cable RTS to the sum of strand-level RTS contributions."""

utilization_rate abstractmethod

utilization_rate(tension_sup_N: ndarray) -> ndarray

Utilization rate as a percentage of RTS, one value per span.

Source code in src/mechaphlowers/core/models/cable/cable_strength.py

@abstractmethod
def utilization_rate(self, tension_sup_N: np.ndarray) -> np.ndarray:
    """Utilization rate as a percentage of RTS, one value per span."""