Gamma margin causes over-closure despite lower true depth?

[MSL-DA]

Cover type: Vertical Blind
Window: azimuth 300°, FOV ±73°, height 0.98m, depth (reveal) 0.25m, sill 1.04m
distance_shaded_area: 1.25m

Issue: Gamma safety margin overrides correct cos(gamma) depth calculation, causing over-closure at high gamma even though true room penetration is lower.

Data (from sonnenverlauf.de, same location):

Date	Altitude	Azimuth	Shadow length	Gamma (vs 300°)	True depth (shadow × cos(gamma))
Jun 21	38.70°	254.35°	1.25m	45.6°	0.87m
Aug 15	38.67°	231.24°	1.25m	68.8°	0.45m

Actual perpendicular penetration into the room is lower on Aug 15 than Jun 21 (0.45m vs 0.87m), because more of the sun's travel is lateral (along the window) rather than into the room at higher gamma.

Despite this, the blind closes further on Aug 15 than on Jun 21 for the same distance_shaded_area target.

Cause identified: The gamma safety margin (gamma_abs > 45° → up to +20% extra closure, smoothstep 45°–90°) is applied on top of the geometric calculation, independent of whether the true (cos-corrected) depth has actually increased. Jun 21 gamma (45.6°) sits just at the threshold (negligible margin); Aug 15 gamma (68.8°) is well into the margin zone (~10-11% additional closure), even though true depth dropped by ~50%.

Question: Is the gamma margin intended to compensate for something other than direct-beam floor penetration (e.g. diffuse glare at oblique angles), or should it be reconciled with the cos(gamma) depth correction so it doesn't force extra closure when true calculated depth has decreased? Is there a way to reduce/disable this margin per-cover?

config_entry-adaptive_cover_pro-01KS2QNAQCZG3NZDMB3KZ8D9K6.json

[MSL-DA]

The image on the left is from June 16, and the image on the right is from August 16.

suncalc.org

On June 16, the sun reaches 1.25 meters into the room and hits horizontal surfaces such as the countertop and floor. The curtain closes correctly in steps from 227° (approximately)

On August 16, the sun reaches 1.25 meters into the room, but it doesn’t hit any horizontal surfaces. The curtain closes almost completely down from 227° (approximately)

[jrhubott]

You found a real bug, just not the one you were aiming at. The gamma safety margin is innocent here: I retired it from the vertical axis in #1224, and in your geometry it was inert anyway, because it multiplies a base height of exactly 0.0. Your cos(gamma) reasoning about true penetration is right, and the engine already divides by cos(gamma) for exactly that reason.

The actual cause is a units error in the sill term. In engine/covers/vertical.py the sill offset is computed as sill_height / tan(elevation), which is a distance measured along the ray. That gets subtracted from distance_shaded_area, which is measured perpendicular to the window ("measure from the inside of your window to where you want the sun boundary to be"). The difference is then divided by cos(gamma) a second time, so the sill ends up over-subtracted by a factor of 1/cos(gamma):

what the code does:  position = D*tan(elev)/cos(gamma) - sill/cos(gamma)
what it should do:   position = D*tan(elev)/cos(gamma) - sill

At your gamma of 68.8 degrees that is 1.83 m of phantom shaded distance, against a window only 0.98 m tall. The effective distance goes negative, a clamp pins the raw position at 0 percent, and your min_position_sun_tracking of 25 is what you actually see on the blind.

Running your exact config (azimuth 300, FOV +/-73, height 0.98, depth 0.25, sill 1.04, shaded distance 1.25) through the real engine:

	gamma	now	should be
Jun 21, elev 38.70	-45.7	0 percent	40 percent
Aug 15, elev 38.67	-68.8	0 percent	100 percent

Both of your sample points compute to 0 percent raw, which is why June still looks like it behaves. On June 21 the sun spends much of the afternoon high enough to escape the clamp, so you get 80, then 45, then 25. On August 15 it is past the clamp from the moment it enters your field of view around 227 degrees, so it sits flat at 25 for the rest of the day. That matches the position forecast in the bundle you attached: handler solar, position 25 at all 23 steps from 15:50 to 19:30. Worst case across the whole grid is 55 percentage points too closed.

Set sill height to 0 and the engine matches the geometry to within 1e-12 everywhere, which is what pins it to the sill term specifically rather than anything else in the chain.

Your photos are consistent with this too. On August 16 the sun genuinely is not reaching your horizontal surfaces, and the blind should be wide open. It is closed because of the sill arithmetic, not because anything decided that angle was dangerous.

On your second question, there is no vertical-axis margin to reduce or disable. The only configurable one is tilt_safety_margin, which applies to the tilt axis and defaults to 0. #1220 tracks adding a vertical equivalent, but that one would add closure, so it is the wrong lever for you.

Until the fix ships, the workaround is to raise distance_shaded_area by roughly your sill height, or set sill height to 0 and fold it into the shaded distance yourself. Both over-open a little when the sun is near the window normal, so treat it as a stop-gap rather than a setting to keep.

I have opened #1290 with the full analysis and I am working the fix now. Worth saying that this symptom has come through twice before, in #304 and #358, and both times it was patched at the wrong end without anyone spotting the units mismatch. Your sun-path data and the diagnostics bundle are what finally made it findable.

[MSL-DA]

Thank you so much for that, @jrhubott