Skip to content

Commit 9b636de

Browse files
1-Bart-11-Bart-1
committed
Update readme for new release
1 parent 4c9e1bb commit 9b636de

File tree

3 files changed

+192
-0
lines changed

3 files changed

+192
-0
lines changed

‎CHANGELOG.md‎

Lines changed: 100 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,106 @@ SPDX-FileCopyrightText: 2025 Uwe Fechner, Bart van de Lint
33
SPDX-License-Identifier: MPL-2.0
44
-->
55

6+
# v0.6.0 21-02-2026
7+
8+
## Changed
9+
- Component constructors (`Point`, `Segment`, `Wing`, `Winch`,
10+
`Transform`) now accept a symbolic `name` (Symbol) as the first
11+
argument in addition to numeric indices. Numeric `idx` values still
12+
work. Use e.g. `Point(:kcu, pos, DYNAMIC)`.
13+
- BREAKING: `Segment` constructor takes separate `point_i`, `point_j`
14+
arguments instead of a `point_idxs` vector.
15+
- BREAKING: Rotation matrix fields renamed from `R_a_b` to `R_a_to_b`
16+
throughout (e.g. `wing.R_b_w` → `wing.R_b_to_w`).
17+
- BREAKING: `ControlPlotsExt` package extension removed. Visualization is
18+
now handled entirely by `SymbolicAWEModelsMakieExt`.
19+
- BREAKING: Predefined model factory functions removed
20+
(`create_ram_sys_struct`, `create_simple_ram_sys_struct`). Build models
21+
using component constructors or YAML instead.
22+
- BREAKING: Ram air kite and V3 kite models moved to dedicated packages
23+
([RamAirKite.jl](https://github.com/OpenSourceAWE/RamAirKite.jl),
24+
[V3Kite.jl](https://github.com/OpenSourceAWE/V3Kite.jl)).
25+
Their data directories are removed from this package.
26+
- `src/system_structure.jl` split into modular files under
27+
`src/system_structure/` (types, core, utilities, transforms, wing,
28+
named_collection).
29+
- `src/generate_system.jl` split into 13 focused modules under
30+
`src/generate_system/` (point_eqs, segment_eqs, wing_eqs, group_eqs,
31+
winch_eqs, pulley_eqs, tether_eqs, scalar_eqs, vsm_eqs, accessors,
32+
helpers, create_sys).
33+
- Makie extension significantly overhauled with new plotting functions.
34+
- Test suite completely rewritten. The old tests (`test_simulation`,
35+
`test_linearization`, `test_initialization`, `test_sam`, etc.) tested
36+
the full assembled kite model as a black box, making failures hard to
37+
diagnose. The new tests isolate each component with minimal models
38+
built from constructors, verifying physics against analytical
39+
solutions:
40+
- `test_point` — gravity free-fall, damping, quasi-static equilibrium
41+
- `test_segment` — spring-damper forces, stiffness, drag
42+
- `test_wing` — QUATERNION and REFINE wing construction, VSM coupling
43+
- `test_wing_dynamics` — rigid body torque response, precession,
44+
angular momentum conservation
45+
- `test_tether_winch` — reel-out dynamics, Coulomb and viscous
46+
friction, terminal velocity
47+
- `test_pulley` — equal-tension constraints, multi-segment pulleys
48+
- `test_transform` — spherical coordinate positioning
49+
- `test_quaternion_conversions` — quaternion ↔ rotation matrix
50+
- `test_quaternion_auto_groups` — auto-generated twist DOFs
51+
- `test_principal_body_frame` — principal vs body frame separation
52+
- `test_heading_calculation` — kite heading from tether geometry
53+
- `test_section_alignment` — VSM section ↔ structural point mapping
54+
- `test_profile_law` — atmospheric wind profile verification
55+
- `test_bench` — performance regression tracking
56+
- Complete documentation overhaul with new pages: coordinate_frames,
57+
vsm_coupling, pipeline, tutorial_julia, tutorial_yaml.
58+
- Data files reorganised: base settings moved to `data/base/`, new
59+
`data/2plate_kite/` and `data/saddle_form/` model directories added.
60+
61+
## Added
62+
- `NamedCollection` indexing — components support symbolic names
63+
(e.g. `sys.points[:kcu]`, `sys.segments[:bridle_1]`).
64+
`SystemStructure` resolves all symbolic references to numeric indices
65+
automatically via `assign_indices_and_resolve!()`.
66+
- `WingType` enum (`QUATERNION`, `REFINE`) for explicit wing type
67+
selection. `REFINE` applies per-panel forces directly to structural
68+
points for higher fidelity aeroelastic coupling.
69+
- `AeroMode` enum (`AERO_NONE`, `AERO_DIRECT`, `AERO_LINEARIZED`) for
70+
build-time control over aerodynamic computation strategy.
71+
- YAML-based model definition via `load_sys_struct_from_yaml()`,
72+
`update_yaml_from_sys_struct!()`, and
73+
`update_aero_yaml_from_struc_yaml!()`.
74+
- REFINE wing support (`src/vsm_refine.jl`) — structural deformation
75+
coupled directly to VSM panel geometry with moment-preserving force
76+
distribution.
77+
- Principal vs body frame separation for QUATERNION wings. Principal
78+
frame (diagonal inertia) used for Euler equations, body frame (from
79+
reference points) used for output and VSM coupling.
80+
- Auto-group generation for QUATERNION wings when groups are not
81+
explicitly provided.
82+
- `record()` for saving simulation replays to MP4.
83+
- `plot_sphere_trajectory`, `plot_body_frame`, `plot_aoa` plotting
84+
functions.
85+
- `update_segment_forces!`, `set_world_frame_damping`,
86+
`set_body_frame_damping`, `segment_stretch_stats` utility functions.
87+
- New examples: `hanging_mass`, `catenary_line`, `saddle_form`,
88+
`coupled_2plate_kite`, `coupled_realtime_visualization`,
89+
`coupled_linearize`, `coupled_simple_lin_model`,
90+
`coupled_tether_deflection`, `heading_gate`,
91+
`cosine_steering_trajectory`, `makie_polar_plots`,
92+
`static_load_2plate_kite`.
93+
- Benchmark test (`test_bench.jl`) for performance tracking.
94+
95+
## Removed
96+
- `predefined_structures.jl` and factory functions
97+
(`create_ram_sys_struct`, `create_simple_ram_sys_struct`,
98+
`create_tether_sys_struct`, `copy_to_simple!`).
99+
- Ram air kite data files, LEI kite directory, `data/kite.obj`.
100+
- Old examples: `ram_air_kite`, `lin_ram_model`, `simple_lin_model`,
101+
`lin_simple_tuned_model`, `simple_tuned_model`,
102+
`realtime_visualization`, `reposition`, `tether_props`.
103+
- `SymbolicAWEModelsControlPlotsExt` package extension.
104+
- `src/precompile.jl`.
105+
6106
# v0.5.0 25-08-2024
7107
## Removed
8108
- BREAKING: the Winch struct doesn't have a model field anymore. Instead, all equations are symbolic, and the WinchModels dependency is removed.

‎README.md‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -185,6 +185,42 @@ page for details.
185185

186186
---
187187

188+
## Testing
189+
190+
Each component is tested in isolation using minimal models built from
191+
constructors, with results verified against analytical solutions. This
192+
proves that the underlying dynamics are physically correct — for
193+
example, that angular momentum is conserved, that terminal velocity
194+
matches the analytical prediction, and that spring-damper forces follow
195+
the expected constitutive law.
196+
197+
```bash
198+
# Run all tests
199+
julia --project=. -e 'using Pkg; Pkg.test()'
200+
201+
# Run a specific test file
202+
julia --project=test test/test_point.jl
203+
```
204+
205+
| Test file | What it verifies |
206+
|-----------|------------------|
207+
| `test_point` | Gravity free-fall, damping, quasi-static equilibrium |
208+
| `test_segment` | Spring-damper forces, stiffness, drag |
209+
| `test_wing` | QUATERNION and REFINE wing construction, VSM coupling |
210+
| `test_wing_dynamics` | Rigid body torque response, precession, angular momentum |
211+
| `test_tether_winch` | Reel-out, Coulomb/viscous friction, terminal velocity |
212+
| `test_pulley` | Equal-tension constraints, multi-segment pulleys |
213+
| `test_transform` | Spherical coordinate positioning |
214+
| `test_quaternion_conversions` | Quaternion ↔ rotation matrix |
215+
| `test_quaternion_auto_groups` | Auto-generated twist DOFs |
216+
| `test_principal_body_frame` | Principal vs body frame separation |
217+
| `test_heading_calculation` | Kite heading from tether geometry |
218+
| `test_section_alignment` | VSM section ↔ structural point mapping |
219+
| `test_profile_law` | Atmospheric wind profile verification |
220+
| `test_bench` | Performance regression tracking |
221+
222+
---
223+
188224
## Ecosystem
189225

190226
Key related packages:

‎docs/src/developers.md‎

Lines changed: 56 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -313,6 +313,62 @@ be reflected in the built documentation.
313313

314314
---
315315

316+
## Testing
317+
318+
The test suite is designed around **component isolation**: each test file
319+
builds a minimal model from constructors (no YAML, no full kite) and
320+
verifies the physics of a single component against analytical solutions.
321+
This proves that the underlying dynamics are physically correct — for
322+
example, that angular momentum is conserved, that terminal velocity
323+
matches the analytical prediction, and that spring-damper forces follow
324+
the expected constitutive law.
325+
326+
### Running tests
327+
328+
```bash
329+
# Run the full test suite
330+
julia --project=. -e 'using Pkg; Pkg.test()'
331+
332+
# Run a single test file
333+
julia --project=test test/test_point.jl
334+
julia --project=test test/test_segment.jl
335+
```
336+
337+
### Test files
338+
339+
| Test file | Component | What it verifies |
340+
|-----------|-----------|------------------|
341+
| `test_point` | [`Point`](@ref) | Gravity free-fall, damping, quasi-static equilibrium |
342+
| `test_segment` | [`Segment`](@ref) | Spring-damper forces, stiffness, drag |
343+
| `test_wing` | [`Wing`](@ref AbstractWing) | QUATERNION and REFINE construction, VSM coupling |
344+
| `test_wing_dynamics` | [`Wing`](@ref AbstractWing) | Torque response, precession, angular momentum conservation |
345+
| `test_tether_winch` | [`Tether`](@ref), [`Winch`](@ref) | Reel-out, Coulomb/viscous friction, terminal velocity |
346+
| `test_pulley` | [`Pulley`](@ref) | Equal-tension constraints, multi-segment pulleys |
347+
| `test_transform` | [`Transform`](@ref) | Spherical coordinate positioning |
348+
| `test_quaternion_conversions` | — | Quaternion ↔ rotation matrix round-trips |
349+
| `test_quaternion_auto_groups` | [`Group`](@ref) | Auto-generated twist DOFs |
350+
| `test_principal_body_frame` | [`Wing`](@ref AbstractWing) | Principal vs body frame separation |
351+
| `test_heading_calculation` | — | Kite heading from tether geometry |
352+
| `test_section_alignment` | [`Wing`](@ref AbstractWing) | VSM section ↔ structural point mapping |
353+
| `test_profile_law` | — | Atmospheric wind profile verification |
354+
| `test_bench` | — | Performance regression tracking |
355+
356+
### Writing new tests
357+
358+
When adding a new component or equation, follow this pattern:
359+
360+
1. **Build a minimal model** using constructors — only include the
361+
components needed to test the behaviour in question.
362+
2. **Derive the expected result analytically** — free-fall distance,
363+
terminal velocity, oscillation frequency, etc.
364+
3. **Simulate and compare** — run `next_step!` in a loop and check the
365+
result against the analytical solution with a tight tolerance.
366+
4. **Keep tests independent** — each test file should build its own
367+
`SymbolicAWEModel` from scratch. Use `vsm_interval=0` and
368+
`AERO_NONE` when aerodynamics are not relevant.
369+
370+
---
371+
316372
## Coding style guidelines
317373

318374
Please adhere to the following style guidelines to maintain code quality and

0 commit comments

Comments
 (0)