source/AID2E-framework/README.md

0001 # AID2E Framework
0002
0003 [![Tests](https://github.com/aid2e/AID2E-framework/actions/workflows/tests.yml/badge.svg?branch=main)](https://github.com/aid2e/AID2E-framework/actions/workflows/tests.yml)
0004 [![Documentation](https://github.com/aid2e/AID2E-framework/actions/workflows/docs-deploy.yml/badge.svg?branch=main)](https://aid2e.github.io/AID2E-framework)
0005
0006 AI assisted Detector Design for EIC (AID2E) is a Python toolkit for authoring and validating detector design optimization workflows. It provides typed configuration models, a Click-based CLI, scheduler/optimizer hooks, and ePIC-specific utilities. Docs: https://aid2e.github.io/AID2E-framework
0007
0008 ## Repository Layout
0009
0010 - `src/aid2e/` main package (CLI at `aid2e.cli`, optimizers, schedulers, utilities)
0011 - `tests/` mirrored test suite, including fixtures for DTLZ2 and ePIC configs
0012 - `docs/` MkDocs site sources (published to GitHub Pages)
0013 - `scripts/` helper scripts for docs build/deploy
0014 - `packages/` legacy package splits (kept for reference; primary code now lives under `src/`)
0015
0016 ## Quickstart
0017
0018 ```bash
0019 python -m venv .venv
0020 source .venv/bin/activate
0021 pip install -e .
0022
0023 # Run tests
0024 pytest -v
0025
0026 # Try the CLI
0027 aid2e --help
0028 aid2e version
0029 ```
0030
0031 ## Using Configuration Loaders
0032
0033 - Load a problem + design config:
0034
0035 ```python
0036 from aid2e.utilities.configurations import load_config
0037
0038 cfg = load_config("path/to/problem.config")
0039 print(cfg.problem.design_config.get_parameter_names())
0040 ```
0041
0042 - Example fixtures live in `tests/test_utilities/fixtures/dtlz2/` (`design.params`, `problem.config`).
0043
0044 ## Developing
0045
0046 - Lint/format/type: `black .`, `flake8`, `mypy` (install extras with `pip install -e ".[dev]"`)
0047 - Docs: `pip install -e ".[docs]" && ./scripts/docs-serve.sh`
0048 - Tests: `pytest -v`
0049
0050 ## Documentation
0051
0052 MkDocs site sources are under `docs/` (Material theme). The navigation is defined in `mkdocs.yml`; API reference is generated via `mkdocstrings`.
0053
0054 ## Contributing
0055
0056 - Prefer adding tests alongside changes.
0057 - Keep imports under the `aid2e` namespace (`aid2e.cli`, `aid2e.utilities.configurations`, etc.).
0058 - Update docs and fixtures when changing configuration schemas.