133 documentation getting started

[sarahleidolf]

Pull Request

Description

Add a getting started for MPC as tutorial.

Type of Change

• Bug fix (non-breaking change fixing an issue)
• New feature (non-breaking change adding functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• Refactoring (code change that neither fixes a bug nor adds a feature)
• Documentation update

Required Checklist

Testing

• Unit tests have been created/updated for new/modified functionality
• CI/CD pipeline passes all tests (pytest, pylint, coverage)

Examples

• Add examples for new features and functionality

Compatibility

• Changes are backward compatible OR deprecation warnings added
• No breaking changes to public APIs
• New dependencies added to pyproject.toml (required in dependencies or optional in [project.optional-dependencies])

OPTIONAL: Release Information

• Version number updated in agentlib_mpc/__init__.py (Required for PyPI release)
  • Version: ___.___.___
• CHANGELOG.md updated with description of changes (Required for PyPI release)

Documentation

• Docstrings added/updated for new/modified public methods (Google style)
• Type hints added for new functions/methods

Breaking Changes

Optional

GitHub Copilot Review

• Request Copilot review via GitHub UI (add 'copilot' as a reviewer)

---

Note: PRs will not be merged without completed required checklist items and passing CI/CD pipeline.

[Copilot]

🟡 Not ready to approve

The tutorial README’s stated sampling-key migration (t_sample_*) is inconsistent with the included simulator config, which can cause the tutorial to fail or confuse users.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

This review doesn't count toward merge requirements. Sign up for the private preview to control whether Copilot approvals count.

Pull request overview

Adds a new “Getting Started” tutorial under examples/getting-started/ to help users set up and run an MPC-driven multi-agent system in the AgentLib-MPC ecosystem.

Changes:

• Introduces a 3-part runnable tutorial (main_part1.py–main_part3.py) with corresponding MPC model/config examples.
• Adds a simple predictor module and configuration to provide forecast inputs to the MPC agent.
• Adds an overview README including notes about AgentLib sampling configuration changes.

Change Classification: Documentation update (with runnable example code)
Backward Compatibility: Compatible (examples/docs only)
CI Risk: Low–Medium (examples are new; one internal inconsistency may cause tutorial runtime failure depending on AgentLib version/config expectations)

File summaries

File	Description
examples/getting-started/README.md	Tutorial overview + AgentLib sampling configuration note
examples/getting-started/main_part1.py	Part 1 runner (FMU + predictor + MPC)
examples/getting-started/main_part2.py	Part 2 runner (objective-function examples)
examples/getting-started/main_part3.py	Part 3 runner (advanced solver/discretization config)
examples/getting-started/fmu/config.json	Simulator (FMU) agent configuration
examples/getting-started/predictor/simple_predictor.py	Predictor module producing a temperature forecast series
examples/getting-started/predictor/config.json	Predictor agent configuration
examples/getting-started/mpc/part1_simple_mpc_model.py	Part 1 CasADi model with simple objective definition
examples/getting-started/mpc/part1_config.json	Part 1 MPC agent configuration
examples/getting-started/mpc/part2_simple_mpc_model.py	Part 2 CasADi model demonstrating multiple objective types
examples/getting-started/mpc/part2_config.json	Part 2 MPC agent configuration
examples/getting-started/mpc/part3_simple_mpc_model.py	Part 3 CasADi model used with advanced settings
examples/getting-started/mpc/part3_config.py	Part 3 MPC configuration as a Python dict (solver/discretization options)

Review details

Comments suppressed due to low confidence (1)

examples/getting-started/README.md:37

• The JSON example uses tab characters for indentation; use spaces to keep formatting consistent and avoid rendering oddities in Markdown diffs.

{
	"t_sample_simulation": 60,
	"t_sample_communication": 60
}

• Files reviewed: 13/16 changed files
• Comments generated: 3
• Review effort level: Low

We're testing this review assessment. Please use 👍 or 👎 to tell us if it's correct.

[Copilot]

Pull request overview

Copilot reviewed 15 out of 17 changed files in this pull request and generated no new comments.

Suppressed comments (10)

examples/getting-started/README.md:32

• The Collocation snippet is currently an inline fenced block and the following “Further information…” line breaks the numbered-list nesting. Converting this to a proper fenced code block and indenting the follow-up bullets keeps the list formatting intact.

   - Collocation ```"discretization_options": {
                    "collocation_order": 2,
                    "collocation_method": "radau"
                }```

agentlib_mpc/utils/plotting/mpc.py:54

• prediction_step was inserted before convert_to in the plot_mpc signature, which breaks callers that pass convert_to positionally (the old 6th argument). To keep backward compatibility, move prediction_step after convert_to (or otherwise keep convert_to in the same positional slot).

    step: bool = False,
    prediction_step: int = 1,
    convert_to: Literal["seconds", "minutes", "hours", "days"] = "seconds",

agentlib_mpc/utils/plotting/mpc.py:92

• i % prediction_step will raise ZeroDivisionError if prediction_step is set to 0 (or negative). Add a small validation/guard so invalid values fail fast with a clear error.

        if plot_predictions and i % prediction_step == 0:

docs/source/tutorials/tutorial.md:10

• The docs link hard-codes a feature branch name (133-documentation-getting-started), which will become stale/broken after merge. Link to main (or use a relative link) so the docs remain valid.

You can also find a “getting started” guide in the examples in agentlib_mpc, which explain the first steps for creating an MPC:
https://github.com/RWTH-EBC/AgentLib-MPC/tree/133-documentation-getting-started/examples/getting-started

examples/getting-started/README.md:28

• The inline fenced code block for the Multiple Shooting example won’t render correctly inside the list item. Use a proper fenced code block on its own lines (and indent it under the bullet) so Markdown renders it as intended.

This issue also appears on line 29 of the same file.

   - Multiple Shooting ```"discretization_options": {
                    "method": "multiple_shooting"
                }```

examples/getting-started/predictor/simple_predictor.py:2

• Typo in the module docstring: “Its a manually written module” should be “It’s a manually written module”.

This is the predictor module. Its purpose is to provide random variables to the MPC agent. Its a manually written module and 

examples/getting-started/predictor/simple_predictor.py:3

• Wording in the module docstring is off: “referenced in the according config.json file” should be “referenced in the corresponding config.json file”.

is referenced in the according config.json file (here: examples/getting-started/predictor/config.json). There are three parameters

examples/getting-started/mpc/part1_simple_mpc_model.py:70

• This example module has several unused imports/variables (logging, matplotlib.pyplot, LocalMASAgency, and logger). If linting runs on examples/, these will fail CI; removing them keeps the tutorial code clean.

import logging
from typing import List
import matplotlib.pyplot as plt
from agentlib_mpc.models.casadi_model import (
    CasadiModel,

examples/getting-started/mpc/part2_simple_mpc_model.py:30

• This example module has several unused imports/variables (logging, matplotlib.pyplot, LocalMASAgency, and logger). If linting runs on examples/, these will fail CI; removing them keeps the tutorial code clean.

import logging
from typing import List
import matplotlib.pyplot as plt
from agentlib_mpc.models.casadi_model import (
    CasadiModel,

examples/getting-started/mpc/part3_simple_mpc_model.py:24

• This example module has several unused imports/variables (logging, matplotlib.pyplot, LocalMASAgency, and logger). If linting runs on examples/, these will fail CI; removing them keeps the tutorial code clean.

import logging
from typing import List
import matplotlib.pyplot as plt
from agentlib_mpc.models.casadi_model import (
    CasadiModel,