Feature/rename calculation to optimization (#484)

* Rename Calcualtion to optimization.py

# Conflicts:
#	flixopt/calculation.py

* Rename new classes slightly

* Also rename results classes

* FInalize port to new names

* Add old methods

* Udpate CHANGELOG.md

* Temp

* I've successfully renamed all aggregation-related classes and modules to use "clustering" terminology for better consistency with the ClusteredOptimization class
  name.

  Changes Made:

  1. Module renamed:
    - aggregation.py → clustering.py (via git mv)
  2. Classes renamed:
    - Aggregation → Clustering
    - AggregationParameters → ClusteringParameters
    - AggregationModel → ClusteringModel
  3. Updated references in:
    - optimization.py: All imports, attributes, and method parameters
    - calculation.py: Import statement (for backward compat type hints)
    - __init__.py: Exports (includes both old and new names)
    - Module docstrings updated
  4. Attribute updates:
    - ClusteredOptimization.clustering_parameters
    - ClusteredOptimization.clustering
    - ClusteredOptimization.clustering_model
    - self.durations['clustering']
    - Label strings: 'Clustering' instead of 'Aggregation'
  5. Backward compatibility:
    - Added deprecated aliases in clustering.py for all old class names
    - Old names exported from __init__.py with deprecation warnings
    - All warnings point to v6.0.0 removal
  6. Changelog updated: Added all clustering renames to the breaking changes section

* Bugfixes

* Use correct deprecation version removal

* Import fix

* Improve docstrings and remove duplicate check

* Remove loguru usage

* Bugfix

* Move solve to Optimization class

* 1. ✅ Added validation for nr_of_previous_values in SegmentedOptimization to prevent silent indexing bugs
  2. ✅ Fixed active_timesteps type annotation to include None
  3. ✅ Fixed fix_sizes() docstring/implementation inconsistency for optional ds parameter

  The changelog now documents all the bug fixes that were applied based on the code review feedback.

* Update CHANGELOG.md

* Update tests

* Update tests

* Add setting logger level to SUCCESS directly

* Remove warnings from examples

* Remove warnings from examples

* Fix SUCCESS Level setting

* 1. Exported SUCCESS_LEVEL Constant ✓

  - Added SUCCESS_LEVEL to __all__ in flixopt/config.py:20
  - Users can now import and use it: from flixopt.config import SUCCESS_LEVEL

  2. Enhanced Documentation ✓

  - CONFIG.Logging docstring (flixopt/config.py:227-262):
    - Added "Log Levels" section explaining all levels including SUCCESS (25)
    - Added examples showing how to use SUCCESS level as string, numeric, or constant
    - Shows that SUCCESS is between INFO (20) and WARNING (30)
  - set_colors() docstring (flixopt/config.py:460):
    - Already included SUCCESS in color customization examples

  3. Comprehensive Test Coverage ✓

  Added 5 new tests in tests/test_config.py:81-139:
  - test_success_level_as_minimum: Verifies SUCCESS level filtering (INFO hidden, SUCCESS shown, WARNING shown)
  - test_success_level_numeric: Tests using numeric value (25)
  - test_success_level_constant: Tests using SUCCESS_LEVEL constant
  - test_success_file_logging: Tests file logging with SUCCESS level
  - test_success_color_customization: Tests color customization

* Removed:
  - ❌ Monkey-patching logging.Logger.success = ...
  - ❌ success() wrapper function
  - ❌ All the complexity and fragility

  Kept:
  - ✅ SUCCESS_LEVEL = 25 constant (exported in __all__)
  - ✅ logging.addLevelName(SUCCESS_LEVEL, 'SUCCESS')
  - ✅ Clean documentation

* Fix singel line coloring

* FIx single and multiline coloring

* Add proper .modeled, .main_results and .summary to SegmentedOptimization

* Updaet CHANGELOG.md

* Implement Protocol

* Add proper type hints

* Remove not needed hints

* rename methods

* rename calculation variables to optimization

* Fixed the _initialize_optimization_common call in SegmentedOptimization.__init_

* Make init more explicit

* 1. Fixed outdated docstring in SegmentedResults.setup_colors
  2. Fixed misleading objective calculation in SegmentedOptimization.main_result
   3. Enhanced docstring warning (flixopt/optimization.py:868-87

* Change assertions to proper Exceptions

* Updated Terminology in docs:
  Key Terminology Changes:

  | Old                   | New                   |
  |-----------------------|-----------------------|
  | Calculation           | Optimization          |
  | CalculationResults    | Results               |
  | FullCalculation       | Optimization          |
  | SegmentedCalculation  | SegmentedOptimization |
  | AggregatedCalculation | ClusteredOptimization |
  | calculation modes     | optimization modes    |

* Add missing type hints and rename files mentioning claculation

* renamed all the "aggregation" attributes and methods to "clustering" while maintaining full backward compatibility.

* Improve naming in example

* Fix remaining mentions of Calculation

* Imrpove docstring

* Improve conftest.py

* Changed x-axis label from "Calculation type" to "Optimization type" for
  consistency with the renamed terminolog

* Fixed xarray boolean comparisons by adding .item() to convert DataArray aggregates to scalar values
  before use in conditional statements. This prevents ValueError: The truth value of a DataArray is ambiguous errors

* Updated TimeSeriesData class docstring from "with aggregation metadata" to "with clustering metadata" to

* Fix tests

* removed the unused hours_per_timestep attribute from SegmentedResults.__init__:
  - Issue: This attribute was computed with incorrect semantics (using all_timesteps instead of timesteps_extra, producing N-1 values instead of
  N)
  - Fix: Completely removed the line since it was never accessed anywhere in the codebase
  - Impact: No functionality affected - this was dead code with no consumers

* Add early validation

* Remove not needed type hint

* Add guards against results accessing before modeling

* Backward compatibility for legacy JSON key (lines 2128-2133):

* Guard against empty segment_results

* Fix deprecation of flow_system parameter in results.py

* Reuse SUCCESS_LEVEL constant

* Typo

* Typo

* Revert docstring changes

* Improve docstring

* Update CHANGELOG.md

* updated results.py to use the new naming scheme

* Further renamings

* Further renamings

* Rename CalculationResultsPaths to ResultsPaths

* Rename CalculationResultsPaths to ResultsPaths

* Change folder.mkdir(parents=False to True

* Temp

* Synchronized folder creation across codebase to always use parents=True and exist_ok=True

* added overwrite protection to prevent accidentally overwriting Results and SegmentedResults files.

* Use unique names in tests

* Improve logging message

* Improve CHANGELOG.md

* Improve CHANGELOG.md

Author: FBumann

CHANGELOG.md

@@ -56,24 +56,46 @@ If upgrading from v2.x, see the [v3.0.0 release notes](https://github.com/flixOp
 If upgrading from v2.x, see the [v3.0.0 release notes](https://github.com/flixOpt/flixOpt/releases/tag/v3.0.0) and [Migration Guide](https://flixopt.github.io/flixopt/latest/user-guide/migration-guide-v3/).
 
 ### ✨ Added
+- `overwrite` parameter when saving results to file. If True, overwrite existing files.
 
 ### 💥 Breaking Changes
 
 ### ♻️ Changed
 
+- Now creates the Results folder even i fparents didnt exist
+
 ### 🗑️ Deprecated
 
+**Class and module renaming:**
+- `FullCalculation` → `Optimization`
+- `AggregatedCalculation` → `ClusteredOptimization`
+- `SegmentedCalculation` → `SegmentedOptimization`
+- `CalculationResults` → `Results`
+- `SegmentedCalculationResults` → `SegmentedResults`
+- `Aggregation` → `Clustering`
+- `AggregationParameters` → `ClusteringParameters`
+- `AggregationModel` → `ClusteringModel`
+- Module: `calculation.py` → `optimization.py`
+- Module: `aggregation.py` → `clustering.py`
+
+Old names remain available with deprecation warnings (removed in v5.0.0).
+
 ### 🔥 Removed
 
 ### 🐛 Fixed
 
+- Fixed `fix_sizes()` docstring/implementation inconsistency for optional `ds` parameter
+
 ### 🔒 Security
 
 ### 📦 Dependencies
 
 ### 📝 Docs
 
 ### 👷 Development
+- Fixed `active_timesteps` type annotation to include `None`
+- Fixed xarray truth-value ambiguity in `main_results` buses with excess filter
+- Added validation for `nr_of_previous_values` in `SegmentedOptimization` to prevent silent indexing bugs
 
 ### 🚧 Known Issues
 

README.md

@@ -42,11 +42,11 @@ flow_system = fx.FlowSystem(timesteps)
 flow_system.add_elements(buses, components, effects)
 
 # 2. Create and solve
-calculation = fx.FullCalculation("MyModel", flow_system)
-calculation.solve()
+optimization = fx.Optimization("MyModel", flow_system)
+optimization.solve(fx.solvers.HighsSolver())
 
 # 3. Analyze results
-calculation.results.solution
+optimization.results.solution
 ```
 
 **Get started with real examples:**
@@ -90,8 +90,8 @@ boiler = fx.Boiler("Boiler", eta=0.9, ...)
 **Multi-criteria optimization:** Model costs, emissions, resource use - any custom metric. Optimize single objectives or use weighted combinations and ε-constraints.
 → [Effects documentation](https://flixopt.github.io/flixopt/latest/user-guide/mathematical-notation/effects-penalty-objective/)
 
-**Performance at any scale:** Choose calculation modes without changing your model - Full, Segmented, or Aggregated (using [TSAM](https://github.com/FZJ-IEK3-VSA/tsam)).
-→ [Calculation modes](https://flixopt.github.io/flixopt/latest/api-reference/calculation/)
+**Performance at any scale:** Choose optimization modes without changing your model - Optimization, SegmentedOptimization, or ClusteredOptimization (using [TSAM](https://github.com/FZJ-IEK3-VSA/tsam)).
+→ [Optimization modes](https://flixopt.github.io/flixopt/latest/api-reference/optimization/)
 
 **Built for reproducibility:** Self-contained NetCDF result files with complete model information. Load results months later - everything is preserved.
 → [Results documentation](https://flixopt.github.io/flixopt/latest/api-reference/results/)

docs/examples/03-Calculation Modes.md docs/examples/03-Optimization Modes.mddocs/examples/03-Calculation Modes.md renamed to docs/examples/03-Optimization Modes.md

@@ -1,5 +1,5 @@
-# Calculation Mode comparison
+# Optimization Modes Comparison
 **Note:** This example relies on time series data. You can find it in the `examples` folder of the FlixOpt repository.
 ```python
-{! ../examples/03_Calculation_types/example_calculation_types.py !}
+{! ../examples/03_Optimization_modes/example_optimization_modes.py !}
 ```

docs/examples/index.md

@@ -9,6 +9,6 @@ We work on improving this gallery. If you have something to share, please contac
 1. [Minimal Example](00-Minimal Example.md) - The simplest possible FlixOpt model
 2. [Simple Example](01-Basic Example.md) - A basic example with more features
 3. [Complex Example](02-Complex Example.md) - A comprehensive example with result saving and loading
-4. [Calculation Modes](03-Calculation Modes.md) - Comparison of different calculation modes
+4. [Optimization Modes](03-Optimization Modes.md) - Comparison of different optimization modes
 5. [Scenarios](04-Scenarios.md) - Working with scenarios in FlixOpt
 6. [Two-stage Optimization](05-Two-stage-optimization.md) - Two-stage optimization approach

docs/getting-started.md

@@ -53,7 +53,7 @@ Working with FlixOpt follows a general pattern:
 2. **Define [`Effects`][flixopt.effects.Effect]** (costs, emissions, etc.)
 3. **Define [`Buses`][flixopt.elements.Bus]** as connection points in your system
 4. **Add [`Components`][flixopt.components]** like converters, storage, sources/sinks with their Flows
-5. **Run [`Calculations`][flixopt.calculation]** to optimize your system
+5. **Run [`Optimizations`][flixopt.optimization]** to optimize your system
 6. **Analyze [`Results`][flixopt.results]** using built-in or external visualization tools
 
 ## Next Steps

docs/user-guide/core-concepts.md

@@ -98,23 +98,23 @@ This approach allows for multi-criteria optimization using both:
  - **Weighted Sum Method**: Optimize a theoretical Effect which other Effects crosslink to
  - **ε-constraint method**: Constrain effects to specific limits
 
-### Calculation
+### Optimization
 
-A [`FlowSystem`][flixopt.flow_system.FlowSystem] can be converted to a Model and optimized by creating a [`Calculation`][flixopt.calculation.Calculation] from it.
+A [`FlowSystem`][flixopt.flow_system.FlowSystem] can be converted to a Model and optimized by creating an [`Optimization`][flixopt.optimization.Optimization] from it.
 
-FlixOpt offers different calculation modes:
+FlixOpt offers different optimization modes:
 
-- [`FullCalculation`][flixopt.calculation.FullCalculation] - Solves the entire problem at once
-- [`SegmentedCalculation`][flixopt.calculation.SegmentedCalculation] - Solves the problem in segments (with optioinal overlap), improving performance for large problems
-- [`AggregatedCalculation`][flixopt.calculation.AggregatedCalculation] - Uses typical periods to reduce computational requirements
+- [`Optimization`][flixopt.optimization.Optimization] - Solves the entire problem at once
+- [`SegmentedOptimization`][flixopt.optimization.SegmentedOptimization] - Solves the problem in segments (with optional overlap), improving performance for large problems
+- [`ClusteredOptimization`][flixopt.optimization.ClusteredOptimization] - Uses typical periods to reduce computational requirements
 
 ### Results
 
-The results of a calculation are stored in a [`CalculationResults`][flixopt.results.CalculationResults] object.
-This object contains the solutions of the optimization as well as all information about the [`Calculation`][flixopt.calculation.Calculation] and the [`FlowSystem`][flixopt.flow_system.FlowSystem] it was created from.
-The solution is stored as an `xarray.Dataset`, but can be accessed through their assotiated Component, Bus or Effect.
+The results of an optimization are stored in a [`Results`][flixopt.results.Results] object.
+This object contains the solutions of the optimization as well as all information about the [`Optimization`][flixopt.optimization.Optimization] and the [`FlowSystem`][flixopt.flow_system.FlowSystem] it was created from.
+The solution is stored as an `xarray.Dataset`, but can be accessed through their associated Component, Bus or Effect.
 
-This [`CalculationResults`][flixopt.results.CalculationResults] object can be saved to file and reloaded from file, allowing you to analyze the results anytime after the solve.
+This [`Results`][flixopt.results.Results] object can be saved to file and reloaded from file, allowing you to analyze the results anytime after the solve.
 
 ## How These Concepts Work Together
 
@@ -128,12 +128,12 @@ The process of working with FlixOpt can be divided into 3 steps:
      -  Add
      - [`FlowSystems`][flixopt.flow_system.FlowSystem] can also be loaded from a netCDF file*
 2. Translate the model to a mathematical optimization problem
-     - Create a [`Calculation`][flixopt.calculation.Calculation] from your FlowSystem and choose a Solver
-     - ...The Calculation is translated internally to a mathematical optimization problem...
+     - Create an [`Optimization`][flixopt.optimization.Optimization] from your FlowSystem and choose a Solver
+     - ...The Optimization is translated internally to a mathematical optimization problem...
      - ...and solved by the chosen solver.
 3. Analyze the results
-     - The results are stored in a [`CalculationResults`][flixopt.results.CalculationResults] object
-     - This object can be saved to file and reloaded from file, retaining all information about the calculation
+     - The results are stored in a [`Results`][flixopt.results.Results] object
+     - This object can be saved to file and reloaded from file, retaining all information about the optimization
      - As it contains the used [`FlowSystem`][flixopt.flow_system.FlowSystem], it fully documents all assumptions taken to create the results.
 
 <figure markdown>
@@ -152,4 +152,4 @@ This allows to adjust your model to very specific requirements without loosing t
 <!--- [FlowSystem](api/flow_system.md) - Time series and system organization-->
 <!--- [Components](api/components.md) - Available component types and how to use them-->
 <!--- [Effects](apieffects.md) - Costs, emissions, and other impacts-->
-<!--- [Calculation Modes](api/calculation.md) - Different approaches to solving your model-->
+<!--- [Optimization Modes](api/optimization.md) - Different approaches to solving your model-->

docs/user-guide/mathematical-notation/dimensions.md

@@ -288,7 +288,7 @@ flow_system = fx.FlowSystem(
 #  [6.0, 4.0]]   # 2040: 10 × [0.6, 0.4]
 ```
 
-**Normalization:** Set `normalize_weights=False` in `Calculation` to turn of the normalization.
+**Normalization:** Set `normalize_weights=False` in `Optimization` to turn off the normalization.
 
 ---
 

docs/user-guide/migration-guide-v3.md

@@ -76,12 +76,12 @@ Terminology changed and sharing system inverted: effects now "pull" shares.
 
 ---
 
-### FlowSystem & Calculation
+### FlowSystem & Optimization
 
 | Change | Description |
 |--------|-------------|
-| **FlowSystem copying** | Each `Calculation` gets its own copy (independent) |
-| **do_modeling() return** | Returns `Calculation` object (access model via `.model` property) |
+| **FlowSystem copying** | Each `Optimization` gets its own copy (independent) |
+| **do_modeling() return** | Returns `Optimization` object (access model via `.model` property) |
 | **Storage arrays** | Arrays match timestep count (no extra element) |
 | **Final charge state** | Use `relative_minimum_final_charge_state` / `relative_maximum_final_charge_state` |
 
@@ -135,7 +135,7 @@ Terminology changed and sharing system inverted: effects now "pull" shares.
     | `agg_group` | `aggregation_group` |
     | `agg_weight` | `aggregation_weight` |
 
-??? abstract "Calculation"
+??? abstract "Optimization"
 
     | Old (v2.x) | New (v3.0.0) |
     |------------|--------------|
@@ -207,7 +207,7 @@ Terminology changed and sharing system inverted: effects now "pull" shares.
 | Issue | Solution |
 |-------|----------|
 | Effect shares not working | See [Effect System Redesign](#effect-system-redesign) |
-| Storage dimensions wrong | See [FlowSystem & Calculation](#flowsystem-calculation) |
+| Storage dimensions wrong | See [FlowSystem & Optimization](#flowsystem-optimization) |
 | Bus assignment error | See [String Labels](#string-labels) |
 | KeyError in results | See [Variable Names](#variable-names) |
 | `AttributeError: model` | Rename `.model` → `.submodel` |
@@ -220,7 +220,7 @@ Terminology changed and sharing system inverted: effects now "pull" shares.
 | Category | Tasks |
 |----------|-------|
 | **Install** | • `pip install --upgrade flixopt` |
-| **Breaking changes** | • Update [effect sharing](#effect-system-redesign)<br>• Update [variable names](#variable-names)<br>• Update [string labels](#string-labels)<br>• Fix [storage arrays](#flowsystem-calculation)<br>• Update [Calculation API](#flowsystem-calculation)<br>• Update [class names](#other-changes) |
+| **Breaking changes** | • Update [effect sharing](#effect-system-redesign)<br>• Update [variable names](#variable-names)<br>• Update [string labels](#string-labels)<br>• Fix [storage arrays](#flowsystem-optimization)<br>• Update [Optimization API](#flowsystem-optimization)<br>• Update [class names](#other-changes) |
 | **Configuration** | • Enable [logging](#other-changes) if needed |
 | **Deprecated** | • Update [deprecated parameters](#deprecated-parameters) (recommended) |
 | **Testing** | • Test thoroughly<br>• Validate results match v2.x |

examples/00_Minmal/minimal_example.py

@@ -32,5 +32,5 @@
         ),
     )
 
-    calculation = fx.FullCalculation('Simulation1', flow_system).do_modeling().solve(fx.solvers.HighsSolver(0.01, 60))
-    calculation.results['Heat'].plot_node_balance()
+    optimization = fx.Optimization('Simulation1', flow_system).solve(fx.solvers.HighsSolver(0.01, 60))
+    optimization.results['Heat'].plot_node_balance()

examples/01_Simple/simple_example.py

@@ -104,24 +104,24 @@
 
     # --- Define and Run Calculation ---
     # Create a calculation object to model the Flow System
-    calculation = fx.FullCalculation(name='Sim1', flow_system=flow_system)
-    calculation.do_modeling()  # Translate the model to a solvable form, creating equations and Variables
+    optimization = fx.Optimization(name='Sim1', flow_system=flow_system)
+    optimization.do_modeling()  # Translate the model to a solvable form, creating equations and Variables
 
     # --- Solve the Calculation and Save Results ---
-    calculation.solve(fx.solvers.HighsSolver(mip_gap=0, time_limit_seconds=30))
+    optimization.solve(fx.solvers.HighsSolver(mip_gap=0, time_limit_seconds=30))
 
     # --- Analyze Results ---
     # Colors are automatically assigned using default colormap
     # Optional: Configure custom colors with
-    calculation.results.setup_colors()
-    calculation.results['Fernwärme'].plot_node_balance_pie()
-    calculation.results['Fernwärme'].plot_node_balance()
-    calculation.results['Storage'].plot_charge_state()
-    calculation.results.plot_heatmap('CHP(Q_th)|flow_rate')
+    optimization.results.setup_colors()
+    optimization.results['Fernwärme'].plot_node_balance_pie()
+    optimization.results['Fernwärme'].plot_node_balance()
+    optimization.results['Storage'].plot_charge_state()
+    optimization.results.plot_heatmap('CHP(Q_th)|flow_rate')
 
     # Convert the results for the storage component to a dataframe and display
-    df = calculation.results['Storage'].node_balance_with_charge_state()
+    df = optimization.results['Storage'].node_balance_with_charge_state()
     print(df)
 
     # Save results to file for later usage
-    calculation.results.to_file()
+    optimization.results.to_file()