galata

Flight dynamics, control-law design and simulation — reproducibly, from a file you can read, with every number traceable to the routine that produced it.

galata is an offline engineering workbench. A YAML study can trim and linearise a local aircraft model, design continuous LQR state feedback, analyse the closed loop, simulate linear and nonlinear responses with explicit actuator limits, and write Markdown, HTML and CSV reports with a run manifest.

The analysis includes labelled aircraft modes, frequency response, gain, phase, delay and disk margins, and Hamiltonian H-infinity norm brackets for stable systems. Published-reference comparisons and numerical checks are recorded separately in the verification report.

It is usable for supervised, offline aviation and defence engineering studies within these limits. It is not a qualified tool, an onboard controller, or a validated model of an arbitrary aircraft. The operating guide explains the supported workflow and the checks a result still needs.

An experimental continuous block-model profile now supports headless compilation and simulation of scalar feedback diagrams. The working example records model identity and scoped run evidence. Desktop delivery is planned for macOS first, then Linux; see the M1 implementation record.

C++20 core, strict SI units, deterministic by policy, Apache-2.0.

CI Determinism

The NT-33A pole map at flight condition 1: short period, phugoid, Dutch roll, roll subsidence and spiral, each labelled by eigenvector participation, on an s-plane with constant-zeta and constant-omega-n grid lines.

_{Drawn from a run, not by hand: tools/social/ emits the poles, CI diffs them, and the labels are the classifier's own output.}

Everything below is produced by tests/validation/ and regenerated into docs/VERIFICATION.md, which CI diffs. The input is a set of non-dimensional derivatives and some geometry — there is no matrix anywhere in it.

The aircraft. NT-33A, a variable-stability T-33. The condition. Flight condition 1 of eight, Table II-2: sea level, M = 0.204, power approach, bare airframe. The reference. Robert K. Heffley and Wayne F. Jewell, Aircraft Handling Qualities Data, NASA CR-2144, Systems Technology Inc., December 1972. NTRS 19730003312, distribution unlimited.

Seven numbers the report computed from the same non-dimensional set by a different route.

The source prints its inputs and outputs to three significant figures, so each value carries up to about 0.5% of its own rounding and several combine in every one of these. The gate is 0.5%. The worst observed is 0.26%.

The report prints no headings saying "short period" or "Dutch roll" — the modal characteristics are the factored denominators of its transfer-function tables, and Appendix A prints this exact condition's lateral denominator as its worked example. galata's labels come from eigenvector participation and are checked against that identification.

git clone https://github.com/celikgo/galata.git
cd galata
export VCPKG_ROOT=/path/to/vcpkg # manifest mode fetches the rest
cmake --preset dev
cmake --build --preset dev
ctest --preset dev -L validation # fails if any deviation above exceeds its gate
./build/dev/src/cli/galata run examples/nt33a-trim-and-linearise/study.yaml --output-dir build/trim-study

The tier carries the ctest label validation, so -L is the flag.

The NT-33A at flight condition 1 — trim point, the labelled modal table with its participation factors, the pole map, the Bode plot with every crossover marked, and a Nyquist against the disk the loop must avoid. One self-contained page, no JavaScript and no network requests, with a light variant that is also what it prints as. The committed copy is docs/reports/nt33a-fc1.html, and it opens from disk.

Every number and every mark on it comes from a run: tools/report/ emits the run record, scripts/gen-report-page.py draws the page from it, and CI compares the record numerically against the code and the page byte for byte against the record. The page names the routine that produced each figure.

One published quantity does not, and it stays published rather than being quietly dropped: a state matrix assembled by hand from the report's dimensional derivatives gives a phugoid damping ratio 2.04% below the published value, while the full chain above reproduces it to 0.05%. The cause is now localised to a single matrix entry — a gravity term that the substituted-ẇ form of the report's Appendix C manufactures and that cannot physically exist. The investigation, including what was ruled out, is in docs/notes/phugoid-damping.md; a labelled regression lock holds the gap at its measured size meanwhile.

The trim, linearisation and frequency-analysis workflow now connects to control synthesis and time-domain simulation. This is a usable CLI and C++ library release with a deliberately limited model and controller scope. It does not complete the broader desktop, hardware or v1.0 plans in the roadmap.

The table above is maintained by hand and checked in review. The capability table below is not: it is generated from the registry the CLI dispatches through, by scripts/gen-status-table.sh, and CI fails if the committed copy disagrees. Run galata capabilities to get the same list from your own build.

implemented and validated means the output has been compared against a published reference; see docs/VERIFICATION.md. implemented, unvalidated means it works and is tested, but no published reference has been compared against.

• No qualification or airworthiness claim. The repository provides no tool qualification package or approved certification evidence. Using a result in an assurance process requires application-specific review and independently established evidence.
• Local aircraft dynamics. The derivative model has no stall, Mach schedule, engine map, structural flexibility or validated full flight envelope. The nonlinear driver stops outside its advisory angle-of-attack/Mach guards; staying inside them does not establish model validity.
• Continuous control studies. LQR assumes exact state feedback. PID accepts supplied gains; it does not tune them. Sensors, sampled control, estimator design and flight-code generation are outside this release.
• CLI and library. There is no desktop application, 3-D view, hardware link or onboard execution support.

The operating guide distinguishes numerical convergence, published-reference agreement and aircraft-specific validation.

Flight-control and GNC engineers, controls researchers, students and autopilot developers conducting supervised offline studies. Aviation or defence use is bounded by the same model, numerical and assurance limits; an industry label does not extend the evidence supplied with the tool.

Build the library and CLI, run the tests, then execute the complete local control-design study:

git clone https://github.com/celikgo/galata.git
cd galata
# vcpkg in manifest mode fetches Eigen, yaml-cpp and GoogleTest.
export VCPKG_ROOT=/path/to/vcpkg
cmake --preset dev
cmake --build --preset dev
ctest --preset dev
# Trim, design, analyse, simulate, and write reports into a separate directory.
./build/dev/src/cli/galata run examples/nt33a-control-design/study.yaml --output-dir build/control-study

The output includes control-design Markdown and HTML reports, linear and nonlinear trajectory CSV files, and a content-addressed run manifest. Existing reports require an explicit --overwrite. The example's controller costs and actuator limits are illustrative inputs, not NT-33A hardware specifications. See the example, study-file contract and operating guide for interpreting and repeating the run.

galata capabilities lists what your build can do and how far each capability has been checked.

Requires CMake 3.25+, Python 3.9+, Ninja, a C++20 compiler and a vcpkg checkout. Tested on Linux (GCC and Clang), macOS (AppleClang) and Windows (MSVC) — see .github/workflows/ci.yml for the exact matrix.

The roadmap separates this release from future work: broader validated aircraft models, sampled controllers and estimators, handling qualities, gain scheduling, hardware integration, a desktop application and a stable plugin interface. These are plans, not features of the offline workbench.

These are gates, not aspirations. A change that violates one does not merge.

1. CI exists before the feature. There is no commit that adds source without adding to the CI graph.
2. Nothing is documented before it works. A capability that is a stub says so in its own output and in the docs. A documentation claim that CI does not verify is a bug, and the Status table above is the contract.
3. One source of version truth — the VERSION file, checked by scripts/check-version-consistency.sh.
4. Every URL in every document resolves, checked by scripts/check-doc-links.sh.
5. Strict SI in the numerical core — metres, seconds, kilograms, newtons, radians, kelvin, pascals. Degrees, feet and knots exist only at the UI and file-format boundary, converted by one documented set of functions and enforced by scripts/check-si-boundary.sh. See ADR-0003.
6. Determinism is tested, and its limits are published. Same platform: bit identical. Across platforms: agreement to a published bound, because platform math libraries do not agree on sin in the last bits and claiming otherwise would be false. See ADR-0004.
7. Every physics and numerics source file cites its literature source and states the model's validity envelope and the direction and magnitude of its known error.
8. Reference values in tests come from published sources, never from the implementation. See docs/TESTING.md.
9. No number reaches the user without provenance — which capability produced it, from what inputs, at what version.

Getting these wrong is how flight software fails silently, so they are written down once, in full, in ADR-0002:

• NED navigation frame, FRD body frame.
• Attitude as a unit quaternion, Hamilton convention, scalar-first [w, x, y, z], representing the body-to-NED rotation. Euler angles (3-2-1) are derived output, never integrated state.
• Thirteen-component state vector [p_n p_e p_d, u v w, q_w q_x q_y q_z, p q r] in that order — the order it is integrated, fingerprinted and serialised in. It is not the row order of a produced state-space matrix: linearisation works in twelve Euler coordinates and reports a reduced set, and every LinearSystem carries its own state names.
• Full 6-DOF equations of motion with a general inertia tensor — I_xz is not assumed zero.

Everything below is also readable at celikgo.github.io/galata, which is this repository's own Markdown rendered — including the generated V&V report. It adds no content that is not in the repository.

• docs/CHARTER.md — the engineering rules, in full
• docs/adr/ — architecture decision records
• docs/VERIFICATION.md — the V&V report: what has been checked against a published document, the agreement measured, and what is explicitly unvalidated. Generated by CI from the code, not written by hand.
• docs/TESTING.md — the test tiers and what each proves
• docs/WORKBENCH.md — running, reviewing and embedding an offline design study
• docs/STUDY_FILES.md — accepted YAML, safe output paths and run-record contents
• docs/ROADMAP.md — milestones and their contents
• docs/rfc/ — design records with implementation status; RFC-0001 covers control synthesis
• The NT-33A flight-condition report — the trim point, the modal table, the pole map and the margins for the reference case, drawn from a run and diffed by CI. Committed at docs/reports/nt33a-fc1.html.
• CLAUDE.md and .claude/skills/ — the build, the gates, and the verification methodology written down as skills
• CONTRIBUTING.md — building, the pre-push gates, what review asks
• SECURITY.md — the threat model this tool actually has, and how to report a vulnerability privately
• CODE_OF_CONDUCT.md — Contributor Covenant 2.1

The agreement with NASA CR-2144 quoted at the top of this file is not a sentence somebody typed. It is gated:

• the reference values live in tests/validation/reference/nt33a_fc1.csv, which carries the report number, its authors, its rights position, the SHA-256 of the scan the numbers were read from, and the method by which they were transcribed;
• tests/validation/test_nt33a_trim_linearize.cpp runs the whole chain from the non-dimensional derivative set and fails if any dimensional derivative deviates by more than 0.5%;
• tests/validation/test_nt33a_modes.cpp does the same for the five classical modes;
• docs/VERIFICATION.md is regenerated from those runs by scripts/gen-verification.sh, and CI fails if the committed copy has drifted, so the report cannot describe a measurement the code no longer produces.

ctest --preset dev -L validation # the whole validation tier

The tier carries the ctest label validation, so -L is the flag; the tests are named after what they check, not after the tier.

Apache-2.0. See LICENSE and NOTICE.

The name is the Galata Tower in Istanbul, from which — by an account first printed in Evliya Çelebi's Seyahatnâme — Hezârfen Ahmed Çelebi is said to have glided across the Bosphorus in the 1630s. The story is not evidence and this project does not treat it as such; it is just where the name comes from.