Skip to content

Commit 834f44a

Browse files
authored
Reogranize Docs (#377)
1 parent ec11000 commit 834f44a

32 files changed

Lines changed: 2504 additions & 448 deletions

CHANGELOG.md

Lines changed: 80 additions & 57 deletions
Original file line numberDiff line numberDiff line change
@@ -46,90 +46,113 @@ This release introduces new model dimensions (periods and scenarios) for multi-p
4646
### ✨ Added
4747
4848
**New model dimensions:**
49-
* **Period dimension**: Enables multi-period investment modeling with distinct decisions in each period for transformation pathway optimization
50-
* **Scenario dimension**: Supports stochastic modeling with weighted scenarios for robust decision-making under uncertainty (demand, prices, weather)
49+
50+
- **Period dimension**: Enables multi-period investment modeling with distinct decisions in each period for transformation pathway optimization
51+
- **Scenario dimension**: Supports stochastic modeling with weighted scenarios for robust decision-making under uncertainty (demand, prices, weather)
5152
5253
**Redesigned effect sharing system:**
54+
5355
Effects now use intuitive `share_from_*` syntax that clearly shows contribution sources:
56+
5457
```python
5558
costs = fx.Effect('costs', '€', 'Total costs',
5659
share_from_temporal={'CO2': 0.2}, # From temporal effects
5760
share_from_periodic={'land': 100}) # From periodic effects
5861
```
62+
5963
This replaces `specific_share_to_other_effects_*` parameters and inverts the direction for clearer relationships.
6064
6165
**Enhanced I/O and data handling:**
62-
* NetCDF/JSON serialization for all Interface objects and FlowSystem with round-trip support
63-
* FlowSystem manipulation: `sel()`, `isel()`, `resample()`, `copy()`, `__eq__()` methods
64-
* Direct access to FlowSystem from results without manual restoring (lazily loaded)
65-
* New `FlowResults` class and precomputed DataArrays for sizes/flow_rates/flow_hours
66-
* `effects_per_component()` dataset for component impact evaluation, including all indirect effects through effect shares
66+
67+
- NetCDF/JSON serialization for all Interface objects and FlowSystem with round-trip support
68+
- FlowSystem manipulation: `sel()`, `isel()`, `resample()`, `copy()`, `__eq__()` methods
69+
- Direct access to FlowSystem from results without manual restoring (lazily loaded)
70+
- New `FlowResults` class and precomputed DataArrays for sizes/flow_rates/flow_hours
71+
- `effects_per_component()` dataset for component impact evaluation, including all indirect effects through effect shares
6772
6873
**Other additions:**
69-
* Balanced storage - charging and discharging sizes can be forced equal via `balanced` parameter
70-
* New Storage parameters: `relative_minimum_final_charge_state` and `relative_maximum_final_charge_state` for final state control
71-
* Improved filter methods in results
72-
* Example for 2-stage investment decisions leveraging FlowSystem resampling
74+
75+
- Balanced storage - charging and discharging sizes can be forced equal via `balanced` parameter
76+
- New Storage parameters: `relative_minimum_final_charge_state` and `relative_maximum_final_charge_state` for final state control
77+
- Improved filter methods in results
78+
- Example for 2-stage investment decisions leveraging FlowSystem resampling
7379
7480
### 💥 Breaking Changes
75-
* `relative_minimum_charge_state` and `relative_maximum_charge_state` don't have an extra timestep anymore.
76-
* Renamed class `SystemModel` to `FlowSystemModel`
77-
* Renamed class `Model` to `Submodel`
78-
* Renamed `mode` parameter in plotting methods to `style`
79-
* `Calculation.do_modeling()` now returns the `Calculation` object instead of its `linopy.Model`. Callers that previously accessed the linopy model directly should now use `calculation.do_modeling().model` instead of `calculation.do_modeling()`.
81+
82+
- `relative_minimum_charge_state` and `relative_maximum_charge_state` don't have an extra timestep anymore.
83+
- Renamed class `SystemModel` to `FlowSystemModel`
84+
- Renamed class `Model` to `Submodel`
85+
- Renamed `mode` parameter in plotting methods to `style`
86+
- `Calculation.do_modeling()` now returns the `Calculation` object instead of its `linopy.Model`. Callers that previously accessed the linopy model directly should now use `calculation.do_modeling().model` instead of `calculation.do_modeling()`.
8087
8188
### ♻️ Changed
82-
* FlowSystems cannot be shared across multiple Calculations anymore. A copy of the FlowSystem is created instead, making every Calculation independent
83-
* Each Subcalculation in `SegmentedCalculation` now has its own distinct `FlowSystem` object
84-
* Type system overhaul - added clear separation between temporal and non-temporal data throughout codebase for better clarity
85-
* Enhanced FlowSystem interface with improved `__repr__()` and `__str__()` methods
86-
* Improved Model Structure - Views and organisation is now divided into:
87-
* Model: The main Model (linopy.Model) that is used to create and store the variables and constraints for the flow_system.
88-
* Submodel: The base class for all submodels. Each is a subset of the Model, for simpler access and clearer code.
89+
90+
- FlowSystems cannot be shared across multiple Calculations anymore. A copy of the FlowSystem is created instead, making every Calculation independent
91+
- Each Subcalculation in `SegmentedCalculation` now has its own distinct `FlowSystem` object
92+
- Type system overhaul - added clear separation between temporal and non-temporal data throughout codebase for better clarity
93+
- Enhanced FlowSystem interface with improved `__repr__()` and `__str__()` methods
94+
- Improved Model Structure - Views and organisation is now divided into:
95+
- Model: The main Model (linopy.Model) that is used to create and store the variables and constraints for the flow_system.
96+
- Submodel: The base class for all submodels. Each is a subset of the Model, for simpler access and clearer code.
8997
9098
### 🗑️ Deprecated
91-
* The `agg_group` and `agg_weight` parameters of `TimeSeriesData` are deprecated and will be removed in a future version. Use `aggregation_group` and `aggregation_weight` instead.
92-
* The `active_timesteps` parameter of `Calculation` is deprecated and will be removed in a future version. Use the new `sel(time=...)` method on the FlowSystem instead.
93-
* The assignment of Bus Objects to Flow.bus is deprecated and will be removed in a future version. Use the label of the Bus instead.
94-
* The usage of Effects objects in Dicts to assign shares to Effects is deprecated and will be removed in a future version. Use the label of the Effect instead.
95-
* Effect parameters renamed:
96-
- `minimum_investment` → `minimum_periodic`
97-
- `maximum_investment` → `maximum_periodic`
98-
- `minimum_operation` → `minimum_temporal`
99-
- `maximum_operation` → `maximum_temporal`
100-
- `minimum_operation_per_hour` → `minimum_per_hour`
101-
- `maximum_operation_per_hour` → `maximum_per_hour`
99+
100+
- The `agg_group` and `agg_weight` parameters of `TimeSeriesData` are deprecated and will be removed in a future version. Use `aggregation_group` and `aggregation_weight` instead.
101+
- The `active_timesteps` parameter of `Calculation` is deprecated and will be removed in a future version. Use the new `sel(time=...)` method on the FlowSystem instead.
102+
- The assignment of Bus Objects to Flow.bus is deprecated and will be removed in a future version. Use the label of the Bus instead.
103+
- The usage of Effects objects in Dicts to assign shares to Effects is deprecated and will be removed in a future version. Use the label of the Effect instead.
104+
- Effect parameters renamed:
105+
- `minimum_investment` → `minimum_periodic`
106+
- `maximum_investment` → `maximum_periodic`
107+
- `minimum_operation` → `minimum_temporal`
108+
- `maximum_operation` → `maximum_temporal`
109+
- `minimum_operation_per_hour` → `minimum_per_hour`
110+
- `maximum_operation_per_hour` → `maximum_per_hour`
102111
103112
### 🔥 Removed
104-
* **Effect share parameters**: The old `specific_share_to_other_effects_*` parameters were replaced WITHOUT DEPRECATION
105-
- `specific_share_to_other_effects_operation` → `share_from_temporal` (with inverted direction)
106-
- `specific_share_to_other_effects_invest` → `share_from_periodic` (with inverted direction)
113+
114+
- **Effect share parameters**: The old `specific_share_to_other_effects_*` parameters were replaced WITHOUT DEPRECATION
115+
- `specific_share_to_other_effects_operation` → `share_from_temporal` (with inverted direction)
116+
- `specific_share_to_other_effects_invest` → `share_from_periodic` (with inverted direction)
107117
108118
### 🐛 Fixed
109-
* Enhanced NetCDF I/O with proper attribute preservation for DataArrays
110-
* Improved error handling and validation in serialization processes
111-
* Better type consistency across all framework components
119+
120+
- Enhanced NetCDF I/O with proper attribute preservation for DataArrays
121+
- Improved error handling and validation in serialization processes
122+
- Better type consistency across all framework components
123+
124+
### 📝 Docs
125+
126+
- Reorganized mathematical notation docs: moved to lowercase `mathematical-notation/` with subdirectories (`elements/`, `features/`, `modeling-patterns/`)
127+
- Added comprehensive documentation pages: `dimensions.md` (time/period/scenario), `effects-penalty-objective.md`, modeling patterns
128+
- Enhanced all element pages with implementation details, cross-references, and "See Also" sections
129+
- Rewrote README and landing page with clearer vision, roadmap, and universal applicability emphasis
130+
- Removed deprecated `docs/SUMMARY.md`, updated `mkdocs.yml` for new structure
131+
- Tightened docstrings in core modules with better cross-referencing
132+
- Added recipies section to docs
112133
113134
### 🚧 Known Issues
114-
* IO for single Interfaces/Elements to Datasets might not work properly if the Interface/Element is not part of a fully transformed and connected FlowSystem. This arises from Numeric Data not being stored as xr.DataArray by the user. To avoid this, always use the `to_dataset()` on Elements inside a FlowSystem that's connected and transformed.
135+
136+
- IO for single Interfaces/Elements to Datasets might not work properly if the Interface/Element is not part of a fully transformed and connected FlowSystem. This arises from Numeric Data not being stored as xr.DataArray by the user. To avoid this, always use the `to_dataset()` on Elements inside a FlowSystem that's connected and transformed.
115137
116138
### 👷 Development
117-
* FlowSystem data management simplified - removed `time_series_collection` pattern in favor of direct timestep properties
118-
* Change modeling hierarchy to allow for more flexibility in future development. This leads to minimal changes in the access and creation of Submodels and their variables.
119-
* Added new module `.modeling` that contains Modelling primitives and utilities
120-
* Clearer separation between the main Model and "Submodels"
121-
* Improved access to the Submodels and their variables, constraints and submodels
122-
* Added `__repr__()` for Submodels to easily inspect its content
123-
* Enhanced data handling methods
124-
* `fit_to_model_coords()` method for data alignment
125-
* `fit_effects_to_model_coords()` method for effect data processing
126-
* `connect_and_transform()` method replacing several operations
127-
* **Testing improvements**: Eliminated warnings during test execution
128-
* Updated deprecated code patterns in tests and examples (e.g., `sink`/`source` → `inputs`/`outputs`, `'H'` → `'h'` frequency)
129-
* Refactored plotting logic to handle test environments explicitly with non-interactive backends
130-
* Added comprehensive warning filters in `__init__.py` and `pyproject.toml` to suppress third-party library warnings
131-
* Improved test fixtures with proper figure cleanup to prevent memory leaks
132-
* Enhanced backend detection and handling in `plotting.py` for both Matplotlib and Plotly
139+
140+
- FlowSystem data management simplified - removed `time_series_collection` pattern in favor of direct timestep properties
141+
- Change modeling hierarchy to allow for more flexibility in future development. This leads to minimal changes in the access and creation of Submodels and their variables.
142+
- Added new module `.modeling` that contains Modelling primitives and utilities
143+
- Clearer separation between the main Model and "Submodels"
144+
- Improved access to the Submodels and their variables, constraints and submodels
145+
- Added `__repr__()` for Submodels to easily inspect its content
146+
- Enhanced data handling methods
147+
- `fit_to_model_coords()` method for data alignment
148+
- `fit_effects_to_model_coords()` method for effect data processing
149+
- `connect_and_transform()` method replacing several operations
150+
- **Testing improvements**: Eliminated warnings during test execution
151+
- Updated deprecated code patterns in tests and examples (e.g., `sink`/`source` → `inputs`/`outputs`, `'H'` → `'h'` frequency)
152+
- Refactored plotting logic to handle test environments explicitly with non-interactive backends
153+
- Added comprehensive warning filters in `__init__.py` and `pyproject.toml` to suppress third-party library warnings
154+
- Improved test fixtures with proper figure cleanup to prevent memory leaks
155+
- Enhanced backend detection and handling in `plotting.py` for both Matplotlib and Plotly
133156
134157
135158
Until here -->

0 commit comments

Comments
 (0)