Feature/docs2 (#207)

FBumann · web-flow · commit c9ed88674ff8 · 2025-03-29T17:37:18.000+01:00
* Improve docs
diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md
@@ -1,7 +1,7 @@
 - [Home](index.md)
 - [Getting Started](getting-started.md)
-- [Concepts & Math](concepts-and-math/)
+- [User Guide](user-guide/)
 - [Examples](examples/)
+- [FAQ](faq/)
 - [API-Reference](api-reference/)
-- [Release Notes](release-notes/)
-- [Contribute](contribute.md)
+- [Release Notes](release-notes/)
diff --git a/docs/examples/index.md b/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!
diff --git a/docs/faq/contribute.md b/docs/faq/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*
diff --git a/docs/faq/index.md b/docs/faq/index.md
@@ -0,0 +1,3 @@
+# Frequently Asked Questions
+
+## Work in progress
diff --git a/docs/getting-started.md b/docs/getting-started.md
@@ -37,6 +37,6 @@ Working with flixOpt follows a general pattern:
 
 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)
+- Learn about the [core concepts of flixOpt](user-guide/index.md)
 - Explore some [examples](examples/)
 - Check the [API reference](api-reference/index.md) for detailed documentation
diff --git a/docs/index.md b/docs/index.md
@@ -1,37 +1,47 @@
-# flixOpt: Energy and Material Flow Optimization Framework
+# FlixOpt
 
-**flixOpt** is a Python-based optimization framework designed to tackle energy and material flow problems using mixed-integer linear programming (MILP).
+**FlixOpt** is a Python-based optimization framework designed to tackle energy and material flow problems using mixed-integer linear programming (MILP).
 
-It 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.
+It borrows concepts from both [FINE](https://github.com/FZJ-IEK3-VSA/FINE) and [oemof.solph](https://github.com/oemof/oemof-solph).
+
+## Why FlixOpt?
+
+FlixOpt is designed as a general-purpose optimization framework to get your model running quickly, without sacrificing flexibility down the road:
+
+- **Easy to Use API**: FlixOpt provides a Pythonic, object-oriented interface that makes mathematical optimization more accessible to Python developers.
+
+- **Approachable Learning Curve**: Designed to be accessible from the start, with options for more detailed models down the road.
+
+- **Domain Independence**: While frameworks like oemof and FINE excel at energy system modeling with domain-specific components, FlixOpt offers a more general mathematical approach that can be applied across different fields.
+
+- **Extensibility**: Easily add custom constraints or variables to any FlixOpt Model using [linopy](https://github.com/PyPSA/linopy). Tailor any FlixOpt model to your specific needs without loosing the convenience of the framework.
+
+- **Solver Agnostic**: Work with different solvers through a consistent interface.
+
+- **Results File I/O**: Built to analyze results independent of running the optimization.
 
 <figure markdown>
   ![flixOpt Conceptual Usage](./images/architecture_flixOpt.png)
   <figcaption>Conceptual Usage and IO operations of flixOpt</figcaption>
 </figure>
 
-## 🚀️ Getting Started
-
-See the [Getting Started Guide](getting-started.md) to start using flixOpt.
+## Installation
 
-See the [Examples](examples/) section for detailed examples.
+```bash
+pip install flixopt
+```
 
-## ⚙️ How It Works
+For more detailed installation options, see the [Getting Started](getting-started.md) guide.
 
-See our [Concepts & Math](concepts-and-math/index.md) to understand the core concepts of flixOpt.
+## License
 
-## 🛠️ Compatible Solvers
+FlixOpt is released under the MIT License. See [LICENSE](https://github.com/flixopt/flixopt/blob/main/LICENSE) for details.
 
-flixOpt works with various solvers:
+## Citation
 
-- [HiGHS](https://highs.dev/) (installed by default)
-- [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)
-
-## 📝 Citation
-
-If you use flixOpt in your research or project, please cite:
+If you use FlixOpt in your research or project, please cite:
 
 - **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)
+
+*A more sophisticated paper is in progress*
diff --git a/docs/user-guide/Mathematical Notation/Bus.md b/docs/user-guide/Mathematical Notation/Bus.md
diff --git a/docs/user-guide/Mathematical Notation/Effects, Penalty & Objective.md b/docs/user-guide/Mathematical Notation/Effects, Penalty & Objective.md
diff --git a/docs/user-guide/Mathematical Notation/Flow.md b/docs/user-guide/Mathematical Notation/Flow.md
@@ -1,4 +1,4 @@
-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}.
+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})
diff --git a/docs/user-guide/Mathematical Notation/LinearConverter.md b/docs/user-guide/Mathematical Notation/LinearConverter.md
@@ -18,4 +18,4 @@ $$
 
 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.
+The conversion efficiency can be defined as a piecewise linear approximation. See [Piecewise](Piecewise.md) for more details.
diff --git a/docs/user-guide/Mathematical Notation/Piecewise.md b/docs/user-guide/Mathematical Notation/Piecewise.md
@@ -0,0 +1,49 @@
+# Piecewise
+
+A Piecewise is a collection of [`Pieces`][flixOpt.interface.Piece], which each define a valid range for a variable $v$
+
+$$ \label{eq:active_piece}
+    \beta_\text{k} = \lambda_\text{0, k} + \lambda_\text{1, k}
+$$
+
+$$ \label{eq:piece}
+    v_\text{k} = \lambda_\text{0, k} * \text{v}_{\text{start,k}} + \lambda_\text{1,k} * \text{v}_{\text{end,k}}
+$$
+
+$$ \label{eq:piecewise_in_pieces}
+\sum_{k=1}^k \beta_{k} = 1
+$$
+
+With:
+
+- $v$: The variable to be defined by the Piecewise
+- $\text{v}_{\text{start,k}}$: the start point of the piece for variable $v$
+- $\text{v}_{\text{end,k}}$: the end point of the piece for variable $v$
+- $\beta_\text{k} \in \{0, 1\}$: defining wether the Piece $k$ is active
+- $\lambda_\text{0,k} \in [0, 1]$: A variable defining the fraction of $\text{v}_{\text{start,k}}$ that is active
+- $\lambda_\text{1,k} \in [0, 1]$: A variable defining the fraction of $\text{v}_{\text{end,k}}$ that is active
+
+Which can also be described as $v \in 0 \cup [\text{v}_\text{start}, \text{v}_\text{end}]$.
+
+Instead of \eqref{eq:piecewise_in_pieces}, the following constraint is used to also allow all variables to be zero:
+
+$$ \label{eq:piecewise_in_pieces_zero}
+\sum_{k=1}^k \beta_{k} = \beta_\text{zero}
+$$
+
+With:
+
+- $\beta_\text{zero} \in \{0, 1\}$.
+
+Which can also be described as $v \in \{0\} \cup [\text{v}_{\text{start_k}}, \text{v}_{\text{end_k}}]$
+
+
+## Combining multiple Piecewises
+
+Piecewise allows representing non-linear relationships. 
+This is a powerful technique in linear optimization to model non-linear behaviors while maintaining the problem's linearity.
+
+Therefore, each Piecewise must have the same number of Pieces $k$.
+
+The variables described in [Piecewise](#piecewise) are created for each Piece, but nor for each Piecewise.
+Rather, \eqref{eq:piece} is the only constraint that is created for each Piecewise, using the start and endpoints $\text{v}_{\text{start,k}}$ and $\text{v}_{\text{end,k}}$ of each Piece for the corresponding variable $v$
diff --git a/docs/user-guide/Mathematical Notation/Storage.md b/docs/user-guide/Mathematical Notation/Storage.md
diff --git a/docs/user-guide/Mathematical Notation/index.md b/docs/user-guide/Mathematical Notation/index.md
diff --git a/docs/user-guide/Mathematical Notation/others.md b/docs/user-guide/Mathematical Notation/others.md
diff --git a/docs/user-guide/index.md b/docs/user-guide/index.md
@@ -17,12 +17,24 @@ Every flixOpt model starts with creating a FlowSystem. It:
 
 [`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 a `size` which, generally speaking, defines how fast energy or material can be moved. Usually measured in MW, kW, m³/h, etc.
+- Have a `flow_rate`, which is defines how fast energy or material is transported. Usually measured in MW, kW, m³/h, etc.
 - 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, ...)
 
+#### Flow Hours
+While the **Flow Rate** defines the rate in which energy or material is transported, the **Flow Hours** define the amount of energy or material that is transported.
+Its defined by the flow_rate times the duration of the timestep in hours.
+
+Examples:
+
+| Flow Rate | Timestep | Flow Hours |
+|-----------|----------|------------|
+| 10 (MW)   | 1 hour   | 10 (MWh)   |
+| 10 (MW)   | 6 minutes | 0.1 (MWh) |
+| 10 (kg/h) | 1 hour   | 10 (kg)    |
+
 ### Buses
 
 [`Bus`][flixOpt.elements.Bus] objects represent nodes or connection points in a FlowSystem. They:

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+# Frequently Asked Questions`
	`2`	`+`
	`3`	`+## Work in progress`
Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-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}.`
	`1`	`+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}.`
`2`	`2`
`3`	`3`	`$$ \label{eq:flow_rate}`
`4`	`4`	`\text P \cdot \text p^{\text{L}}_{\text{rel}}(\text{t}_{i})`