# Kindred Solver

Assembly constraint solver for [Kindred Create](https://git.kindred-systems.com/kindred/create). Combines a numerical multibody dynamics engine (OndselSolver) with a GNN-based constraint prediction layer.

## Components

### OndselSolver (C++)

Numerical assembly constraint solver using multibody dynamics. Solves joint constraints between rigid bodies using a Newton-Raphson iterative approach. Used by FreeCAD's Assembly workbench as the backend solver.

- Source: `OndselSolver/`
- Entry point: `OndselSolverMain/`
- Tests: `tests/`, `testapp/`
- Build: CMake

**Theory:** [MbDTheory](https://github.com/Ondsel-Development/MbDTheory)

#### Building

```bash
cmake -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build
```

### ML Solver Layer (Python)

Graph neural network that predicts constraint independence and per-body degrees of freedom. Trained on synthetic assembly data generated via the pebble game algorithm, with the goal of augmenting or replacing the numerical solver for common assembly patterns.

- Core library: `solver/`
- Data generation: `solver/datagen/` (pebble game, synthetic assemblies, labeling)
- Model architectures: `solver/models/` (GIN, GAT, NNConv)
- Training: `solver/training/`
- Inference: `solver/inference/`
- FreeCAD integration: `freecad/`
- Configuration: `configs/` (Hydra)

#### Setup

```bash
pip install -e ".[train,dev]"
pre-commit install
```

#### Usage

```bash
make help          # show all targets
make dev           # install all deps + pre-commit hooks
make test          # run tests
make lint          # run ruff linter
make check         # lint + type-check + test
make data-gen      # generate synthetic data
make train         # run training
make export        # export model
```

Docker is also supported:

```bash
docker compose up train       # GPU training
docker compose up test        # run tests
docker compose up data-gen    # generate synthetic data
```

## Repository structure

```
kindred-solver/
├── OndselSolver/       # C++ numerical solver library
├── OndselSolverMain/   # C++ solver CLI entry point
├── tests/              # C++ unit tests + Python tests
├── testapp/            # C++ test application
├── solver/             # Python ML solver library
│   ├── datagen/        # Synthetic data generation (pebble game)
│   ├── datasets/       # PyG dataset adapters
│   ├── models/         # GNN architectures
│   ├── training/       # Training loops
│   ├── evaluation/     # Metrics and visualization
│   └── inference/      # Runtime prediction API
├── freecad/            # FreeCAD workbench integration
├── configs/            # Hydra configs (dataset, model, training, export)
├── scripts/            # CLI utilities
├── data/               # Datasets (not committed)
├── export/             # Model packaging
└── docs/               # Documentation
```

## License

OndselSolver: LGPL-2.1-or-later (see [LICENSE](LICENSE))
ML Solver Layer: Apache-2.0