Dynamic Inflow 3 State — Robotics/Rotorcraft
Robotics/Rotorcraft/Dynamic_Inflow_3_State · 4 input / 1 output port(s) at insert · exports to Python, MATLAB, Java, Rust, C, C++, VHDL, Verilog, SystemVerilog, PLC Structured Text
Description#
The block's own DESCRIPTION_HTML, rendered verbatim — the same text the config dialog's info panel and the library navigator show. Fix a wrong sentence in the block's .cpp (R-D9), never here.
Dynamic Inflow 3 State
Robotics / Rotorcraft
The Pitt–Peters three-state dynamic inflow model: the induced velocity normal to a rotor disc, as three ordinary differential equations in the mean, lateral and longitudinal inflow. The inflow ratio seen by blade b at radial element r is λi = λ0 + λc·r·cos ψb + λs·r·sin ψb, with ψb = ψ + 2πb/Nb and ψ' = Ω; the three states follow M·λ' = |Ω|·(F − V·L−1 λ), where F is the blade load distribution reduced to thrust, roll and pitch coefficients, V holds the mass-flow parameters and L the wake-skew matrix.
Ports
- fz – the elemental force distribution, an [Nb,Nr] array of force per unit blade length (N/m, or lbf/ft in English units): one row per blade, one column per radial element. Its size sets the number of blades and elements.
- mu – the rotor advance ratio μ, a scalar [1,1], nondimensional.
- muz – the normal velocity ratio μz, a scalar [1,1], nondimensional.
- rho – the air density ρ > 0, a scalar [1,1] (kg/m³, or slug/ft³).
- lambda_i – the normal induced velocity ratio, the same [Nb,Nr] size as fz: the inflow at each blade's azimuth and each element's mid-radius, nondimensional.
Parameters
- Units – Metric (MKS) (the default) or English. The two are the same arithmetic – every quantity is consistent – so the choice only says which units the numbers are in.
- Rotor Rotational Speed – Ω in rad/s, a scalar. Defaults to 41.2596. A negative value turns the azimuth the other way and leaves the inflow dynamics unchanged; zero freezes both.
- Rotor Radius – R, a scalar > 0 (m, or ft). Defaults to 5.08.
- Radial Locations Source – where the radial element edges come from:
- Uniform distribution based on force input (the default) – Nr equal elements spanning the whole blade, edges 0, 1/Nr, …, 1.
- Custom distribution – the edges come from the parameter below.
- Non-dimensional Radial Element Edges – the element edges when the source is
Custom distribution: Nr+1 strictly increasing values in [0,1]. Defaults to
-1, which is the value the uniform setting expects and is ignored there. - Mass Matrix Diagonal – the apparent-mass diagonal:
- Standard 8/(3pi) (the default) – [8/(3π) 16/(45π) 16/(45π)].
- Alternate 128/(75pi) – [128/(75π) 16/(45π) 16/(45π)], the larger mean apparent mass.
- Integration Substeps – M, how many fourth-order Runge-Kutta steps a sample is integrated with on the discrete solver and in exported code, a whole number of 1 or more. Defaults to 100. No Simulink counterpart.
- Sampling Time (s) – zero or less inherits the solver's rate; a positive value runs the block at that period.
Code export
All ten targets: Python, MATLAB, Java, Rust, C, C++, VHDL, Verilog, SystemVerilog and PLC Structured Text. A core holds the four states, publishes the inflow from them, and integrates one sample with the inputs held and M Runge-Kutta substeps. The rotational speed, radius, element edges and mass matrix are folded to constants; a core does 4·M derivative evaluations per sample, and the emitted body grows with Nb·Nr, which is fixed at export time by the size of the fz signal.
The three HDL targets are simulation-only real arithmetic,
quantized at the port: a square root, a division by a signal and a sine of a state have no
Q16.16 form. The cores simulate correctly and are not offered as synthesizable.
Simulink bridge
Import and export, mapped to Aerospace Blockset's
aerolibinflowmodels/Dynamic Inflow (3-State): Units →
units, Rotor Rotational Speed → omega, Rotor Radius
→ radius, Radial Locations Source → radDistrSrc,
Non-dimensional Radial Element Edges → radDistr and Mass Matrix
Diagonal → massMatrix, the last three enumerations 1:1 and therefore
lossless. Always emitted with omegaSrc = Dialog: taking the rotational
speed from a port moves that block's port list, and this block has one.
"Sampling Time (s)" does not cross: the Simulink block is continuous and defines no
SampleTime parameter.
Notes
- Stateful, continuous and nonlinear: four continuous states, all starting at zero. The output reads the state alone, so the block has no direct feedthrough and a loop through it is not an algebraic loop.
- The sign of μ does not matter: the wake-skew ratio is built from |μ|, so the block answers the same at μ and −μ. Measured against the Simulink block, which does the same.
- The Simulink block limits μ and μz to [−1,4] and refuses ρ ≤ 0. This block does not stop a run for them; it guards the divisions instead, so ρ ≤ 0 gives no forcing and a total flow of zero gives no damping.
- The mass-flow parameter V is negative wherever μ² + λt (λt + λ0) is, which is the model's own behaviour and drives the lateral and longitudinal states unstable. Keep μz + λ0 clear of zero, as the Simulink block's own warning asks.
Code facts#
| Fact | Value |
|---|---|
| registered type | Robotics/Rotorcraft/Dynamic_Inflow_3_State |
| family | Robotics/Rotorcraft |
| solver environment class | ICoreBlock_0_Robotics_1_Rotorcraft_2_Dynamic_Inflow_3_State |
| source | src/ICoreBlocks/ICoreBlockLibrary/Blocks/Robotics/Rotorcraft/Dynamic_Inflow_3_State/ICoreBlock_0_Robotics_1_Rotorcraft_2_Dynamic_Inflow_3_State.cpp |
| header | src/ICoreBlocks/ICoreBlockLibrary/Blocks/Robotics/Rotorcraft/Dynamic_Inflow_3_State/ICoreBlock_0_Robotics_1_Rotorcraft_2_Dynamic_Inflow_3_State.h |
| default size on canvas | 130 × 110 px |
| ports at insert | 4 in, 1 out |
| code generators implemented | Python, MATLAB, Java, Rust, C, C++, VHDL, Verilog, SystemVerilog, PLC Structured Text |
Ports#
| # | Direction | Signal type | Description label |
|---|---|---|---|
| 1 | in | ICoreDouble | fz |
| 2 | in | ICoreDouble | mu |
| 3 | in | ICoreDouble | muz |
| 4 | in | ICoreDouble | rho |
| 5 | out | ICoreDouble | lambda_i |
Ports the constructor creates. A block whose port list changes with its configuration adds or removes ports at load time; the count above is the one a freshly inserted block has.
Configuration variables#
| Config variable | Default | Simulink parameter |
|---|---|---|
CONFIG_UNITS (unresolved) | Metric (MKS)%~%English~~Metric (MKS) | — |
CONFIG_OMEGA (unresolved) | 41.2596 | — |
CONFIG_RADIUS (unresolved) | 5.08 | — |
CONFIG_RADSRC (unresolved) | std::string(RADSRC_UNIFORM)%~%RADSRC_CUSTOM~~RADSRC_UNIFORM | — |
CONFIG_EDGES (unresolved) | -1 | — |
CONFIG_MASSM (unresolved) | std::string(MASSM_STD)%~%MASSM_ALT~~MASSM_STD | — |
CONFIG_SUB (unresolved) | 100 | — |
Every block also carries Sampling Time (s) from ICoreBlockSolverEnvironment: zero or less inherits the solver's rate, a positive value runs the block at that period.
Simulink bridge#
| support | Support::Both |
| Simulink path | aerolibinflowmodels/Dynamic Inflow (3-State) |
| port-count rule | PortsParam::None |
SampleTime parameter | no — the counterpart defines none; the rate stays on the ICore side |
| deliberately not crossed | Integration Substeps |
| always set | omegaSrc = Dialog |
| ICore config | Simulink parameter | Value translation |
|---|---|---|
Units | units | Metric (MKS) → Metric (MKS), English → English |
Rotor Rotational Speed | omega | passes through |
Rotor Radius | radius | passes through |
Radial Locations Source | radDistrSrc | Uniform distribution based on force input → Uniform distribution based on force input, Custom distribution → Custom distribution |
Non-dimensional Radial Element Edges | radDistr | passes through |
Mass Matrix Diagonal | massMatrix | MASSM_STD → SL_MASSM_STD, MASSM_ALT → SL_MASSM_ALT |
Caveat (shown to the user): aerolibinflowmodels/Dynamic Inflow (3-State) is continuous and has NO SampleTime parameter (verified against the R2026a block dialog). omegaSrc is pinned to Dialog because taking the rotor speed from a port moves that block's port list, and this block has one; "Integration Substeps" is how this block integrates a sample and has no counterpart
Catalog contract: src/ICoreBlocks/ICoreCoder/ICoreCommandSystem/SimulinkBridge/ICoreSimulinkBlockCatalog.h
Description vs code#
The lists agree. check_block_descriptions.py finds no disagreement between the description's Ports, Parameters, Code export and Simulink bridge lists and the code's.
The verdict above is
tools/docs/check_block_descriptions.py(P7.1), which compares LISTS. It cannot read a sentence: "stateless" on a block with a state, an initial-value semantic the recursion does not implement, a "not synthesizable" caveat the HDL banner contradicts. That is the agent audit (P7.3) on BLOCK_DESCRIPTION_AUDIT.md, and this tool's green is not a substitute for one.
File banner (developer view)#
The top comment of the block's .cpp — the maths, the realization and the export strategy, addressed to whoever changes it. It must not contradict the description above (P7.5).
Dynamic Inflow (3-State) -- the induced velocity through a rotor disc, as three ODEs State [l0 lc ls psi]; the inflow ratio at blade b, radial element r is
lambda(b, r) = l0 + lc * rm(r) * cos(psi_b) + ls * rm(r) * sin(psi_b), psi_b = psi + 2*pi*b/Nb, psi' = Omega
and the three inflow states follow M l' = |Omega| * (F - V L^-1 l) with
M = diag(M0, 16/(45 pi), 16/(45 pi)), M0 = 8/(3 pi) or 128/(75 pi) F = sum over blades and elements of fz * dr * R / (rho pi R^2 (Omega R)^2) times [1, -rm sin(psi_b), -rm cos(psi_b)] lt = muz + l0, VT = sqrt(mu^2 + lt^2), V = (mu^2 + lt (lt + l0)) / VT X = |mu| / (VT + |lt|) (that is tan(chi/2), chi the wake skew) L = [ 1/2, 0, -a ; 0, 2(1 + X^2), 0 ; a, 0, 2(1 - X^2) ], a = 15 pi X / 64
⚠ EVERY LINE ABOVE IS MEASURED, and the block cannot be read: aerolibinflowmodels/Dynamic Inflow (3-State) is a compiled ThreeStateDI block (no mask, no .m, no shipped source -- only libmwaeroblks_inflowModels.dylib), and the R2026a doc page carries no equations. It was identified through the model API: the derivative and the output evaluated at chosen states and inputs (feval(mdl, t, x, u, 'derivs') / 'outputs'), 400+ points over random states, advance ratios of both signs, both mass-matrix settings, a custom radial distribution, English units and an Omega port. Worst relative disagreement of the formulas above against the block: 1.2e-15.
Four things that measurement settled, none of them guessable:
- The couplings are ANTISYMMETRIC. L(l0, ls) = -a where L(ls, l0) = +a, and the mean row of L
carries half the weight of the others -- which is why M0 is the 8/(3 pi) of the dialog rather than the 2/pi apparent mass of the same state in the finite-state block.
- The MEAN forcing takes -sin(psi_b) and the LONGITUDINAL forcing -cos(psi_b), i.e. the block
pairs its cosine state with a sine-weighted moment. Writing the textbook pairing instead leaves a rig that passes export verification (ICore against ICore) and fails Simulink.
- THE ADVANCE RATIO'S SIGN DOES NOT MATTER, AND THAT IS MEASURED, not assumed: the block's
derivative at mu and at -mu is bit-identical, at every state tried (three states, both a forcing and a damping split, and a 200-sample run at a constant negative mu). So the wake skew is |mu| / (VT + |lt|), in [0, 1], with no sign anywhere -- a signed X passes export verification (ICore against ICore) and fails Simulink the moment mu crosses zero, which is exactly how this was found: one sample out of 500, and the parity residual it left was 20 % of the inflow.
- A negative Omega spins the azimuth backwards (psi' = Omega) and leaves the inflow dynamics
alone (|Omega|); Omega = 0 freezes both. Units (Metric/English) is the same arithmetic.
Sample results#
Plotted: impulse — Impulse: one sample of 1 at k = 5, 0 elsewhere (Repeating Sequence Stair)
Category dynamic · sample time 0.1 · 60 steps · commit 23d8841c6561ca4bb64cd9b5b64da9638de12629 · produced by docsSample --out <folder> --blocks Fixed_Wing_Point_Mass Kernel_Classifier_Predictor Kernel_Regression_Predictor Rotor Rotor_With_Flap_Effects Multirotor Multirotor_With_Flap_Effects Dynamic_Inflow_3_State Kurtogram Empirical_Mode_Decomposition Modal_FRF Order_Spectrum --steps 60 · data docs/generated/samples/Robotics__Rotorcraft__Dynamic_Inflow_3_State.json · the SVG is generated from those numbers by tools/docs/plot_svg.py, so it is a run and not a drawing (R-D10).