section_study

SectionStudy

SectionStudy(
    cable_array: CableArray,
    section_array: SectionArray,
    span_model_type: Type[ISpan] = CatenarySpan,
    deformation_model_type: Type[
        IDeformation
    ] = DeformationRte,
)

User-facing facade that bundles all engines for a power-line section.

SectionStudy creates a BalanceEngine and a PositionEngine eagerly, wiring the observer chain so that every solve automatically refreshes downstream geometry. A PlotEngine, ThermalEngine, and Guying are created lazily on first access to avoid unnecessary dependencies (e.g. plotly).

All state-management features (save / restore, rollback on solver error, intermediate warm-start) live here so that BalanceEngine is never modified.

Parameters:

Name	Type	Description	Default
cable_array	CableArray	Cable specification data.	required
section_array	SectionArray	Support / section data.	required
span_model_type	Type[ISpan]	Span model class. Defaults to CatenarySpan.	CatenarySpan
deformation_model_type	Type[IDeformation]	Deformation model class. Defaults to DeformationRte.	DeformationRte

Examples:

>>> study = SectionStudy(cable_array, section_array)
>>> study.solve_adjustment()
>>> study.solve_change_state(wind_pressure=200, new_temperature=90)
>>> points = study.get_supports_points()

Source code in src/mechaphlowers/api/section_study.py

def __init__(
    self,
    cable_array: CableArray,
    section_array: SectionArray,
    span_model_type: Type[ISpan] = CatenarySpan,
    deformation_model_type: Type[IDeformation] = DeformationRte,
) -> None:
    self._cable_array = cable_array
    self._section_array = section_array
    self._span_model_type = span_model_type
    self._deformation_model_type = deformation_model_type
    self._manipulation = Manipulation(section_array)

    self._balance_engine = BalanceEngine(
        cable_array=cable_array,
        section_array=section_array,
        span_model_type=span_model_type,
        deformation_model_type=deformation_model_type,
    )
    self._caretaker = BalanceEngineCaretaker(self._balance_engine)
    self._position_engine = PositionEngine(self._balance_engine)
    self._plot_engine: PlotEngine | None = None
    self._thermal_engine: ThermalEngine | None = None
    self._guying: Guying | None = None
    self._intermediate_memento: BalanceEngineMemento | None = None

intermediate_memento property

intermediate_memento: BalanceEngineMemento | None

The memento captured after the intermediate warm-start solve, if any.

manipulation property

manipulation: Manipulation

The [Manipulation][mechaphlowers.core.manipulation.Manipulation] object storing geometric overlays.

add_loads

add_loads(
    load_position_distance: ndarray | list,
    load_mass: ndarray | list,
) -> None

Calls preferred method set_loads.

This method is kept for compatibility.

Expected length for load_position_distance and load_mass is the number of pylons. Last array elements should be nan or zero.

Raises:

Type	Description
ValueError	if at least one load_position_distance is not in [0, span_length] or if the arguments don't have the right lengths.

Source code in src/mechaphlowers/api/section_study.py

def add_loads(
    self,
    load_position_distance: np.ndarray | list,
    load_mass: np.ndarray | list,
) -> None:
    """Calls preferred method [`set_loads`](mechaphlowers.api.section_study.SectionStudy.set_loads).

    This method is kept for compatibility.

    Expected length for load_position_distance and load_mass is the number of pylons. Last array elements should be nan
    or zero.

    Raises:
        ValueError: if at least one load_position_distance is not in [0, span_length]
            or if the arguments don't have the right lengths.
    """
    warnings.warn(
        "add_loads is deprecated, use set_loads instead."
        "Caution: expected argument length for set_loads is the number of spans.",
        category=DeprecationWarning,
    )
    load_position_distance = np.array(load_position_distance)
    load_mass = np.array(load_mass)
    self.set_loads(arr.decr(load_position_distance), arr.decr(load_mass))

add_rope

add_rope(
    rope: dict[int, float],
    rope_lineic_mass: float | None = None,
) -> None

Override insulator length and mass for specified supports with rope values.

Delegates to [Manipulation.add_rope][mechaphlowers.core.manipulation.Manipulation.add_rope].

Parameters:

Name	Type	Description	Default
rope	dict[int, float]	Dictionary mapping support index (0-based) to rope length (meters).	required
rope_lineic_mass	float | None	Linear mass of the rope in kg/m.	None

Source code in src/mechaphlowers/api/section_study.py

def add_rope(
    self,
    rope: dict[int, float],
    rope_lineic_mass: float | None = None,
) -> None:
    """Override insulator length and mass for specified supports with rope values.

    Delegates to [`Manipulation.add_rope`][mechaphlowers.core.manipulation.Manipulation.add_rope].

    Args:
        rope: Dictionary mapping support index (0-based) to rope length (meters).
        rope_lineic_mass: Linear mass of the rope in kg/m.
    """
    self._manipulation.add_rope(rope, rope_lineic_mass)

add_virtual_support

add_virtual_support(
    virtual_support: dict[int, dict[str, float]],
) -> None

Insert virtual supports.

Delegates to [Manipulation.add_virtual_support][mechaphlowers.core.manipulation.Manipulation.add_virtual_support].

Parameters:

Name	Type	Description	Default
virtual_support	dict[int, dict[str, float]]	Dictionary mapping left-support index to virtual support parameters.	required

Source code in src/mechaphlowers/api/section_study.py

def add_virtual_support(
    self, virtual_support: dict[int, dict[str, float]]
) -> None:
    """Insert virtual supports.

    Delegates to [`Manipulation.add_virtual_support`][mechaphlowers.core.manipulation.Manipulation.add_virtual_support].

    Args:
        virtual_support: Dictionary mapping left-support index to virtual
            support parameters.
    """
    self._manipulation.add_virtual_support(virtual_support)

get_data_spans

get_data_spans() -> dict[str, list]

Delegate to BalanceEngine.get_data_spans.

Returns:

Type	Description
dict[str, list]	dict[str, list]: Dictionary with span data (parameter, tensions, etc.).

Source code in src/mechaphlowers/api/section_study.py

def get_data_spans(self) -> dict[str, list]:
    """Delegate to [`BalanceEngine.get_data_spans`][mechaphlowers.core.models.balance.engine.BalanceEngine.get_data_spans].

    Returns:
        dict[str, list]: Dictionary with span data (parameter, tensions, etc.).
    """
    return self._balance_engine.get_data_spans()

get_points_for_plot

get_points_for_plot(
    project: bool = False, frame_index=0
) -> tuple[Points, Points, Points]

Delegate to PositionEngine.get_points_for_plot.

Parameters:

Name	Type	Description	Default
project	bool	True to project into a support frame (2-D mode).	False
frame_index		Index of the support frame for projection.	0

Returns:

Type	Description
tuple[Points, Points, Points]	Tuple of (spans, supports, insulators) as Points.

Source code in src/mechaphlowers/api/section_study.py

def get_points_for_plot(
    self, project: bool = False, frame_index=0
) -> tuple[Points, Points, Points]:
    """Delegate to [`PositionEngine.get_points_for_plot`][mechaphlowers.core.geometry.position_engine.PositionEngine.get_points_for_plot].

    Args:
        project: `True` to project into a support frame (2-D mode).
        frame_index: Index of the support frame for projection.

    Returns:
        Tuple of ``(spans, supports, insulators)`` as `Points`.
    """
    return self._position_engine.get_points_for_plot(project, frame_index)

get_spans_points

get_spans_points(
    frame: Literal[
        'section', 'localsection', 'cable'
    ] = 'section',
) -> ndarray

Delegate to PositionEngine.get_spans_points.

Parameters:

Name	Type	Description	Default
frame	Literal['section', 'localsection', 'cable']	Coordinate frame. Defaults to "section".	'section'

Returns:

Type	Description
ndarray	np.ndarray: Array of span points in the requested frame.

Source code in src/mechaphlowers/api/section_study.py

def get_spans_points(
    self, frame: Literal["section", "localsection", "cable"] = "section"
) -> np.ndarray:
    """Delegate to [`PositionEngine.get_spans_points`][mechaphlowers.core.geometry.position_engine.PositionEngine.get_spans_points].

    Args:
        frame (Literal["section", "localsection", "cable"]): Coordinate frame. Defaults to "section".

    Returns:
        np.ndarray: Array of span points in the requested frame.
    """
    return self._position_engine.get_spans_points(frame)

get_supports_points

get_supports_points() -> ndarray

Delegate to PositionEngine.get_supports_points.

Returns:

Type	Description
ndarray	np.ndarray: Array of support points coordinates.

Source code in src/mechaphlowers/api/section_study.py

def get_supports_points(self) -> np.ndarray:
    """Delegate to [`PositionEngine.get_supports_points`][mechaphlowers.core.geometry.position_engine.PositionEngine.get_supports_points].

    Returns:
        np.ndarray: Array of support points coordinates.
    """
    return self._position_engine.get_supports_points()

modify_cable

modify_cable(
    shift_support: dict[int, float] | None = None,
    shorten_span: dict[int, float] | None = None,
) -> None

Validate and store cable shifting values.

Delegates to [Manipulation.modify_cable][mechaphlowers.core.manipulation.Manipulation.modify_cable].

Parameters:

Name	Type	Description	Default
shift_support	dict[int, float] | None	Horizontal shifting per support, in meters. Dictionary mapping support index (0-based) to shift value; first and last supports are forced to 0.	None
shorten_span	dict[int, float] | None	Span length modification per span, in meters. Dictionary mapping span index (0-based) to shortening value; positive values shorten the span.	None

Source code in src/mechaphlowers/api/section_study.py

def modify_cable(
    self,
    shift_support: dict[int, float] | None = None,
    shorten_span: dict[int, float] | None = None,
) -> None:
    """Validate and store cable shifting values.

    Delegates to [`Manipulation.modify_cable`][mechaphlowers.core.manipulation.Manipulation.modify_cable].

    Args:
        shift_support (dict[int, float] | None): Horizontal shifting per support, in meters.
            Dictionary mapping support index (0-based) to shift value; first and last
            supports are forced to 0.
        shorten_span (dict[int, float] | None): Span length modification per span, in meters.
            Dictionary mapping span index (0-based) to shortening value; positive values
            shorten the span.
    """
    self._manipulation.modify_cable(shift_support, shorten_span)

modify_support

modify_support(
    manipulation: dict[int, dict[str, float]],
) -> None

Apply additive offsets to support geometry.

Delegates to [Manipulation.modify_support][mechaphlowers.core.manipulation.Manipulation.modify_support].

Parameters:

Name	Type	Description	Default
manipulation	dict[int, dict[str, float]]	Dictionary mapping support index (0-based) to offsets with optional keys "y" and "z".	required

Source code in src/mechaphlowers/api/section_study.py

def modify_support(
    self, manipulation: dict[int, dict[str, float]]
) -> None:
    """Apply additive offsets to support geometry.

    Delegates to
    [`Manipulation.modify_support`][mechaphlowers.core.manipulation.Manipulation.modify_support].

    Args:
        manipulation: Dictionary mapping support index (0-based) to
            offsets with optional keys ``"y"`` and ``"z"``.
    """
    self._manipulation.modify_support(manipulation)

reset_all

reset_all() -> None

Remove all active manipulations.

Delegates to [Manipulation.reset_all][mechaphlowers.core.manipulation.Manipulation.reset_all].

Source code in src/mechaphlowers/api/section_study.py

def reset_all(self) -> None:
    """Remove all active manipulations.

    Delegates to [`Manipulation.reset_all`][mechaphlowers.core.manipulation.Manipulation.reset_all].
    """
    self._manipulation.reset_all()

reset_cable

reset_cable() -> None

Remove cable shifting.

Delegates to [Manipulation.reset_cable][mechaphlowers.core.manipulation.Manipulation.reset_cable].

Source code in src/mechaphlowers/api/section_study.py

def reset_cable(self) -> None:
    """Remove cable shifting.

    Delegates to [`Manipulation.reset_cable`][mechaphlowers.core.manipulation.Manipulation.reset_cable].
    """
    self._manipulation.reset_cable()

reset_rope

reset_rope() -> None

Remove the rope overlay.

Delegates to [Manipulation.reset_rope][mechaphlowers.core.manipulation.Manipulation.reset_rope].

Source code in src/mechaphlowers/api/section_study.py

def reset_rope(self) -> None:
    """Remove the rope overlay.

    Delegates to [`Manipulation.reset_rope`][mechaphlowers.core.manipulation.Manipulation.reset_rope].
    """
    self._manipulation.reset_rope()

reset_support

reset_support() -> None

Remove the support manipulation overlay.

Delegates to [Manipulation.reset_support][mechaphlowers.core.manipulation.Manipulation.reset_support].

Source code in src/mechaphlowers/api/section_study.py

def reset_support(self) -> None:
    """Remove the support manipulation overlay.

    Delegates to [`Manipulation.reset_support`][mechaphlowers.core.manipulation.Manipulation.reset_support].
    """
    self._manipulation.reset_support()

reset_virtual_support

reset_virtual_support() -> None

Remove all virtual supports.

Delegates to [Manipulation.reset_virtual_support][mechaphlowers.core.manipulation.Manipulation.reset_virtual_support].

Source code in src/mechaphlowers/api/section_study.py

def reset_virtual_support(self) -> None:
    """Remove all virtual supports.

    Delegates to [`Manipulation.reset_virtual_support`][mechaphlowers.core.manipulation.Manipulation.reset_virtual_support].
    """
    self._manipulation.reset_virtual_support()

restore_state

restore_state(memento: BalanceEngineMemento) -> None

Restore state and notify observers to refresh geometry.

Parameters:

Name	Type	Description	Default
memento	BalanceEngineMemento	Snapshot previously returned by save_state.	required

Source code in src/mechaphlowers/api/section_study.py

def restore_state(self, memento: BalanceEngineMemento) -> None:
    """Restore state and notify observers to refresh geometry.

    Args:
        memento (BalanceEngineMemento): Snapshot previously returned by
            [`save_state`][mechaphlowers.api.section_study.SectionStudy.save_state].
    """
    self._caretaker.restore(memento)
    self._balance_engine.notify()

save_state

save_state() -> BalanceEngineMemento

Create an immutable snapshot of the current engine state.

Returns:

Name	Type	Description
BalanceEngineMemento	BalanceEngineMemento	Independent copy of every mutable array.

Source code in src/mechaphlowers/api/section_study.py

def save_state(self) -> BalanceEngineMemento:
    """Create an immutable snapshot of the current engine state.

    Returns:
        BalanceEngineMemento: Independent copy of every mutable array.
    """
    return self._caretaker.save()

set_loads

set_loads(
    load_position_distance: ndarray | list,
    load_mass: ndarray | list,
) -> None

Delegate to BalanceEngine.set_loads.

If either load_position_distance[i] or load_mass[i] is 0 or nan, it means there is no load at span i.

Parameters:

Name	Type	Description	Default
load_position_distance	ndarray | list	Position of the loads, in meters. Its size must be the number of spans.	required
load_mass	ndarray | list	Mass of the loads. Its size must be the number of spans.	required

Raises:

Type	Description
ValueError	if at least one load_position_distance is not in [0, span_length] or if the arguments don't have the right lengths.

Source code in src/mechaphlowers/api/section_study.py

def set_loads(
    self,
    load_position_distance: np.ndarray | list,
    load_mass: np.ndarray | list,
) -> None:
    """Delegate to [`BalanceEngine.set_loads`][mechaphlowers.core.models.balance.engine.BalanceEngine.set_loads].

    If either load_position_distance[i] or load_mass[i] is 0 or nan, it means there is no load at span i.

    Args:
        load_position_distance (np.ndarray | list): Position of the loads, in meters. Its size must be the number of spans.
        load_mass (np.ndarray | list): Mass of the loads. Its size must be the number of spans.

    Raises:
        ValueError: if at least one load_position_distance is not in [0, span_length]
            or if the arguments don't have the right lengths.
    """
    self._balance_engine.set_loads(load_position_distance, load_mass)
    self._solve_intermediate()

solve_adjustment

solve_adjustment() -> None

Run adjustment on clean geometry, then apply manipulations if any.

1. Build a clean engine from the original section array and solve adjustment to obtain initial_L_ref.
2. If manipulations are registered, call [Manipulation.from_section_array][mechaphlowers.core.manipulation.Manipulation.from_section_array] to produce a manipulated copy, then [Manipulation.initialize_engine][mechaphlowers.core.manipulation.Manipulation.initialize_engine] to build the target engine with injected L_ref and blocked adjustment.
3. Rewire downstream engines (caretaker, position, plot, guying).

On SolverError, the engine state is restored to the snapshot taken before the solve attempt, and the error is re-raised.

Raises:

Type	Description
SolverError	If the solver fails to converge.

Source code in src/mechaphlowers/api/section_study.py

def solve_adjustment(self) -> None:
    """Run adjustment on clean geometry, then apply manipulations if any.

    1. Build a clean engine from the original section array and solve
       adjustment to obtain ``initial_L_ref``.
    2. If manipulations are registered, call
       [`Manipulation.from_section_array`][mechaphlowers.core.manipulation.Manipulation.from_section_array] to produce a manipulated
       copy, then [`Manipulation.initialize_engine`][mechaphlowers.core.manipulation.Manipulation.initialize_engine] to build the
       target engine with injected ``L_ref`` and blocked adjustment.
    3. Rewire downstream engines (caretaker, position, plot, guying).

    On [`SolverError`][mechaphlowers.entities.errors.SolverError], the engine
    state is restored to the snapshot taken before the solve attempt, and the
    error is re-raised.

    Raises:
        SolverError: If the solver fails to converge.
    """
    if self._manipulation.has_manipulations:
        # Phase 1: solve on clean geometry
        clean_engine = BalanceEngine(
            cable_array=self._cable_array,
            section_array=self._section_array,
            span_model_type=self._span_model_type,
            deformation_model_type=self._deformation_model_type,
        )

        try:
            clean_engine.solve_adjustment()
        except SolverError as e:
            logger.error(
                "Error during solve_adjustment. No changes on the engine state"
            )
            raise e

        initial_L_ref = clean_engine.initial_L_ref.copy()

        # Phase 2: build manipulated SA and target engine
        manipulated_sa = self._manipulation.from_section_array(
            self._section_array
        )
        self._balance_engine = self._manipulation.initialize_engine(
            clean_engine, manipulated_sa, initial_L_ref
        )

        # Rewire downstream engines
        self._caretaker = BalanceEngineCaretaker(self._balance_engine)
        self._position_engine = PositionEngine(self._balance_engine)
        self._plot_engine = None
        self._guying = None
    else:
        memento = self._caretaker.save()
        if self._intermediate_memento is not None:
            # case where change_state already occurred: resetting climate state
            self._caretaker.restore(self._intermediate_memento)
        # if not: new case where no change_state was already run
        try:
            self._balance_engine.solve_adjustment()
        except SolverError as e:
            logger.error(
                "Error during solve_adjustment, rolling back state."
            )
            self._caretaker.restore(memento)
            raise e

solve_change_state

solve_change_state(
    wind_pressure: ndarray | float | None = None,
    ice_thickness: ndarray | float | None = None,
    new_temperature: ndarray | float | None = None,
    wind_direction: Literal[
        'clockwise', 'anticlockwise'
    ] = 'anticlockwise',
) -> None

Run BalanceEngine.solve_change_state with automatic rollback.

An intermediate solve at default conditions (T=15 °C, wind=0, ice=0) is performed first as a warm-start to improve convergence, unless the requested conditions already match the defaults.

On SolverError, the engine state is restored to the snapshot taken before the solve attempt, and the error is re-raised.

Parameters:

Name	Type	Description	Default
wind_pressure	ndarray | float | None	Wind pressure in Pa. Defaults to None.	None
ice_thickness	ndarray | float | None	Ice thickness in m. Defaults to None.	None
new_temperature	ndarray | float | None	New temperature in °C. Defaults to None.	None
wind_direction	Literal['clockwise', 'anticlockwise']	Direction of the wind. Defaults to "anticlockwise".	'anticlockwise'

Raises:

Type	Description
SolverError	If the solver fails to converge.

Source code in src/mechaphlowers/api/section_study.py

def solve_change_state(
    self,
    wind_pressure: np.ndarray | float | None = None,
    ice_thickness: np.ndarray | float | None = None,
    new_temperature: np.ndarray | float | None = None,
    wind_direction: Literal[
        "clockwise", "anticlockwise"
    ] = "anticlockwise",
) -> None:
    """Run [`BalanceEngine.solve_change_state`][mechaphlowers.core.models.balance.engine.BalanceEngine.solve_change_state] with automatic rollback.

    An intermediate solve at default conditions (T=15 °C, wind=0, ice=0)
    is performed first as a warm-start to improve convergence, unless the
    requested conditions already match the defaults.

    On [`SolverError`][mechaphlowers.entities.errors.SolverError], the engine
    state is restored to the snapshot taken before the solve attempt, and the
    error is re-raised.

    Args:
        wind_pressure (np.ndarray | float | None): Wind pressure in Pa. Defaults to None.
        ice_thickness (np.ndarray | float | None): Ice thickness in m. Defaults to None.
        new_temperature (np.ndarray | float | None): New temperature in °C. Defaults to None.
        wind_direction (Literal["clockwise", "anticlockwise"]): Direction of the wind. Defaults to "anticlockwise".

    Raises:
        SolverError: If the solver fails to converge.
    """
    engine = self._balance_engine
    default = engine.default_value

    span_shape = engine.section_array.data.span_length.shape

    def _to_array(val: np.ndarray | float | None, name: str) -> np.ndarray:
        if val is None:
            return np.full(span_shape, default[name])
        if isinstance(val, (int, float)):
            return np.full(span_shape, val)
        if isinstance(val, np.ndarray) and val.shape != span_shape:
            raise ValueError(
                f"{name}: expected array of shape {span_shape}, got {val.shape}"
            )
        return val

    target_wind = _to_array(wind_pressure, "wind_pressure")
    target_ice = _to_array(ice_thickness, "ice_thickness")
    target_temp = _to_array(new_temperature, "new_temperature")

    is_default = (
        np.allclose(target_wind, default["wind_pressure"])
        and np.allclose(target_ice, default["ice_thickness"])
        and np.allclose(target_temp, default["new_temperature"])
    )

    memento = self._caretaker.save()
    try:
        if is_default:
            self._solve_intermediate()
        else:
            self._get_intermediate_state()

            engine.solve_change_state(
                wind_pressure=wind_pressure,
                ice_thickness=ice_thickness,
                new_temperature=new_temperature,
                wind_direction=wind_direction,
            )
    except SolverError as e:
        logger.error(
            "Error during solve_change_state, rolling back state."
        )
        self._caretaker.restore(memento)
        raise e

supports_number

supports_number() -> int

Return the number of supports in the balance engine.

Source code in src/mechaphlowers/api/section_study.py

def supports_number(self) -> int:
    """Return the number of supports in the balance engine."""
    return self._balance_engine.support_number