documentation update

docs/index.md

@@ -16,9 +16,15 @@ pip install grid-data-models
 In an effort to reduce code duplication and provide client packages a standard interface to interact with power system data, a group of research engineers at NREL is working on developing standard data models. Features:
 
 - **Built-in validation layer:** Use of [pydantic](https://docs.pydantic.dev/latest/) allows us to validate model fields.
+- **Connectivity Validation**: Ensures logical consistency in grid design, e.g.:
+  - Three-phase equipment cannot connect to single-phase buses.
+  - Transformer low-voltage sides cannot connect to high-voltage buses.
 - **Time series data management:** GDM uses [infrasys](https://github.nrel.gov/CADET/infrastructure_systems) package which enables [efficient time series data management](https://nrel.github.io/infrasys/explanation/time_series.html) by sharing arrays across components and offloading system memory. For example, we can attach time series power consumption data to a load profile.
 - **Built-in unit conversion:** GDM leverages [pint](https://pint.readthedocs.io/en/stable/) for unit conversion for power system quantities. For e.g power, voltage, time etc.
 - **JSON serialization/deserialization:** GDM uses [infrasys](https://github.nrel.gov/CADET/infrastructure_systems) to serialize and deserialize distribution system components to/from JSON.
+- **Temporal Modeling**: Supports temporal changes within a distribution model, enabling dynamic analyses over time.
+- **Graph-Based Analysis**: Exposes a connectivity graph using **NetworkX**, allowing advanced graph-based algorithms and visualizations.
+- **Interoperability**: Easily integrates with existing tools.
 
 ## How to get started ?
 

docs/temoral_models/temporal_intro.md

@@ -0,0 +1,33 @@
+## Temporal models in `grid-data-models`
+
+The `grid-data-models` (GDM) package includes comprehensive support for modeling temporal changes within a distribution system. This functionality allows users to effectively manage time-dependent modifications to a base grid model, enabling dynamic analysis and scenario planning.
+
+### Key Concepts
+
+1. **Time-Stamped Modifications**:  
+   The system enables edits, additions, and deletions to a base GDM model at specific timestamps. Each modification is tracked and stored, ensuring a clear history of changes over time.
+
+2. **Scenario-Based Temporal Modeling**:  
+   Users can define multiple temporal scenarios linked to the same base model. This feature allows for maintaining and analyzing various operational or planning conditions within a single system, avoiding duplication of base models.
+
+3. **Efficient Retrieval**:  
+   With exposed utility functions, users can easily retrieve an updated GDM model for any given timestamp. The retrieved model reflects all modifications up to the specified time, providing a complete and consistent view of the system.
+
+### Implementation Features
+- **Base Model Integrity**:  
+  All temporal changes are built upon a single base GDM model, ensuring a consistent foundation for analysis.
+
+- **Scenario Management**:  
+  Temporal changes can be grouped into scenarios, enabling users to manage different operational cases independently while sharing a common base model.
+
+- **Utility Functions**:  
+  - `get_model_at_time(timestamp)`: Returns the GDM model updated to include all changes up to the specified `timestamp`.
+  - `apply_scenario(scenario_id)`: Applies all temporal modifications related to a specific scenario to the base model.
+  - `list_scenarios()`: Lists all defined scenarios for the base model.
+
+### Example Usage
+```python
+
+```
+
+This capability allows users to seamlessly integrate time-dependent changes into their workflows, making `grid-data-models` a powerful tool for both operational and planning purposes in distribution system analysis.