From 9626cc00b4cc47bd79edbfd393951860eeeeecf1 Mon Sep 17 00:00:00 2001 From: FBumann <117816358+FBumann@users.noreply.github.com> Date: Wed, 29 Oct 2025 20:59:49 +0100 Subject: [PATCH 1/7] Improve docs --- docs/user-guide/index.md | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) diff --git a/docs/user-guide/index.md b/docs/user-guide/index.md index df97bf768..96b1f713f 100644 --- a/docs/user-guide/index.md +++ b/docs/user-guide/index.md @@ -114,19 +114,20 @@ This [`CalculationResults`][flixopt.results.CalculationResults] object can be sa The process of working with FlixOpt can be divided into 3 steps: 1. Create a [`FlowSystem`][flixopt.flow_system.FlowSystem], containing all the elements and data of your system - - Define the time series of your system - - Add [`Components`][flixopt.components] like [`Boilers`][flixopt.linear_converters.Boiler], [`HeatPumps`][flixopt.linear_converters.HeatPump], [`CHPs`][flixopt.linear_converters.CHP], etc. - - Add [`Buses`][flixopt.elements.Bus] as connection points in your system + - Define the time horizon of your system (and optionally your periods and scenarios, see [Dimensions](mathematical-notation/dimensions.md))) - Add [`Effects`][flixopt.effects.Effect] to represent costs, emissions, etc. - - *This [`FlowSystem`][flixopt.flow_system.FlowSystem] can also be loaded from a netCDF file* + - Add [`Buses`][flixopt.elements.Bus] as connection points in your systeand [`Sinks`][flixopt.components.Sink] & [`Sources`][flixopt.components.Source] as connections to the outer world (markets, power grid, ...) + - Add [`Components`][flixopt.components] like [`Boilers`][flixopt.linear_converters.Boiler], [`HeatPumps`][flixopt.linear_converters.HeatPump], [`CHPs`][flixopt.linear_converters.CHP], etc. + - 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 internaly to a mathematical optimization problem... + - ...The Calculation 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 - - As it contains the used [`FlowSystem`][flixopt.flow_system.FlowSystem], it can be used to start a new calculation + - As it contains the used [`FlowSystem`][flixopt.flow_system.FlowSystem], it fully documents all assumptions taken to create the results.
![FlixOpt Conceptual Usage](../images/architecture_flixOpt.png) From 2427e6dc8bd4936940c4efa75d919c9b9db7e122 Mon Sep 17 00:00:00 2001 From: FBumann <117816358+FBumann@users.noreply.github.com> Date: Wed, 29 Oct 2025 21:09:30 +0100 Subject: [PATCH 2/7] Improve docs --- docs/user-guide/{index.md => core-concepts.md} | 2 +- mkdocs.yml | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) rename docs/user-guide/{index.md => core-concepts.md} (99%) diff --git a/docs/user-guide/index.md b/docs/user-guide/core-concepts.md similarity index 99% rename from docs/user-guide/index.md rename to docs/user-guide/core-concepts.md index 96b1f713f..83adbdab1 100644 --- a/docs/user-guide/index.md +++ b/docs/user-guide/core-concepts.md @@ -1,4 +1,4 @@ -# FlixOpt Concepts +# Core Concepts of flixopt FlixOpt is built around a set of core concepts that work together to represent and optimize **any system involving flows and conversions** - whether that's energy systems, material flows, supply chains, water networks, or production processes. diff --git a/mkdocs.yml b/mkdocs.yml index cc108e237..7d3490360 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -11,9 +11,9 @@ repo_name: flixOpt/flixopt nav: - Home: index.md - User Guide: - - user-guide/index.md - - Migration to v3.0.0: user-guide/migration-guide-v3.md - Getting Started: getting-started.md + - Core Concepts: user-guide/core-concepts.md + - Migration to v3.0.0: user-guide/migration-guide-v3.md - Mathematical Notation: - Overview: user-guide/mathematical-notation/index.md - Dimensions: user-guide/mathematical-notation/dimensions.md From bf9fa0a789eb9d2a88e2bfde7d695690550dfa20 Mon Sep 17 00:00:00 2001 From: FBumann <117816358+FBumann@users.noreply.github.com> Date: Wed, 29 Oct 2025 21:16:17 +0100 Subject: [PATCH 3/7] Improve docs and fix links --- docs/getting-started.md | 2 +- docs/index.md | 4 ++-- docs/user-guide/core-concepts.md | 4 ++-- docs/user-guide/mathematical-notation/index.md | 4 ++-- 4 files changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/getting-started.md b/docs/getting-started.md index 9af389755..044ffb872 100644 --- 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](user-guide/index.md) +- Learn about the [core concepts of flixopt](user-guide/core-concepts.md) - Explore some [examples](examples/index.md) - Check the [API reference](api-reference/index.md) for detailed documentation diff --git a/docs/index.md b/docs/index.md index a7cd67f8c..c9b01f284 100644 --- a/docs/index.md +++ b/docs/index.md @@ -139,6 +139,6 @@ Help improve FlixOpt by contributing code, docs, or examples {% include-markdown "../README.md" - start="## Installation" - end="## License" + start="## 🛠️ Installation" + end="## 📄 License" %} diff --git a/docs/user-guide/core-concepts.md b/docs/user-guide/core-concepts.md index 83adbdab1..53aa23002 100644 --- a/docs/user-guide/core-concepts.md +++ b/docs/user-guide/core-concepts.md @@ -1,10 +1,10 @@ -# Core Concepts of flixopt +# Core concepts of flixopt FlixOpt is built around a set of core concepts that work together to represent and optimize **any system involving flows and conversions** - whether that's energy systems, material flows, supply chains, water networks, or production processes. This page provides a high-level overview of these concepts and how they interact. -## Core Concepts +## Main building blocks ### FlowSystem diff --git a/docs/user-guide/mathematical-notation/index.md b/docs/user-guide/mathematical-notation/index.md index 05d1fed60..27e7b7e9a 100644 --- a/docs/user-guide/mathematical-notation/index.md +++ b/docs/user-guide/mathematical-notation/index.md @@ -1,9 +1,9 @@ # Mathematical Notation -This section provides the **mathematical formulations** underlying FlixOpt's optimization models. It is intended as **reference documentation** for users who want to understand the mathematical details behind the high-level FlixOpt API described in the [FlixOpt Concepts](../index.md) guide. +This section provides the **mathematical formulations** underlying FlixOpt's optimization models. It is intended as **reference documentation** for users who want to understand the mathematical details behind the high-level FlixOpt API described in the [FlixOpt Concepts](../core-concepts.md) guide. -**For typical usage**, refer to the [FlixOpt Concepts](../index.md) guide, [Examples](../../examples/index.md), and [API Reference](../../api-reference/index.md) - you don't need to understand these mathematical formulations to use FlixOpt effectively. +**For typical usage**, refer to the [FlixOpt Concepts](../core-concepts.md) guide, [Examples](../../examples/index.md), and [API Reference](../../api-reference/index.md) - you don't need to understand these mathematical formulations to use FlixOpt effectively. --- From 70fcea49904b977345d78bb7fe5a333cfe200379 Mon Sep 17 00:00:00 2001 From: FBumann <117816358+FBumann@users.noreply.github.com> Date: Wed, 29 Oct 2025 21:18:48 +0100 Subject: [PATCH 4/7] Update contribute.md --- docs/contribute.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/contribute.md b/docs/contribute.md index 44af34069..cdc9d58c0 100644 --- a/docs/contribute.md +++ b/docs/contribute.md @@ -4,7 +4,7 @@ We warmly welcome contributions from the community! This guide will help you get ## Development Setup 1. Clone the repository `git clone https://github.com/flixOpt/flixopt.git` -2. Install the development dependencies `pip install -e ".[dev]"` +2. Install the development dependencies `pip install -e ".[full, dev]"` 3. Install pre-commit hooks `pre-commit install` (one-time setup) 4. Run `pytest` to ensure your code passes all tests From 9d9be87c8118f7e723f2ecc0f7b353eed3c326b9 Mon Sep 17 00:00:00 2001 From: FBumann <117816358+FBumann@users.noreply.github.com> Date: Wed, 29 Oct 2025 22:17:32 +0100 Subject: [PATCH 5/7] Update contribute.md --- CONTRIBUTE.md | 44 ++++++++++++++++++++++++++++++++++++++++ docs/contribute.md | 46 +----------------------------------------- tests/run_all_tests.py | 10 --------- 3 files changed, 45 insertions(+), 55 deletions(-) create mode 100644 CONTRIBUTE.md delete mode 100644 tests/run_all_tests.py diff --git a/CONTRIBUTE.md b/CONTRIBUTE.md new file mode 100644 index 000000000..8ce652351 --- /dev/null +++ b/CONTRIBUTE.md @@ -0,0 +1,44 @@ +# 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 -e ".[full, dev]"` +3. Install pre-commit hooks `pre-commit install` (one-time setup) +4. Run `pytest` to ensure your code passes all tests + +## Code Quality +We use [Ruff](https://github.com/astral-sh/ruff) for linting and formatting. After the one-time setup above, **code quality checks run automatically on every commit**. + +To run manually: +- `ruff check --fix .` to check and fix linting issues +- `ruff format .` to format code or +- `pre-commit run` or `pre-commit run --all-files` to trigger all checks + +## Documentation (Optional) +FlixOpt uses [mkdocs](https://www.mkdocs.org/) to generate documentation. +To work on documentation: +```bash +pip install -e ".[docs]" +mkdocs serve +``` +Then navigate to http://127.0.0.1:8000/ + +## Testing +- `pytest` to run the test suite + +--- +# 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 & Releases +New features should be branched from `main` into `feature/*` +As stated, we follow **Semantic Versioning**. Releases are created manually from the `main` branch. diff --git a/docs/contribute.md b/docs/contribute.md index cdc9d58c0..e1b93aecb 100644 --- a/docs/contribute.md +++ b/docs/contribute.md @@ -1,45 +1 @@ -# 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 -e ".[full, dev]"` -3. Install pre-commit hooks `pre-commit install` (one-time setup) -4. Run `pytest` to ensure your code passes all tests - -## Code Quality -We use [Ruff](https://github.com/astral-sh/ruff) for linting and formatting. After the one-time setup above, **code quality checks run automatically on every commit**. - -To run manually: -- `ruff check --fix .` to check and fix linting issues -- `ruff format .` to format code or -- `pre-commit run` or `pre-commit run --all-files` to trigger all checks - -## Documentation (Optional) -FlixOpt uses [mkdocs](https://www.mkdocs.org/) to generate documentation. -To work on documentation: -```bash -pip install -e ".[docs]" -mkdocs serve -``` -Then navigate to http://127.0.0.1:8000/ - -## Testing -- `pytest` to run the test suite -- You can also run the provided python script `run_all_test.py` - ---- -# 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 & Releases -New features should be branched from `main` into `feature/*` -As stated, we follow **Semantic Versioning**. Releases are created manually from the `main` branch. +{! ../CONTRIBUTE.md !} diff --git a/tests/run_all_tests.py b/tests/run_all_tests.py deleted file mode 100644 index 83b6dfacf..000000000 --- a/tests/run_all_tests.py +++ /dev/null @@ -1,10 +0,0 @@ -""" -Run this script to run all tests with pytest -Alternatively, use 'python -m unittest discover -s tests' in the command line (using unittest) -or run testmodules individually -""" - -import pytest - -if __name__ == '__main__': - pytest.main(['test_integration.py', '--disable-warnings']) From 0859cc46c9744d28594703a1e74c183890ceb742 Mon Sep 17 00:00:00 2001 From: FBumann <117816358+FBumann@users.noreply.github.com> Date: Wed, 29 Oct 2025 22:20:03 +0100 Subject: [PATCH 6/7] Improve CONTRIBUTE.md --- CONTRIBUTE.md | 141 +++++++++++++++++++++++++++++++++++++++++--------- 1 file changed, 116 insertions(+), 25 deletions(-) diff --git a/CONTRIBUTE.md b/CONTRIBUTE.md index 8ce652351..5e4b7d7ee 100644 --- a/CONTRIBUTE.md +++ b/CONTRIBUTE.md @@ -1,23 +1,65 @@ -# Contributing to the Project +# Contributing to FlixOpt -We warmly welcome contributions from the community! This guide will help you get started with contributing to our project. +We warmly welcome contributions from the community! Whether you're fixing bugs, adding features, improving documentation, or sharing examples, your contributions are valuable. + +## Ways to Contribute + +### 🐛 Report Issues +Found a bug or have a feature request? Please [open an issue](https://github.com/flixOpt/flixopt/issues) on GitHub. + +When reporting issues, please include: +- A clear description of the problem +- Steps to reproduce the issue +- Expected vs. actual behavior +- Your environment (OS, Python version, FlixOpt version) +- Minimal code example if applicable + +### 💡 Share Examples +Help others learn FlixOpt by contributing examples: +- Real-world use cases +- Tutorial notebooks +- Integration examples with other tools +- Add them to the `examples/` directory + +### 📖 Improve Documentation +Documentation improvements are always welcome: +- Fix typos or clarify existing docs +- Add missing documentation +- Translate documentation +- Improve code comments + +### 🔧 Submit Code Contributions +Ready to contribute code? Great! See the sections below for setup and guidelines. + +--- ## Development Setup -1. Clone the repository `git clone https://github.com/flixOpt/flixopt.git` -2. Install the development dependencies `pip install -e ".[full, dev]"` -3. Install pre-commit hooks `pre-commit install` (one-time setup) -4. Run `pytest` to ensure your code passes all tests -## Code Quality -We use [Ruff](https://github.com/astral-sh/ruff) for linting and formatting. After the one-time setup above, **code quality checks run automatically on every commit**. +### Getting Started +1. Fork and clone the repository: + ```bash + git clone https://github.com/flixOpt/flixopt.git + cd flixopt + ``` -To run manually: -- `ruff check --fix .` to check and fix linting issues -- `ruff format .` to format code or -- `pre-commit run` or `pre-commit run --all-files` to trigger all checks +2. Install development dependencies: + ```bash + pip install -e ".[full, dev]" + ``` -## Documentation (Optional) +3. Set up pre-commit hooks (one-time setup): + ```bash + pre-commit install + ``` + +4. Verify your setup: + ```bash + pytest + ``` + +### Working with Documentation FlixOpt uses [mkdocs](https://www.mkdocs.org/) to generate documentation. + To work on documentation: ```bash pip install -e ".[docs]" @@ -25,20 +67,69 @@ mkdocs serve ``` Then navigate to http://127.0.0.1:8000/ -## Testing -- `pytest` to run the test suite - --- -# Best practices -## Coding Guidelines +## Code Quality Standards + +### Automated Checks +We use [Ruff](https://github.com/astral-sh/ruff) for linting and formatting. After the one-time setup above, **code quality checks run automatically on every commit**. + +### Manual Checks +To run checks manually: +- `ruff check --fix .` - Check and fix linting issues +- `ruff format .` - Format code +- `pre-commit run --all-files` - Run all pre-commit checks + +### Testing +- `pytest` - Run the test suite +- Ensure all tests pass before submitting a PR -- Follow PEP 8 style guidelines -- Write clear, commented code -- Include type hints +### Coding Guidelines +- Follow [PEP 8](https://pep8.org/) style guidelines +- Write clear, self-documenting code with helpful comments +- Include type hints for function signatures - Create or update tests for new functionality -- Ensure 100% test coverage for new code +- Aim for 100% test coverage for new code + +--- + +## Workflow + +### Branches & Pull Requests +1. Create a feature branch from `main`: + ```bash + git checkout -b feature/your-feature-name + ``` + +2. Make your changes and commit them with clear messages + +3. Push your branch and open a Pull Request + +4. Ensure all CI checks pass + +### Branch Naming +- Features: `feature/feature-name` +- Bug fixes: `fix/bug-description` +- Documentation: `docs/what-changed` + +### Commit Messages +- Use clear, descriptive commit messages +- Start with a verb (Add, Fix, Update, Remove, etc.) +- Keep the first line under 72 characters + +--- + +## Releases + +We follow **Semantic Versioning** (MAJOR.MINOR.PATCH). Releases are created manually from the `main` branch by maintainers. + +--- + +## Questions? + +If you have questions or need help, feel free to: +- Open a discussion on GitHub +- Ask in an issue +- Reach out to the maintainers -## Branches & Releases -New features should be branched from `main` into `feature/*` -As stated, we follow **Semantic Versioning**. Releases are created manually from the `main` branch. +Thank you for contributing to FlixOpt! From efe456f49657e9b7bd6d51e4e6360541fadd440d Mon Sep 17 00:00:00 2001 From: FBumann <117816358+FBumann@users.noreply.github.com> Date: Wed, 29 Oct 2025 22:25:27 +0100 Subject: [PATCH 7/7] Update CHANGELOG.md --- CHANGELOG.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index fec1a0d46..b46a82bc0 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -72,6 +72,8 @@ If upgrading from v2.x, see the [v3.0.0 release notes](https://github.com/flixOp ### 📦 Dependencies ### 📝 Docs +- Add more comprehensive `CONTRIBUTE.md` +- Improve logical structure in User Guide ### 👷 Development