Skip to content

Contributing

Fed-MaxFuse is research software written for an MSc thesis at TU Delft. Contributions, questions, and reuse are welcome within that context.

Getting set up

git clone https://github.com/kbaran1998/fed-maxfuse.git
cd fed-maxfuse/fed-maxfuse
uv sync --group dev
uv run pytest

If the test suite passes, your environment is correct.

Development workflow

  1. Branch from main.
  2. Write a test first where practical, especially for numerical changes.
  3. Implement.
  4. Run the checks (all four): bash uv run ruff format src tests uv run ruff check src tests uv run mypy src uv run pytest -n auto
  5. Open a pull request describing what changed and, for numerical changes, what you verified.

Code conventions

Aspect Convention
Formatting ruff format (line length per pyproject.toml)
Imports isort ordering, enforced by ruff
Docstrings Required on public functions; pydocstyle rules active
Types Annotate public APIs; mypy must pass
Complexity mccabe limits configured — prefer decomposition over long functions

Adding a new execution mode

The model variants follow a consistent shape. To add one:

  1. Create src/fed_maxfuse/models/<your_mode>/.
  2. Add model.py, parameters.py, train.py (plus server_functions.py if it has a server side).
  3. Add a value to MaxFuseRunType in src/shared/_types/enums/.
  4. Provide a default_<mode>_<dataset>_params.json.
  5. Wire it into src/cli/run/commands.py.
  6. Add parameter-parsing tests, following test_federated_params.py.

Do not branch inside an existing model to add a mode; the sibling-directory pattern is what keeps the variants independently testable.

Adding a metric

  1. Implement under evaluation/metrics/supervised/ or .../unsupervised/.
  2. If it comes from ZADU, add its abbreviation to ZaduAbbreviationEnum.
  3. Add tests covering the metric's known bounds and edge cases.
  4. Document it in Metrics, including which direction is better, which is the single most useful thing to record.

Numerical changes need evidence

This is a research codebase; changes that affect results carry a higher bar.

  • State which metrics you checked and on which dataset.
  • Remember that MaxFuse is stochastic: a single run proves nothing. Use repetitions, and compare distributions rather than point values.
  • If you change a default, say so explicitly in the PR. Silent default changes are how the upstream reference implementation ended up with a documented behaviour that differs from its actual behaviour.

Record what you compared against

When benchmarking against a reference implementation, note the exact version or commit. Two versions of "MaxFuse" can differ algorithmically while carrying the same version string.

Documentation

This site is built with MkDocs Material.

cd docs
mkdocs serve      # http://localhost:8000, live reload
mkdocs build      # static output

Conventions:

  • Maths uses MathJax via pymdownx.arithmatex: $...$ inline, $$...$$ display.
  • Admonitions (!!! note, !!! warning, !!! tip) are available.
  • Cross-page links use relative paths with the .md extension.
  • Add new pages to nav: in mkdocs.yml, or they will not appear.

Reporting issues

Use the issue tracker. For anything numerical, please include:

  • dataset ID and run type,
  • the configuration JSON,
  • expected versus observed metric values,
  • Python and package versions (uv pip freeze).

Contact

Krzysztof Baran — krysbaran@gmail.com