update to main

.github/workflows/deploy-docs.yaml

@@ -0,0 +1,33 @@
+name: Documentation
+
+on:
+  release:
+    types: [created]  # Automatically deploy docs on release
+  workflow_dispatch:  # Allow manual triggering
+
+jobs:
+  deploy-docs:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0  # Fetch all history for proper versioning
+
+      - name: Configure Git Credentials
+        run: |
+          git config user.name github-actions[bot]
+          git config user.email 41898282+github-actions[bot]@users.noreply.github.com
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: 3.11
+
+      - name: Install documentation dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[docs]"
+
+      - name: Deploy docs
+        run: |
+          VERSION=${GITHUB_REF#refs/tags/v}
+          mike deploy --push --update-aliases $VERSION latest

.github/workflows/python-app.yaml

@@ -37,7 +37,7 @@ jobs:
     strategy:
       fail-fast: false  # Continue testing other Python versions if one fails
       matrix:
-        python-version: ['3.10', '3.11', '3.12']
+        python-version: ['3.10', '3.11', '3.12', '3.13']
 
     steps:
       - name: Check out code
@@ -82,7 +82,7 @@ jobs:
 
       - name: Upload to TestPyPI
         run: |
-          twine upload --repository testpypi dist/*
+          twine upload --repository testpypi dist/* --verbose
         env:
           TWINE_USERNAME: __token__
           TWINE_PASSWORD: ${{ secrets.TEST_PYPI_API_TOKEN }}
@@ -99,12 +99,12 @@ jobs:
           (sleep 30 && pip install --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ $PACKAGE_NAME) || \
           (sleep 60 && pip install --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ $PACKAGE_NAME)
           # Basic import test
-          python -c "import $PACKAGE_NAME; print('Installation successful!')"
+          python -c "import flixopt; print('Installation successful!')"
 
   publish-pypi:
     name: Publish to PyPI
     runs-on: ubuntu-22.04
-    needs: [publish-testpypi]  # Only run after TestPyPI publish succeeds
+    needs: [test]  # Only run after TestPyPI publish succeeds
     if: github.event_name == 'release' && github.event.action == 'created'  # Only on release creation
 
     steps:
@@ -124,3 +124,24 @@ jobs:
       - name: Build the distribution
         run: |
           python -m build
+
+      - name: Upload to PyPI
+        run: |
+          twine upload dist/* --verbose
+        env:
+          TWINE_USERNAME: __token__
+          TWINE_PASSWORD: ${{ secrets.PYPI_API_TOKEN }}
+
+      - name: Verify PyPI installation
+        run: |
+          # Create a temporary environment to test installation
+          python -m venv prod_test_env
+          source prod_test_env/bin/activate
+          # Get the package name from the built distribution
+          PACKAGE_NAME=$(ls dist/*.tar.gz | head -n 1 | sed 's/dist\///' | sed 's/-[0-9].*$//')
+          # Wait for PyPI to index the package
+          sleep 60
+          # Install from PyPI
+          pip install $PACKAGE_NAME
+          # Basic import test
+          python -c "import flixopt; print('PyPI installation successful!')"

.gitignore

@@ -1,4 +1,5 @@
 *.pyc
+*.log
 results/
 .idea/
 .venv/

README.md

@@ -1,134 +1,86 @@
-# flixOpt: Energy and Material Flow Optimization Framework
+# FlixOpt: Energy and Material Flow Optimization Framework
 
-**flixOpt** is a Python-based optimization framework designed to tackle energy and material flow problems using mixed-integer linear programming (MILP). Combining flexibility and efficiency, it provides a powerful platform for both dispatch and investment optimization challenges.
+[![Documentation](https://img.shields.io/badge/docs-latest-brightgreen.svg)](https://flixopt.github.io/flixopt/latest/)
+[![Build Status](https://github.com/flixOpt/flixopt/actions/workflows/python-app.yaml/badge.svg)](https://github.com/flixOpt/flixopt/actions/workflows/python-app.yaml)
+[![PyPI version](https://img.shields.io/pypi/v/flixopt)](https://pypi.org/project/flixopt/)
+[![Python Versions](https://img.shields.io/pypi/pyversions/flixopt.svg)](https://pypi.org/project/flixopt/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
 ---
 
-## 🚀 Introduction
+## 🚀 Purpose
 
-flixOpt was developed by [TU Dresden](https://github.com/gewv-tu-dresden) as part of the SMARTBIOGRID project, funded by the German Federal Ministry for Economic Affairs and Energy (FKZ: 03KB159B). Building on the Matlab-based flixOptMat framework (developed in the FAKS project), flixOpt also incorporates concepts from [oemof/solph](https://github.com/oemof/oemof-solph). 
+**flixopt** is a Python-based optimization framework designed to tackle energy and material flow problems using mixed-integer linear programming (MILP).
 
-Although flixOpt is in its early stages, it is fully functional and ready for experimentation. It is used for investment and operation decisions by energy providing companys as well as research institutions. Feedback and collaboration are highly encouraged to help shape its future.
+**flixopt** bridges the gap between high-level energy systems models like [FINE](https://github.com/FZJ-IEK3-VSA/FINE) used for design and (multi-period) investment decisions and low-level dispatch optimization tools used for operation decisions.
 
----
-
-## 📦 Installation
+**flixopt** leverages the fast and efficient [linopy](https://github.com/PyPSA/linopy/) for the mathematical modeling and [xarray](https://github.com/pydata/xarray) for data handling.
 
-Install flixOpt directly into your environment using pip. Thanks to [HiGHS](https://github.com/ERGO-Code/HiGHS?tab=readme-ov-file), flixOpt can be used without further setup.
-`pip install git+https://github.com/flixOpt/flixopt.git`
+**flixopt** provides a user-friendly interface with options for advanced users.
 
-We recommend installing flixOpt with all dependencies, which enables interactive network visualizations by [pyvis](https://github.com/WestHealth/pyvis) and time series aggregation by [tsam](https://github.com/FZJ-IEK3-VSA/tsam).
-`pip install "flixOpt[full] @ git+https://github.com/flixOpt/flixopt.git"`
+It was originally developed by [TU Dresden](https://github.com/gewv-tu-dresden) as part of the SMARTBIOGRID project, funded by the German Federal Ministry for Economic Affairs and Energy (FKZ: 03KB159B). Building on the Matlab-based flixOptMat framework (developed in the FAKS project), FlixOpt also incorporates concepts from [oemof/solph](https://github.com/oemof/oemof-solph). 
 
 ---
 
-## 🌟 Key Features and Concepts
-
-### 💡 High-level Interface...
-  - flixOpt aims to provide a user-friendly interface for defining and solving energy systems, without sacrificing fine-grained control where necessary.
-  - This is achieved through a high-level interface with many optional or default parameters.
-  - The most important concepts are:
-    - **FlowSystem**: Represents the System that is modeled.
-    - **Flow**: A Flow represents a stream of matter or energy. In an Energy-System, it could be electricity [kW]
-    - **Bus**: A Bus represents a balancing node in the Energy-System, typically connecting a demand to a supply.
-    - **Component**: A Component is a physical entity that consumes or produces matter or energy. It can also transform matter or energy into other kinds of matter or energy.
-    - **Effect**: Flows and Components can have Effects, related to their usage (or size). Common effects are *costs*, *CO2-emissions*, *primary-energy-demand* or *area-demand*. One Effect is used as the optimization target. The others can be constrained.
-  - To simplify the modeling process, high-level **Components** (CHP, Boiler, Heat Pump, Cooling Tower, Storage, etc.) are availlable.
-
-### 🎛️ ...with low-level control
-- **Segmented Linear Correlations**  
-  - Accurate modeling for efficiencies, investment effects, and sizes.
-- **On/Off Variables**
-  - Modeling On/Off-Variables and their constraints.
-    - On-Hours/Off-Hours
-    - Consecutive On-Hours/ Off-Hours
-    - Switch On/Off
-
-### 💰 Investment Optimization
-- flixOpt combines dispatch optimization with investment optimization in one model.
-- Size and/or discrete investment decisions can be modeled
-- Investment decisions can be combined with Modeling On/Off-Variables and their constraints
-
-### Further Features
-- **Multiple Effects**
-  - Couple effects (e.g., specific CO2 costs) and set constraints (e.g., max CO2 emissions).
-  - Easily switch between optimization targets (e.g., minimize CO2 or costs).
-  - This allows to solve questions like "How much does it cost to reduce CO2 emissions by 20%?"
-
-- **Advanced Time Handling**
-  - Non-equidistant timesteps supported.  
-  - Energy prices or effects in general can always be defined per hour (or per MWh...)
-
-  - A variety of predefined constraints for operational and investment optimization can be applied.
-  - Many of these are optional and only applied when necessary, keeping the amount o variables and equations low.
-
----
+## 🌟 Key Features
 
-## 🖥️ Usage Example
-![Usage Example](https://github.com/user-attachments/assets/fa0e12fa-2853-4f51-a9e2-804abbefe20c)
+- **High-level Interface** with low-level control
+    - User-friendly interface for defining flow systems
+    - Pre-defined components like CHP, Heat Pump, Cooling Tower, etc.
+    - Fine-grained control for advanced configurations
 
-**Plotting examples**:
-![flixOpt plotting](/pics/flixOpt_plotting.jpg)
+- **Investment Optimization**
+    - Combined dispatch and investment optimization
+    - Size optimization and discrete investment decisions
+    - Combined with On/Off variables and constraints
 
-## ⚙️ Calculation Modes
+- **Effects, not only Costs --> Multi-criteria Optimization**
+    - flixopt abstracts costs as so called 'Effects'. This allows to model costs, CO2-emissions, primary-energy-demand or area-demand at the same time.
+    - Effects can interact with each other(e.g., specific CO2 costs)
+    - Any of these `Effects` can be used as the optimization objective.
+    - A **Weigted Sum** of Effects can be used as the optimization objective.
+    - Every Effect can be constrained ($\epsilon$-constraint method).
 
-flixOpt offers three calculation modes, tailored to different performance and accuracy needs:
+- **Calculation Modes**
+    - **Full** - Solve the model with highest accuracy and computational requirements.
+    - **Segmented** - Speed up solving by using a rolling horizon. 
+    - **Aggregated** - Speed up solving by identifying typical periods using [TSAM](https://github.com/FZJ-IEK3-VSA/tsam). Suitable for large models.
 
-- **Full Mode**  
-  - Provides exact solutions with high computational requirements.  
-  - Recommended for detailed analyses and investment decision problems.
-
-- **Segmented Mode**  
-  - Solving a Model segmentwise, this mode can speed up the solving process for complex systems, while being fairly accurate.
-  - Utilizes variable time overlap to improve accuracy.
-  - Not suitable for large storage systems or investment decisions.
+---
 
-- **Aggregated Mode**  
-  - Automatically generates typical periods using [TSAM](https://github.com/FZJ-IEK3-VSA/tsam).  
-  - Balances speed and accuracy, making it ideal for large-scale simulations.
+## 📦 Installation
 
+Install FlixOpt via pip.
+`pip install flixopt`
+With [HiGHS](https://github.com/ERGO-Code/HiGHS?tab=readme-ov-file) included out of the box, flixopt is ready to use..
 
-## 🏗️ Architecture
+We recommend installing FlixOpt with all dependencies, which enables additional features like interactive network visualizations ([pyvis](https://github.com/WestHealth/pyvis)) and time series aggregation ([tsam](https://github.com/FZJ-IEK3-VSA/tsam)).
+`pip install "flixopt[full]"`
 
-- **Minimal coupling to Pyomo**
-  - Included independent module is used to organize variables and equations, independently of a specific modeling language.
-  - While currently only working with [Pyomo](http://www.pyomo.org/), flixOpt is designed to work with different modeling languages with minor modifications ([cvxpy](https://www.cvxpy.org)).
+---
 
-- **File-based Post-Processing Unit**
-  - Results are saved to .json and .yaml files for easy access and analysis anytime.
-  - Internal plotting functions utilizing matplotlib, plotly and pandas simplify results visualization and reporting.
+## 📚 Documentation
 
-![Architecture Diagram](/pics/architecture_flixOpt.png)
+The documentation is available at [https://flixopt.github.io/flixopt/latest/](https://flixopt.github.io/flixopt/latest/)
 
 ---
 
 ## 🛠️ Solver Integration
 
-By default, flixOpt uses the open-source solver [HiGHS](https://highs.dev/) which is installed by default. However, it is compatible with additional solvers such as:  
+By default, FlixOpt uses the open-source solver [HiGHS](https://highs.dev/) which is installed by default. However, it is compatible with additional solvers such as:  
 
-- [CBC](https://github.com/coin-or/Cbc)  
-- [GLPK](https://www.gnu.org/software/glpk/)  
 - [Gurobi](https://www.gurobi.com/)  
+- [CBC](https://github.com/coin-or/Cbc)  
+- [GLPK](https://www.gnu.org/software/glpk/)
 - [CPLEX](https://www.ibm.com/analytics/cplex-optimizer)
 
-Executables can be found for example [here for CBC](https://portal.ampl.com/dl/open/cbc/) and [here for GLPK](https://sourceforge.net/projects/winglpk/) (Windows: You have to put solver-executables to the PATH-variable)
-
 For detailed licensing and installation instructions, refer to the respective solver documentation.  
 
 ---
 
 ## 📖 Citation
 
-If you use flixOpt in your research or project, please cite the following:  
+If you use FlixOpt in your research or project, please cite the following:  
 
 - **Main Citation:** [DOI:10.18086/eurosun.2022.04.07](https://doi.org/10.18086/eurosun.2022.04.07)  
 - **Short Overview:** [DOI:10.13140/RG.2.2.14948.24969](https://doi.org/10.13140/RG.2.2.14948.24969)  
-
----
-
-## 🔧 Development and Testing
-
-Run the tests using:  
-
-```bash
-python -m unittest discover -s tests

docs/SUMMARY.md

@@ -0,0 +1,7 @@
+- [Home](index.md)
+- [Getting Started](getting-started.md)
+- [User Guide](user-guide/)
+- [Examples](examples/)
+- [FAQ](faq/)
+- [API-Reference](api-reference/)
+- [Release Notes](release-notes/)

docs/contribute.md

@@ -0,0 +1,49 @@
+# Contributing to the Project
+
+We warmly welcome contributions from the community! This guide will help you get started with contributing to our project.
+
+## Development Setup
+1. Clone the repository `git clone https://github.com/flixOpt/flixopt.git`
+2. Install the development dependencies `pip install -editable .[dev, docs]`
+3. Run `pytest` and `ruff check .` to ensure your code passes all tests
+
+## Documentation
+FlixOpt uses [mkdocs](https://www.mkdocs.org/) to generate documentation. To preview the documentation locally, run `mkdocs serve` in the root directory.
+
+## Helpful Commands
+- `mkdocs serve` to preview the documentation locally. Navigate to `http://127.0.0.1:8000/` to view the documentation.
+- `pytest` to run the test suite (You can also run the provided python script `run_all_test.py`)
+- `ruff check .` to run the linter
+- `ruff check . --fix` to automatically fix linting issues
+
+---
+# Best practices
+
+## Coding Guidelines
+
+- Follow PEP 8 style guidelines
+- Write clear, commented code
+- Include type hints
+- Create or update tests for new functionality
+- Ensure 100% test coverage for new code
+
+## Branches
+As we start to think FlixOpt in **Releases**, we decided to introduce multiple **dev**-branches instead of only one:
+Following the **Semantic Versioning** guidelines, we introduced:
+- `next/patch`: This is where all pull requests for the next patch release (1.0.x) go.  
+- `next/minor`: This is where all pull requests for the next minor release (1.x.0) go.  
+- `next/major`: This is where all pull requests for the next major release (x.0.0) go.
+
+Everything else remains in `feature/...`-branches.
+
+## Pull requests
+Every feature or bugfix should be merged into one of the 3 [release branches](#branches), using **Squash and merge** or a regular **single commit**.
+At some point, `next/minor` or `next/major` will get merged into `main` using a regular **Merge**  (not squash).
+*This ensures that Features are kept separate, and the `next/...`branches stay in synch with ``main`.*
+
+## Releases
+As stated, we follow **Semantic Versioning**.
+Right after one of the 3 [release branches](#branches) is merged into main, a **Tag** should be added to the merge commit and pushed to the main branch. The tag has the form `v1.2.3`.
+With this tag,  a release with **Release Notes** must be created. 
+
+*This is our current best practice*

docs/examples/00-Minimal Example.md

@@ -0,0 +1,5 @@
+# Minimal Example
+
+```python
+{! ../examples/00_Minmal/minimal_example.py !}
+```

docs/examples/01-Basic Example.md

@@ -0,0 +1,5 @@
+# Simple example
+
+```python
+{! ../examples/01_Simple/simple_example.py !}
+```

docs/examples/02-Complex Example.md

@@ -0,0 +1,10 @@
+# Complex example
+This saves the results of a calculation to file and reloads them to analyze the results
+## Build the Model
+```python
+{! ../examples/02_Complex/complex_example.py !}
+```
+## Load the Results from file
+```python
+{! ../examples/02_Complex/complex_example_results.py !}
+```

docs/examples/03-Calculation Modes.md

@@ -0,0 +1,5 @@
+# Calculation Mode 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 !}
+```

docs/examples/index.md

@@ -0,0 +1,5 @@
+# Examples
+
+Here you can find a collection of examples that demonstrate how to use FlixOpt.
+
+We work on improving this gallery. If you have something to share, please contact us!