diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index f153aa3..1e4968a 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -18,7 +18,7 @@ repos: - repo: https://github.com/astral-sh/ruff-pre-commit # Ruff version. - rev: v0.15.0 + rev: v0.15.1 hooks: # Run the linter. - id: ruff diff --git a/docs/api_reference/architecture.md b/docs/api_reference/architecture.md index 09e94ba..0e386b7 100644 --- a/docs/api_reference/architecture.md +++ b/docs/api_reference/architecture.md @@ -6,137 +6,144 @@ SPDX-License-Identifier: MPL-2.0 # The architecture of Transformer Thermal Model -> **⚠️ Warning:** -> This overview is partly outdated and will be updated soon. + +## Container diagram ```mermaid -stateDiagram-v2 - direction TB - - - %% Define states with descriptions - DataCollection: Data Collection - Validation: Input Validation - TransformerConfig: Transformer Configuration - HotSpotCalib: Hot Spot Calibration - ThermalModel: Thermal Model Engine - TempCalculation: Temperature Calculation - AgingAnalysis: Aging Analysis - Results: Output Results - - %% Legend for state descriptions - state Legend{ - direction LR - LegendInputState: Input State - LegendProcessState: Process State - LegendOptionalState: Optional State - LegendOutputState: Output State - } +C4Container + title C2: Containers of the Transformer Thermal Model + + Person_Ext(scientist, "Scientist", "Someone that reports on or analyses thermals of transformers.") + System_Ext(cyclops, "Cyclic Optimiser", "Finds a thermal limit of a transformer by repeatedly calculating
the thermals and scaling a load profile.") + - %% Composite state for input data sources - state DataCollection { - direction LR - state InputData{ - direction LR - DateTimeIndex: Date and Time Index - LoadProfile: Load Profile Data - AmbientTemp: Ambient Temperature Data - - InputProfile: InputProfile - - DateTimeIndex --> InputProfile - LoadProfile --> InputProfile - AmbientTemp --> InputProfile - } - InitialTemperatures: Initial temperatures (optional) - InitialTemperatures: - Initial top oil temperature - state CoolerConfiguration { - direction LR - CoolerTypePT: CoolerType ONAN or ONAF - CoolerTypeDT: CoolerType not needed + Boundary(b0, "Transformer Thermal Model") { - [*] --> CoolerTypePT: PowerTransformer - [*] --> CoolerTypeDT: DistributionTransformer + Boundary(b1, "Extra features") { + Container(docs, "Docs", "HTML module", "Module with markdown files linking to existing code and extra added context around it.") + Container(toolbox, "Toolbox", "Python module", "Provides extra utility functions that are not necessary to run the model,
but can be handy for a large group of our users.") + Container(aging, "Aging", "Python module", "Determine the aging rate profile for a specific type of insulated paper
for a given hot spot profile.") } - - state TransformerSpecs { - direction LR - MandatorySpecs: Mandatory Specifications - OptionalSpecs: Optional Specifications - TransformerSpecifications: UserTransformerSpecifications - - MandatorySpecs: - load_loss (W) - MandatorySpecs: - nom_load_sec_side (A) - MandatorySpecs: - no_load_loss (W) - MandatorySpecs: - amb_temp_surcharge (K) - - OptionalSpecs: - top_oil_temp_rise (K) - OptionalSpecs: - winding_oil_gradient (K) - OptionalSpecs: - hot_spot_fac (-) - OptionalSpecs: - time_const_oil, time_const_windings - OptionalSpecs: - ... (other optional specs) - - MandatorySpecs --> TransformerSpecifications - OptionalSpecs --> TransformerSpecifications + Boundary(b2, "Core Container"){ + System(thermal_modeling, "Thermal Modeling", "Calculate thermals of a transformer.") } - [*] --> InputData - [*] --> TransformerSpecs - [*] --> CoolerConfiguration - [*] --> InitialTemperatures + Boundary(b3, "Imported packages"){ + System_Ext(numpy, "Numpy", "The fundamental package for scientific computing with Python") + } } + + Rel(scientist, toolbox, "Easily transforms pandas input into TTM-valid input with") + Rel(scientist, aging, "Estimates the aging of a transformer using") + Rel(scientist, docs, "Understands the workings of TTM via the") + Rel(scientist, thermal_modeling, "Calculates thermal values of a transformer using") + + Rel(cyclops, thermal_modeling, "Calculates thermal transformer limits using") + + Rel(thermal_modeling, toolbox, "Provides input schemas for") + Rel(thermal_modeling, aging, "Provides possible insulator types for") + + Rel(aging, numpy, "Represents, organizes and structures data with") + Rel(thermal_modeling, numpy, "Represents, organizes and structures data with") - %% Composite state for results - state Results { - TopOilTemp: Top Oil Temperature - HotSpotTemp: Hot Spot Temperature - AgingResults: Aging Assessment - - OutputProfile: OutputProfile - AgingOutput: pd.Series - - TopOilTemp --> OutputProfile - HotSpotTemp --> OutputProfile - AgingResults --> AgingOutput + UpdateLayoutConfig($c4BoundaryInRow="2", $c4ShapeInRow="2") +``` + +## Component diagrams + +### Thermal Modeling + +```mermaid +C4Component + title C3: Thermal Modeling + + Person_Ext(scientist, "Scientist", "Someone that reports on or analyses thermals of transformers.") + System_Ext(cyclops, "Cyclic Optimiser", "Finds a thermal limit of a transformer by repeatedly calculating
the thermals and scaling a load profile.") + + Boundary(b0, "Transformer Thermal Model"){ + System_Boundary(s0, "Thermal Modeling"){ + Container(hs_calibration, "Hot-spot calibration", "Python module", "Calibrates hot spot factor as a replacement
if this value is unknown to the user.") + Container(model, "Model", "Python module", "Calculate transformer temperatures under specified load
and ambient temperature profiles.") + Container(transformer, "Transformer", "Python module", "Data class (containing logic) with specifications and calculated properties
of a transformer. Can build a PowerTransformer, DistributionTransformer
and ThreeWindingTransformer.") + } + + System_Boundary(s1, "Imported packages"){ + System_Ext(numpy, "Numpy", "The fundamental package for scientific computing with Python") + } } - - %% Main flow - DataCollection - DataCollection --> Validation: Validate inputs - Validation --> ThermalModel: create Model() with InputProfile, Transformer and optional initial temperatures - Validation --> TransformerConfig: Create Transformer() with specs and cooler type - TransformerConfig --> HotSpotCalib: Calibrate hot spot factor if needed (only for PowerTransformers) - TransformerConfig --> ThermalModel: skip if factor known - HotSpotCalib --> ThermalModel: Initialize model - ThermalModel --> TempCalculation: Calculate temperatures - TempCalculation --> AgingAnalysis: Analyze aging (using the modeled hot spot profile) - TempCalculation --> Results: Generate outputs - AgingAnalysis --> Results: Add aging data - Results --> [*] + Rel(scientist, transformer, "Provides asset specifications to build a") + Rel(scientist, hs_calibration, "Calibrates hot-spot factor (when unknown) with") + Rel(cyclops, model, "Finds thermal limits of Transformer using") + Rel(scientist, model, "Finds thermal values of a Transformer using") + Rel(model, transformer, "Simulates thermal values of the provided") - - %% Notes for clarity - note right of Validation - Uses Pydantic schemas to validate - load profiles, ambient temperature, - and transformer specifications - end note - - note left of TempCalculation - Implements IEC 60076-7 standard - for thermal modeling calculations - end note - - %% Styling - classDef inputState fill:#d9e7e0,stroke:#267950,stroke-width:3px - classDef processState fill:#fbe9d9,stroke:#ea8426 - classDef optionalState fill:#f3dddd,stroke:#bb3b40,font-style:italic,stroke-dasharray: 5 5 - classDef outputState fill:#ecddec,stroke:#954091,stroke-width:3px - - class LegendInputState,Validation,InputProfile,TransformerSpecifications,CoolerTypePT,CoolerTypeDT inputState - class LegendProcessState,TransformerConfig,ThermalModel,TempCalculation processState - class LegendOutputState,OutputProfile,AgingOutput outputState - class LegendOptionalState,HotSpotCalib,AgingAnalysis optionalState + Rel(model, numpy, "Represents data with") + Rel(transformer, numpy, "Represents data with") + Rel(hs_calibration, numpy, "Represents data with") + + UpdateLayoutConfig($c4BoundaryInRow="3", $c4ShapeInRow="1") ``` + +### Toolbox components + +```mermaid +C4Component + title C3: Toolbox Components + + Person_Ext(scientist, "Scientist", "Someone that reports on or analyses thermals of transformers.") + Boundary(b0, "Transformer Thermal Model"){ + + System_Boundary(b1, "Toolbox"){ + System(toolbox, "Toolbox", "Provides extra utility functions that are not necessary to run the model,
but can be handy for a large group of our users.") + System_Ext(pandas, "Pandas", "A fast, powerful, flexible and easy to use open source data analysis
and manipulation tool, built on top of the Python programming language.") + Rel(toolbox, pandas, "Formats pandas DataFrames to numpy with") + } + System(thermal_model, "Thermal Modeling") + } + + Rel(scientist, toolbox, "Translates their pandas DataFrames to TTM inputs using") + Rel(toolbox, thermal_model, "Reads methods for generating user input from") + + UpdateLayoutConfig($c4BoundaryInRow="2", $c4ShapeInRow="1") +``` + +### Docs + +```mermaid +C4Component + title C3: Docs Components + + Person_Ext(scientist, "Scientist", "Someone that reports on or analyses thermals of transformers.") + Boundary(ttm, "Transformer Thermal Model"){ + Boundary(b0, "Extra features") { + Container_Boundary(b01, "other features"){ + System(other_features, "Other features", "The other extra features, e.g. the Toolbox and Aging.") + } + Container_Boundary(b02, "Docs"){ + System(docs, "Docs", "HTML files building the documentation page") + System_Ext(mkdocs, "MkDocs", "MkDocs is a fast, simple and downright gorgeous static site generator that's geared towards building project documentation.") + Person(developer, "Developer", "Someone that contributes to the TTM.") + Rel(developer, mkdocs, "Builds the documentation by running") + } + } + + Boundary(b1, "Core Container"){ + System(thermal_modeling, "Thermal Modeling", "Calculate thermals of a transformer.") + } + + } + + Rel(scientist, docs, "Understands the inner workings of the TTM via") + + Rel(mkdocs, thermal_modeling, "Retrieves documentation from") + Rel(mkdocs, other_features, "Retrieves documentation from") + Rel(docs, mkdocs, "Builds the HTML files with") + + UpdateLayoutConfig($c4BoundaryInRow="1", $c4ShapeInRow="3") + + +``` + + \ No newline at end of file