Merge pull request #1 from Matdata-eu/002-train-path-calculation

002 train path calculation

Author: MathiasVDA

.github/agents/copilot-instructions.md

@@ -0,0 +1,29 @@
+# tp-lib Development Guidelines
+
+Auto-generated from all feature plans. Last updated: 2026-01-09
+
+## Active Technologies
+
+- Rust 1.75+ (edition 2021) (002-train-path-calculation)
+
+## Project Structure
+
+```text
+src/
+tests/
+```
+
+## Commands
+
+cargo test; cargo clippy
+
+## Code Style
+
+Rust 1.75+ (edition 2021): Follow standard conventions
+
+## Recent Changes
+
+- 002-train-path-calculation: Added Rust 1.75+ (edition 2021)
+
+<!-- MANUAL ADDITIONS START -->
+<!-- MANUAL ADDITIONS END -->

.github/workflows/ci.yml

@@ -68,17 +68,21 @@ jobs:
         uses: dtolnay/rust-toolchain@stable
 
       - name: Install maturin
-        run: pip install maturin pytest
-      
+        run: pip install maturin
+
+      - name: Create virtual environment
+        run: python -m venv .venv
+
       - name: Build Python package
         run: |
           cd tp-py
           maturin develop
-      
+
+      - name: Install test dependencies
+        run: .venv/bin/pip install pytest
+
       - name: Run Python tests
-        run: |
-          cd tp-py
-          pytest python/tests/
+        run: .venv/bin/pytest tp-py/python/tests/
 
   lint:
     name: Linting

.github/workflows/coverage.yml

@@ -0,0 +1,54 @@
+name: Coverage
+
+on:
+  push:
+    branches: [main, develop]
+  pull_request:
+    branches: [main]
+
+jobs:
+  coverage:
+    name: Generate Coverage Report
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install Rust toolchain
+        uses: actions-rust-lang/setup-rust-toolchain@v1
+        with:
+          toolchain: stable
+          components: llvm-tools-preview
+
+      - name: Install cargo-llvm-cov
+        uses: taiki-e/install-action@v2
+        with:
+          tool: cargo-llvm-cov
+
+      - name: Generate coverage report
+        run: |
+          cargo llvm-cov --lib -p tp-lib-core \
+            --lcov --output-path lcov.info
+
+      - name: Upload coverage to Codecov
+        uses: codecov/codecov-action@v4
+        if: github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name == github.repository
+        with:
+          files: lcov.info
+          token: ${{ secrets.CODECOV_TOKEN }}
+          fail_ci_if_error: true
+          flags: unittests
+          name: tp-lib-core-coverage
+
+      - name: Generate HTML report (for artifacts)
+        if: always()
+        run: |
+          cargo llvm-cov --lib -p tp-lib-core \
+            --html --output-dir coverage-report
+
+      - name: Upload HTML report as artifact
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: coverage-report
+          path: coverage-report/
+          retention-days: 30

.gitignore

@@ -64,4 +64,7 @@ htmlcov/
 # OS
 Thumbs.db
 
-.cargo
+.cargo
+test-data/best_position_geom_*.csv
+test-data/TP-Lib_attachments.zip
+test-data/TP-Lib.qgs

.vscode/settings.json

@@ -1,4 +1,5 @@
 {
+    "rust-analyzer.debug.engine": "ms-vscode.cpptools",
     "chat.promptFilesRecommendations": {
         "speckit.constitution": true,
         "speckit.specify": true,

CONTRIBUTING.md

@@ -272,6 +272,7 @@ tp-lib/
 │   ├── src/
 │   │   ├── models/        # Data models
 │   │   ├── projection/    # Projection algorithms
+│   │   ├── path/          # Train path calculation
 │   │   ├── io/            # Input/output parsers
 │   │   ├── crs/           # Coordinate transformations
 │   │   └── temporal/      # Timezone utilities
@@ -282,6 +283,87 @@ tp-lib/
     └── python/tests/      # Python tests
 ```
 
+## Train Path Calculation Development
+
+When working on path calculation features (`tp-core/src/path/`):
+
+### Architecture Overview
+
+The path calculation module consists of several submodules:
+
+- **`candidate.rs`**: Find candidate netelements for each GNSS position
+- **`probability.rs`**: Calculate HMM-related probabilities (e.g., emission/transition) using distance, heading, and network context
+- **`viterbi.rs`**: Run the HMM/Viterbi algorithm to compute the most likely train path from the candidate sequences
+- **`graph.rs`**: Network topology graph operations
+- **`spacing.rs`**: GNSS resampling for consistent spacing
+
+### Key Functions
+
+```rust
+// Main entry point
+calculate_train_path(gnss_positions, netelements, netrelations, config) -> PathResult
+
+// Project onto pre-calculated path
+project_onto_path(gnss_positions, path, netelements, config) -> Vec<ProjectedPosition>
+```
+
+### Algorithm Flow
+
+1. **Candidate Selection** (`find_candidate_netelements`)
+   - Uses R-tree spatial index for O(log n) lookup
+   - Filters by `cutoff_distance` and `max_candidates`
+
+2. **Probability Calculation** (`calculate_combined_probability`)
+   - Distance probability: `exp(-distance / distance_scale)`
+   - Heading probability: `exp(-heading_diff / heading_scale)`
+   - Combined: `distance_prob * heading_prob`
+
+3. **Path Construction** (`construct_forward_path`, `construct_backward_path`)
+   - Traverses network using netrelations (topology)
+   - Builds path in both directions for validation
+
+4. **Path Selection** (`select_best_path`)
+   - Validates bidirectional agreement
+   - Returns highest probability path
+
+### Testing Path Calculation
+
+```bash
+# Run path calculation tests
+cargo test --workspace path
+
+# Run integration tests
+cargo test --test tests path_calculation
+
+# Run benchmarks
+cargo bench --bench projection_bench
+cargo bench --bench naive_baseline_bench
+```
+
+### Creating coverage report
+
+```bash
+cargo llvm-cov --lib -p tp-lib-core --html --output-dir target/coverage
+```
+
+### Performance Targets
+
+- **SC-001**: 1000 positions × 50 netelements in <10 seconds
+- **Current**: ~900μs (11,000× faster than target)
+- **Memory**: <500MB for 10k+ positions
+
+### Configuration Parameters
+
+| Parameter | Default | Purpose |
+|-----------|---------|---------|
+| `distance_scale` | 10.0 | Distance decay rate (meters) |
+| `heading_scale` | 2.0 | Heading decay rate (degrees) |
+| `cutoff_distance` | 500.0 | Max search distance (meters) |
+| `heading_cutoff` | 10.0 | Max heading difference (degrees) |
+| `probability_threshold` | 0.02 | Min probability for inclusion |
+| `max_candidates` | 3 | Max candidates per position |
+| `resampling_distance` | None | Optional GNSS resampling |
+
 ## Constitution Principles
 
 TP-Lib follows strict architectural principles (see Constitution v1.1.0):

Cargo.toml

@@ -26,6 +26,9 @@ crs-definitions = "0.3.1"
 rstar = "0.12"
 geojson = "0.24"
 
+# Graph algorithms
+petgraph = "0.6"
+
 # Data processing
 arrow = "53.0"
 polars = "0.44"
@@ -52,3 +55,8 @@ pyo3 = { version = "0.21", features = ["extension-module"] }
 # Testing
 criterion = { version = "0.5", features = ["html_reports"] }
 quickcheck = "1.0"
+
+[profile.dev]
+debug = 2
+opt-level = 0
+split-debuginfo = "unpacked"