iec_60287_parameter_extractor

IEC60287CableParameters dataclass

IEC60287CableParameters(
    ampacity: float,
    conductor_temperature: float,
    screen_temperature: float,
    armour_temperature: float | None,
    surface_temperature: float,
    dc_resistance_conductor_at_20: float,
    skin_effect_factor: float,
    proximity_effect_factor: float,
    ac_resistance_conductor: float,
    dc_resistance_screen: float,
    t1: float,
    t2: float,
    t3: float,
    t4: float,
    conductor_loss: float,
    dielectric_loss: float,
    screen_loss: float,
    armour_loss: float,
    total_loss: float,
    screen_loss_factor: float,
    armour_loss_factor: float,
)

Reference IEC 60287 parameters for a single cable validation case.

from_dict classmethod

from_dict(d: dict)

Create an IEC60287CableParameters instance from a dictionary, ensuring all required keys are present.

Source code in cable_thermal_model/validation/iec_60287_parameter_extractor.py

@classmethod
def from_dict(cls, d: dict):
    """Create an IEC60287CableParameters instance from a dictionary, ensuring all required keys are present."""
    return cls(**d)

build_scenario

build_scenario(
    circuit_ratings: dict[str, float],
    soil_thermal_resistivity: float,
    soil_thermal_capacity: float,
    ambient_temperature: float,
) -> DataFrame[ScenarioSchemaSoil]

Build a static scenario DataFrame used for IEC parameter extraction.

Parameters:

Name	Type	Description	Default
circuit_ratings	dict[str, float]	Mapping of circuit names to their load ratings (A).	required
soil_thermal_resistivity	float	Thermal resistivity of the surrounding soil (K*m/W).	required
soil_thermal_capacity	float	Volumetric heat capacity of the soil (J/(m^3*K)).	required
ambient_temperature	float	Ambient temperature of the soil (C).	required

Returns:

Type	Description
DataFrame[ScenarioSchemaSoil]	A DataFrame with columns for ambient temperature, soil properties, and load.

Source code in cable_thermal_model/validation/iec_60287_parameter_extractor.py

def build_scenario(
    circuit_ratings: dict[str, float],
    soil_thermal_resistivity: float,
    soil_thermal_capacity: float,
    ambient_temperature: float,
) -> DataFrame[ScenarioSchemaSoil]:
    """Build a static scenario DataFrame used for IEC parameter extraction.

    Args:
        circuit_ratings: Mapping of circuit names to their load ratings (A).
        soil_thermal_resistivity: Thermal resistivity of the surrounding soil (K*m/W).
        soil_thermal_capacity: Volumetric heat capacity of the soil (J/(m^3*K)).
        ambient_temperature: Ambient temperature of the soil (C).

    Returns:
        A DataFrame with columns for ambient temperature, soil properties, and load.

    """
    scenario = pd.DataFrame(
        data={
            "ambient_temperature": ambient_temperature,
            "soil_thermal_resistivity": soil_thermal_resistivity,
            "soil_thermal_capacity": soil_thermal_capacity,
        },
        index=pd.timedelta_range(start="0D", end="30000D", periods=20),
    )

    for circuit_name, rating in circuit_ratings.items():
        scenario[f"load_{circuit_name}"] = rating

    return ScenarioSchemaSoil.validate(scenario)

extract_iec_60287_parameters

extract_iec_60287_parameters(
    static_env: StaticEnvSoil,
    circuit_ratings: dict[str, float],
    soil_thermal_resistivity: float,
    soil_thermal_capacity: float,
    ambient_temperature: float,
) -> DataFrame

Compute IEC validation parameters and return a compact DataFrame.

Parameters:

Name	Type	Description	Default
static_env	StaticEnvSoil	The static environment to solve.	required
circuit_ratings	dict[str, float]	Mapping of circuit names to their load ratings (A).	required
soil_thermal_resistivity	float	Thermal resistivity of the surrounding soil (K*m/W).	required
soil_thermal_capacity	float	Volumetric heat capacity of the soil (J/(m^3*K)).	required
ambient_temperature	float	Ambient temperature of the soil (°C).	required

Returns:

Type	Description
DataFrame	A DataFrame with the relevant IEC parameters for all cables in static_env.

Source code in cable_thermal_model/validation/iec_60287_parameter_extractor.py

def extract_iec_60287_parameters(
    static_env: StaticEnvSoil,
    circuit_ratings: dict[str, float],
    soil_thermal_resistivity: float,
    soil_thermal_capacity: float,
    ambient_temperature: float,
) -> pd.DataFrame:
    """Compute IEC validation parameters and return a compact DataFrame.

    Args:
        static_env: The static environment to solve.
        circuit_ratings: Mapping of circuit names to their load ratings (A).
        soil_thermal_resistivity: Thermal resistivity of the surrounding soil (K*m/W).
        soil_thermal_capacity: Volumetric heat capacity of the soil (J/(m^3*K)).
        ambient_temperature: Ambient temperature of the soil (°C).

    Returns:
        A DataFrame with the relevant IEC parameters for all cables in static_env.

    """
    scenario = build_scenario(
        circuit_ratings=circuit_ratings,
        soil_thermal_resistivity=soil_thermal_resistivity,
        soil_thermal_capacity=soil_thermal_capacity,
        ambient_temperature=ambient_temperature,
    )

    model = ModelFactory.create_model(static_env, scenario)
    model_output = model.run()

    parameters = pd.DataFrame()
    for cable_key, pos_cable in model.cables.items():
        context = _get_cable_context(
            cable=pos_cable.cable,
            cable_key=cable_key,
            scenario=scenario,
            model_output=model_output,
        )

        results = _extract_parameters_for_cable(context)
        parameters = pd.concat([parameters, results], axis=1)

    return parameters

compare_parameters_to_reference

compare_parameters_to_reference(
    extracted_parameters: Series,
    reference_parameters: IEC60287CableParameters,
) -> DataFrame

Compare extracted parameters to reference values and compute differences.

Parameters:

Name	Type	Description	Default
extracted_parameters	Series	A Series containing the extracted parameters for a cable.	required
reference_parameters	IEC60287CableParameters	An IEC60287CableParameters object with reference values.	required

Returns:

Type	Description
DataFrame	A DataFrame comparing extracted and reference parameters, including differences.

Source code in cable_thermal_model/validation/iec_60287_parameter_extractor.py

def compare_parameters_to_reference(
    extracted_parameters: pd.Series,
    reference_parameters: IEC60287CableParameters,
) -> pd.DataFrame:
    """Compare extracted parameters to reference values and compute differences.

    Args:
        extracted_parameters: A Series containing the extracted parameters for a cable.
        reference_parameters: An IEC60287CableParameters object with reference values.

    Returns:
        A DataFrame comparing extracted and reference parameters, including differences.

    """
    reference_series = pd.Series(asdict(reference_parameters))

    comparison = pd.DataFrame({"Extracted": extracted_parameters, "Reference": reference_series})
    comparison["Diff"] = comparison["Extracted"] - comparison["Reference"]
    comparison["Rel Diff (%)"] = round(comparison["Diff"] / comparison["Reference"].replace(0, np.nan) * 100, 2)
    comparison.insert(0, "Unit", pd.Series(IEC60287CableParameters.units))

    return comparison