Feature/docs (#189)

* Add docs

* Change docs type to numpy

* Automate docs

* Only deploy docs on release

* ruff check

Author: FBumann

.github/workflows/python-app.yaml

@@ -56,6 +56,24 @@ jobs:
       - name: Run tests
         run: pytest -v -p no:warnings
 
+  deploy-docs:
+    runs-on: ubuntu-latest
+    if: github.event_name == 'release' && github.event.action == 'created'  # Only on release creation
+    steps:
+      - uses: actions/checkout@v4
+      - 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 dependencies
+        run: |
+          pip install -e .[docs]
+      - name: Deploy documentation
+        run: mkdocs gh-deploy --force
+
   publish-testpypi:
     name: Publish to TestPyPI
     runs-on: ubuntu-22.04

docs/SUMMARY.md

@@ -0,0 +1,6 @@
+- [Home](index.md)
+- [Getting Started](getting-started.md)
+- [Concepts & Math](concepts-and-math/)
+- [Examples](examples/)
+- [API-Reference](api-reference/)
+- [Contribute](contribute.md)

docs/concepts-and-math/Mathematical Description.md

@@ -0,0 +1,108 @@
+
+# Mathematical Notation
+
+## Naming Conventions
+
+flixOpt uses the following naming conventions:
+
+- All optimization variables are denoted by italic letters (e.g., $x$, $y$, $z$)
+- All parameters and constants are denoted by non italic small letters (e.g., $\text{a}$, $\text{b}$, $\text{c}$)
+- All Sets are denoted by greek capital letters (e.g., $\mathcal{F}$, $\mathcal{E}$)
+- All units of a set are denoted by greek small letters (e.g., $\mathcal{f}$, $\mathcal{e}$)
+- The letter $i$ is used to denote an index (e.g., $i=1,\dots,\text n$)
+- All time steps are denoted by the letter $\text{t}$ (e.g., $\text{t}_0$, $\text{t}_1$, $\text{t}_i$)
+
+## Buses
+
+The balance equation for a bus is:
+
+$$ \label{eq:bus_balance}
+  \sum_{f_\text{in} \in \mathcal{F}_\text{in}} p_{f_\text{in}}(\text{t}_i) =
+  \sum_{f_\text{out} \in \mathcal{F}_\text{out}} p_{f_\text{out}}(\text{t}_i)
+$$
+
+Optionally, a Bus can have a `excess_penalty_per_flow_hour` parameter, which allows to penalize the balance for missing or excess flow-rates.
+This is usefull as it handles a possible ifeasiblity gently.
+
+This changes the balance to
+
+$$ \label{eq:bus_balance-excess}
+  \sum_{f_\text{in} \in \mathcal{F}_\text{in}} p_{f_ \text{in}}(\text{t}_i) + \phi_\text{in}(\text{t}_i) =
+  \sum_{f_\text{out} \in \mathcal{F}_\text{out}} p_{f_\text{out}}(\text{t}_i) + \phi_\text{out}(\text{t}_i)
+$$
+
+The penalty term is defined as
+
+$$ \label{eq:bus_penalty}
+  s_{b \rightarrow \Phi}(\text{t}_i) =
+      \text a_{b \rightarrow \Phi}(\text{t}_i) \cdot \Delta \text{t}_i
+      \cdot [ \phi_\text{in}(\text{t}_i) + \phi_\text{out}(\text{t}_i) ]
+$$
+
+With:
+
+- $\mathcal{F}_\text{in}$ and $\mathcal{F}_\text{out}$ being the set of all incoming and outgoing flows
+- $p_{f_\text{in}}(\text{t}_i)$ and $p_{f_\text{out}}(\text{t}_i)$ being the flow-rate at time $\text{t}_i$ for flow $f_\text{in}$ and $f_\text{out}$, respectively
+- $\phi_\text{in}(\text{t}_i)$ and $\phi_\text{out}(\text{t}_i)$ being the missing or excess flow-rate at time $\text{t}_i$, respectively
+- $\text{t}_i$ being the time step
+- $s_{b \rightarrow \Phi}(\text{t}_i)$ being the penalty term
+- $\text a_{b \rightarrow \Phi}(\text{t}_i)$ being the penalty coefficient (`excess_penalty_per_flow_hour`)
+
+## Flows
+
+The flow-rate is the main optimization variable of the Flow. It's limited by the size of the Flow and relative bounds \eqref{eq:flow_rate}.
+
+$$ \label{eq:flow_rate}
+    \text P \cdot \text p^{\text{L}}_{\text{rel}}(\text{t}_{i})
+    \leq p(\text{t}_{i}) \leq
+    \text P \cdot \text p^{\text{U}}_{\text{rel}}(\text{t}_{i})
+$$
+
+With:
+
+- $\text P$ being the size of the Flow
+- $p(\text{t}_{i})$ being the flow-rate at time $\text{t}_{i}$
+- $\text p^{\text{L}}_{\text{rel}}(\text{t}_{i})$ being the relative lower bound (typically 0)
+- $\text p^{\text{U}}_{\text{rel}}(\text{t}_{i})$ being the relative upper bound (typically 1)
+
+With $\text p^{\text{L}}_{\text{rel}}(\text{t}_{i}) = 0$ and $\text p^{\text{U}}_{\text{rel}}(\text{t}_{i}) = 1$,
+equation \eqref{eq:flow_rate} simplifies to
+
+$$
+    0 \leq p(\text{t}_{i}) \leq \text P
+$$
+
+
+This mathematical Formulation can be extended or changed when using [OnOffParameters](#omoffparameters)
+to define the On/Off state of the Flow, or [InvestParameters](#investments),
+which changes the size of the Flow from a constant to an optimization variable.
+
+## LinearConverters
+[`LinearConverters`][flixOpt.components.LinearConverter] define a ratio between incoming and outgoing [Flows](#flows).
+
+$$ \label{eq:Linear-Transformer-Ratio}
+    \sum_{f_{\text{in}} \in \mathcal F_{in}} \text a_{f_{\text{in}}}(\text{t}_i) \cdot p_{f_\text{in}}(\text{t}_i) = \sum_{f_{\text{out}} \in \mathcal F_{out}}  \text b_{f_\text{out}}(\text{t}_i) \cdot p_{f_\text{out}}(\text{t}_i)
+$$
+
+With:
+
+- $\mathcal F_{in}$ and $\mathcal F_{out}$ being the set of all incoming and outgoing flows
+- $p_{f_\text{in}}(\text{t}_i)$ and $p_{f_\text{out}}(\text{t}_i)$ being the flow-rate at time $\text{t}_i$ for flow $f_\text{in}$ and $f_\text{out}$, respectively
+- $\text a_{f_\text{in}}(\text{t}_i)$ and $\text b_{f_\text{out}}(\text{t}_i)$ being the ratio of the flow-rate at time $\text{t}_i$ for flow $f_\text{in}$ and $f_\text{out}$, respectively
+
+With one incoming **Flow** and one outgoing **Flow**, this can be simplified to: 
+
+$$ \label{eq:Linear-Transformer-Ratio-simple}
+    \text a(\text{t}_i) \cdot p_{f_\text{in}}(\text{t}_i) = p_{f_\text{out}}(\text{t}_i)
+$$
+
+where $\text a$ can be interpreted as the conversion efficiency of the **LinearTransformer**.
+#### Piecewise Concersion factors
+The conversion efficiency can be defined as a piecewise function.
+
+## Effects
+## Features
+### InvestParameters
+### OnOffParameters
+
+## Calculation Modes

docs/concepts-and-math/index.md

@@ -0,0 +1,103 @@
+# flixOpt Concepts & Mathematical Description
+
+flixOpt is built around a set of core concepts that work together to represent and optimize energy and material flow systems. This page provides a high-level overview of these concepts and how they interact.
+
+## Core Concepts
+
+### FlowSystem
+
+The [`FlowSystem`][flixOpt.flow_system.FlowSystem] is the central organizing unit in flixOpt. 
+Every flixOpt model starts with creating a FlowSystem. It:
+
+- Defines the timesteps for the optimization
+- Contains and connects [components](#components), [buses](#buses), and [flows](#flows)
+- Manages the [effects](#effects) (objectives and constraints)
+
+### Timesteps
+Time steps are defined as a sequence of discrete time steps $\text{t}_i \in \mathcal{T} \quad \text{for} \quad i \in \{1, 2, \dots, \text{n}\}$ (left-aligned in its timespan).
+From this sequence, the corresponding time intervals $\Delta \text{t}_i \in \Delta \mathcal{T}$ are derived as 
+
+$$\Delta \text{t}_i = \text{t}_{i+1} - \text{t}_i \quad \text{for} \quad i \in \{1, 2, \dots, \text{n}-1\}$$
+
+The final time interval $\Delta \text{t}_\text n$ defaults to $\Delta \text{t}_\text n = \Delta \text{t}_{\text n-1}$, but is of course customizable.
+Non-equidistant time steps are also supported.
+
+### Buses
+
+[`Bus`][flixOpt.elements.Bus] objects represent nodes or connection points in a FlowSystem. They:
+
+- Balance incoming and outgoing flows
+- Can represent physical networks like heat, electricity, or gas 
+- Handle infeasible balances gently by allowing the balance to be closed in return for a big Penalty (optional)
+
+### Flows
+
+[`Flow`][flixOpt.elements.Flow] objects represent the movement of energy or material between a [Bus](#buses) and a [Component](#components) in a predefined direction.
+
+- Have a `flow_rate`, which is the main optimization variable of a Flow
+- Have a `size` which defines how much energy or material can be moved (fixed or part of an investment decision)
+- Have constraints to limit the flow-rate (min/max, total flow hours, on/off etc.)
+- Can have fixed profiles (for demands or renewable generation)
+- Can have [Effects](#effects) associated by their use (operation, investment, on/off, ...)
+
+### Components
+
+[`Component`][flixOpt.elements.Component] objects usually represent physical entities in your system that interact with [`Flows`][flixOpt.elements.Flow]. They include:
+
+- [`LinearConverters`][flixOpt.components.LinearConverter] - Converts input flows to output flows with (piecewise) linear relationships
+- [`Storages`][flixOpt.components.Storage] - Stores energy or material over time
+- [`Sources`][flixOpt.components.Source] / [`Sinks`][flixOpt.components.Sink] / [`SourceAndSinks`][flixOpt.components.SourceAndSink] - Produce or consume flows. They are usually used to model external demands or supplies.
+- [`Transmissions`][flixOpt.components.Transmission] - Moves flows between locations with possible losses
+- Specialized [`LinearConverters`][flixOpt.components.LinearConverter] like [`Boilers`][flixOpt.linear_converters.Boiler], [`HeatPumps`][flixOpt.linear_converters.HeatPump], [`CHPs`][flixOpt.linear_converters.CHP], etc. These simplify the usage of the `LinearConverter` class and can also be used as blueprint on how to define custom classes or parameterize existing ones.
+
+### Effects
+
+[`Effect`][flixOpt.effects.Effect] objects represent impacts or metrics related to your system, such as:
+
+- Costs (investment, operation)
+- Emissions (CO₂, NOx, etc.)
+- Resource consumption
+
+These can be freely defined and crosslink to each other (`CO₂` ──[specific CO₂-costs]─→ `Costs`).
+One effect is designated as the **optimization objective** (typically Costs), while others can have constraints.
+This effect can incorporate several other effects, which woul result in a weighted objective from multiple effects.
+
+### Calculation Modes
+
+flixOpt offers different calculation approaches:
+
+- [`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
+
+## How These Concepts Work Together
+
+1. You create a `FlowSystem` with a specified time series
+2. You add elements to the FLowSystem:
+    - `Bus` objects as connection points
+    - `Component` objects like Boilers, Storages, etc.. They include `Flow` which define the connection to a Bus.
+    - `Effect` objects to represent costs, emissions, etc.
+3.You choose a calculation mode and solver
+4.flixOpt converts your model into a mathematical optimization problem
+5.The solver finds the optimal solution
+6.You analyze the results with built-in or external tools
+
+## Advanced Usage
+flixOpt uses [linopy](https://github.com/PyPSA/linopy) to model the mathematical optimization problem.
+Any model created with flixOpt can be extended or modified using the great [linopy API](https://linopy.readthedocs.io/en/latest/api.html).
+This allows to adjust your model to very specific requirements without loosing the convenience of flixOpt.
+
+
+
+## Architechture (outdated)
+![Architecture](../images/architecture_flixOpt.png)
+
+
+<!--## Next Steps-->
+<!---->
+<!--Now that you understand the basic concepts, learn more about each one:-->
+<!---->
+<!--- [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-->

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/getting-started.md

@@ -0,0 +1,42 @@
+# Getting Started with flixOpt
+
+This guide will help you install flixOpt, understand its basic concepts, and run your first optimization model.
+
+## Installation
+
+### Basic Installation
+
+Install flixOpt directly into your environment using pip:
+
+```bash
+pip install git+https://github.com/flixOpt/flixOpt.git
+```
+
+This provides the core functionality with the HiGHS solver included.
+
+### Full Installation
+
+For all features including interactive network visualizations and time series aggregation:
+
+```bash
+pip install "flixOpt[full] @ git+https://github.com/flixOpt/flixOpt.git"
+```
+
+## Basic Workflow
+
+Working with flixOpt follows a general pattern:
+
+1. **Create a [`FlowSystem`][flixOpt.flow_system.FlowSystem]** with a time series
+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
+6. **Analyze [`Results`][flixOpt.results]** using built-in or external visualization tools
+
+## Next Steps
+
+Now that you've installed flixOpt and understand the basic workflow, you can:
+
+- Learn about the [core concepts of flixOpt](concepts-and-math/index.md)
+- Explore some [examples](examples/index.md)
+- Check the [API reference](api-reference/index.md) for detailed documentation