Repository Guidelines

Project Structure & Module Organization

Root scripts:
- ```
process_data.py
```
  (MAT → NPZ)
- ```
analyze_data.py
```
  (stats + plots)
- ```
train_koopman.py
```
  (Koopman model training; TensorBoard logging)
- ```
test_data.py
```
  (unittest)

Data:

AscTec_Pelican_Flight_Dataset.mat

(raw),

pelican_dataset.npz

(processed).

Assets:
- ```
plots/
```
  (generated histograms, safe to delete/regenerate)
- ```
runs/
```
  (TensorBoard logs, safe to delete/regenerate)

Build, Test, and Development Commands

Create env (recommended):

python -m venv .venv && source .venv/bin/activate

Install deps:
```
pip install numpy scipy matplotlib
```
.
Optional training deps:
```
pip install tensorboard tensorboardX torch
```
(pick a CUDA build that matches your driver if using GPU).

Process raw data:

python process_data.py

(creates

pelican_dataset.npz

Analyze dataset:
```
python analyze_data.py
```
(prints stats, writes PNGs to
```
plots/
```
).

Train Koopman model (CPU default):

python train_koopman.py --tb-logdir runs --run-name demo

Short demo:

python train_koopman.py --short-run --subset-size 4096 --max-train-steps 50 --max-val-steps 20 --scale-steps 100 --epochs 1 --log-every 1

GPU:

python train_koopman.py --device cuda --gpu-id 0

View logs in TensorBoard:
```
tensorboard --logdir runs
```

Run tests:

python -m unittest -v

python test_data.py -v

Coding Style & Naming Conventions

Python 3.9+; follow PEP 8 with 4‑space indentation.
Names: modules/files
```
snake_case.py
```
; functions/variables
```
snake_case
```
; classes
```
CapWords
```
.
Docstrings: concise, triple‑quoted; include Args/Returns where helpful.
I/O paths: prefer relative paths from repo root; avoid hard‑coded user paths.

Testing Guidelines

Framework:
```
unittest
```
(stdlib). Add tests as
```
test_*.py
```
at repo root or a
```
tests/
```
folder.
Coverage: include edge cases for missing files, malformed data, and shape checks.
Repro: ensure
```
process_data.py
```
runs before tests; fail fast with clear messages.

Commit & Pull Request Guidelines

Commits: imperative mood, concise scope. Example:
```
process: transpose matrices in parser
```
.
Group related changes; avoid mixing data files with code changes.
PRs: include description, rationale, and before/after notes. Attach sample output (stats snippet or plot screenshot) when relevant. Link issues and list manual test steps.

Security & Configuration Tips

Large files: avoid committing regenerated
```
pelican_dataset.npz
```
and
```
plots/*.png
```
when unnecessary; consider adding them to
```
.gitignore
```
for local workflows.
Logs:
```
runs/
```
(TensorBoard) and any
```
wandb/
```
directories are local artifacts and should not be committed.
Determinism: document library versions in your PR if outputs change (e.g., NumPy/Matplotlib).
Data handling: do not upload proprietary datasets; this repo expects local availability of the
```
.mat
```
file.

Orientation Conventions

Euler:
```
Euler
```
uses roll, pitch, yaw in radians, ordered
```
[roll, pitch, yaw]
```
.
Quaternion: transition dataset exports
```
[w, x, y, z]
```
(unit-norm) when using quaternions.

Option:

PelicanTransitionDataset(..., orientation="euler")

returns Euler instead of quaternion; state size becomes 12D

[pos(3), euler(3), vel(3), pqr(3)]

Training CLI Reference (TensorBoard logging)

Core flags:

```
--device {cpu|cuda}
```
and
```
--gpu-id N
```

--batch-size

--latent-dim

--lr

--weight-decay

--epochs

--log-every

```
--orientation {quat|euler}
```

Short-run helpers:

--short-run

--subset-size

--max-train-steps

--max-val-steps

--scale-steps

Eval verbosity:

--eval-progress-every N

--eval-log-every N

TensorBoard:

--tb-logdir runs

--run-name NAME

--tb-flush-every N

Project Structure & Module Organization

Root scripts:

```
process_data.py
```
(MAT → NPZ)
```
analyze_data.py
```
(stats + plots)
```
train_koopman.py
```
(Koopman model training; TensorBoard logging)
```
test_data.py
```
(unittest)

Data:

AscTec_Pelican_Flight_Dataset.mat

(raw),

pelican_dataset.npz

(processed).

Assets:

```
plots/
```
(generated histograms, safe to delete/regenerate)
```
runs/
```
(TensorBoard logs, safe to delete/regenerate)

Build, Test, and Development Commands

Create env (recommended):

python -m venv .venv && source .venv/bin/activate

Install deps:

pip install numpy scipy matplotlib

Optional training deps:

pip install tensorboard tensorboardX torch

(pick a CUDA build that matches your driver if using GPU).

Process raw data:

python process_data.py

(creates

pelican_dataset.npz

Analyze dataset:

python analyze_data.py

(prints stats, writes PNGs to

plots/

Train Koopman model (CPU default):

python train_koopman.py --tb-logdir runs --run-name demo

Short demo:

python train_koopman.py --short-run --subset-size 4096 --max-train-steps 50 --max-val-steps 20 --scale-steps 100 --epochs 1 --log-every 1

GPU:

python train_koopman.py --device cuda --gpu-id 0

View logs in TensorBoard:

tensorboard --logdir runs

Run tests:

python -m unittest -v

python test_data.py -v

Commit & Pull Request Guidelines

Commits: imperative mood, concise scope. Example:

process: transpose matrices in parser

Group related changes; avoid mixing data files with code changes.

PRs: include description, rationale, and before/after notes. Attach sample output (stats snippet or plot screenshot) when relevant. Link issues and list manual test steps.

Security & Configuration Tips

Large files: avoid committing regenerated

pelican_dataset.npz

and

plots/*.png

when unnecessary; consider adding them to

.gitignore

for local workflows.

Logs:

runs/

(TensorBoard) and any

wandb/

directories are local artifacts and should not be committed.

Determinism: document library versions in your PR if outputs change (e.g., NumPy/Matplotlib).

Data handling: do not upload proprietary datasets; this repo expects local availability of the

.mat

file.

Orientation Conventions

Euler:

Euler

uses roll, pitch, yaw in radians, ordered

[roll, pitch, yaw]

Quaternion: transition dataset exports

[w, x, y, z]

(unit-norm) when using quaternions.

Option:

PelicanTransitionDataset(..., orientation="euler")

returns Euler instead of quaternion; state size becomes 12D

[pos(3), euler(3), vel(3), pqr(3)]

Training CLI Reference (TensorBoard logging)

Core flags:

```
--device {cpu|cuda}
```
and
```
--gpu-id N
```

--batch-size

--latent-dim

--lr

--weight-decay

--epochs

--log-every

```
--orientation {quat|euler}
```

Short-run helpers:

--short-run

--subset-size

--max-train-steps

--max-val-steps

--scale-steps

Eval verbosity:

--eval-progress-every N

--eval-log-every N

TensorBoard:

--tb-logdir runs

--run-name NAME

--tb-flush-every N

Repository Guidelines

Repository Guidelines

Project Structure & Module Organization

Build, Test, and Development Commands

Coding Style & Naming Conventions

Testing Guidelines

Commit & Pull Request Guidelines

Security & Configuration Tips

Orientation Conventions

Training CLI Reference (TensorBoard logging)

Related Skills

Nano Banana Pro

Markdown Converter

1password

Repository Guidelines

Project Structure & Module Organization

Build, Test, and Development Commands

Coding Style & Naming Conventions

Testing Guidelines

Commit & Pull Request Guidelines

Security & Configuration Tips

Orientation Conventions

Training CLI Reference (TensorBoard logging)