willtools-demo/panellift/PLAN.md

panellift — plan

PCI Chapter 8 handling checks for precast wall panels, fed from the Revit model that already holds the geometry.

Scope is the "first tier" agreed on 2026-08-18: stripping and yard handling, flat. Transportation (needs dunnage positions the model does not have) and erection (the panel rotating up, load shedding onto the lowest pick point) are explicitly out.

---

Why the calculation does not run inside Revit

The extension runs on IronPython 2.7 on Revit's UI thread. A calculation whose output goes to a plant has to be verifiable, and verifiable means a test suite that runs in a second without a Revit licence, a model, or a Windows box.

So: Revit writes a JSON file, a plain CPython package reads it. Same pattern already proven by vibe.aiextract. The package has no dependencies — every dependency is something that can be missing at the moment somebody needs a number.

Revit  ──liftexport──>  <mark>.json  ──panellift──>  report.html
(IronPython 2.7)                        (CPython 3.9+)

A consequence worth keeping: a panel can be checked by hand-writing the JSON, with no model at all.

Decisions taken

Question	Decision
Lifter capacity vs handling multiplier	Not stacked. PCI Table 8.3.1 note (a): those factors are for flexural design and are not to be applied to lifting-device safety factors. Inserts are checked against unfactored reactions and against the published rating of the part itself — safety factors are per product in knowledge/catalogue.yaml and an insert with none published is reported unjudged. This row used to end "with the manufacturer's 4:1 tension / 2.67:1 shear". No manufacturer published that. The sentence was written the day after the constant it justified and it cited nothing; the one datasheet in this repository for the parts it reached (ALP catalog p53, 02/2024) heads its capacity table "Capacity in Concrete 4:1 SWL" across both load columns — 4:1 in shear as well. Corrected 2026-08-31, and recorded rather than quietly deleted, because an invented pedigree on a safety factor is the kind of thing that gets re-derived from the same document twice.
Sling angle	Engineer's config file, in degrees. Not inferred from the model.
Rolling block vs static lift	Engineer's config file. Two different mechanics, not a coefficient — see below.
Load cases	Stripping + yard handling.
Flexural capacity	Shipped 2026-08-31 as ACI 318-19 approximate fps (Eq. 20.3.2.3.1), strand only, in capacity.py. The columns were informational for one day. Owner's ruling 2026-09-01 — "M/pMn 对我而言>1.0是可以的,我能盖章。你不行,大于1.0你就报fail,我做最后决策。" — so M/φMn > 1.0 is a FLEX-CAP FAIL and V/φVn > 1.0 a SHEAR-CAP FAIL, checked at every station of every stage, with no development-length exclusion: the tool may not bless a ratio over 1.0 and the engineer stamps past it. The stress check keeps its own verdict; a station that cannot be judged stays a dash and is neither. Full strain compatibility remains the upgrade: it needs the strand stress-strain curve and mild-steel/WWF input paths that no layer holds yet. fy defaults to 60 ksi, fyt from the design summary; both overridable in config.

Rolling block vs static lift

• rolling — equalising sheaves, every line in a cable group carries the same force. Two groups, two equations of statics, determinate. Reactions do not depend on stiffness, so a blockout does not move them.
• static — fixed-length slings. The panel is a continuous beam on rigid supports; three or more support lines are indeterminate and the reactions follow flexural stiffness. A blockout beside a support really does shed load off it.

Measured on the ASPIRE panel with three support lines at 4 / 16 / 28 ft:

rolling   15,167  15,167  15,167 lb
static    13,508  18,484  13,508 lb      middle line +22%

Picking the wrong one is a 22% error on an insert. Hence: the engineer says.

The design decision that matters most

PCI Figure 8.3.2's coefficients are a test, not the engine.

Those coefficients only hold when the picks sit where positive and negative moment come out equal. The entire reason to check a real ticket is that the detailer may not have put them there — so using the closed form as the engine would assume the answer.

Instead the moment comes from a real beam solve at the actual insert positions, and Figure 8.3.2 becomes the regression test: put the supports at (sqrt(2)-1)/2 of the span and the solver must return 0.0214 w a b².

It does. That identity is also derived in pci.py rather than quoted — solving w(aL)²/2 = wL²(1-2a)²/8 - w(aL)²/2 gives 4a² + 4a - 1 = 0, hence a = 0.20711 and a coefficient of 0.02145, which is PCI's 0.0214.

Known idealisation

The panel is treated as a beam spanning its long direction. This is PCI's own method for My, and it is what the ASPIRE examples do. It is not valid for a near-square panel, where two-way plate action governs — that is finite-element territory (PanelsPlus). The code must refuse rather than answer when the aspect ratio gets close to 1. Not yet implemented.

The transverse direction Mx will use PCI's closed form with the "resisted by 15t or b/2" rule, as a secondary check.

Status

Done and tested — 34 tests, all passing

Module
model.py	Panel, Blockout, Lifter, Rigging, Reinforcement, Stage, Material
section.py	b_eff(x), S(x), I(x), w(x), blockout merging, weight reconciliation
pci.py	Table 8.3.1, 5√f'c, Figure 8.3.2 closed forms, optimal support fraction
linalg.py	dense solver, so there are no dependencies
statics.py	insert clustering → support lines → cable groups; rolling and static solvers; V(x), M(x); sling forces

Reproduced from ASPIRE Winter 2019 (Brown), which reprints PCI Table 8.3.1 and Figure 8.3.2:

	ours	published
unit weight	109.4 psf	109.4
S solid	1531 in³	1531
S, five 6"×24" pockets	1148 in³	1148
unfactored moment	24,020 lb-ft	23,973
stripping stress, solid	245 psi	244 — OK vs 316
transport stress, solid	282 psi	282 — OK vs 354
stripping stress, pocketed	326 psi	326 — no good vs 316
transport stress, pocketed	377 psi	376 — no good vs 354

The moment differs by 0.2% because the article rounds the coefficient to 0.0214; we carry (√2−1)²/8.

Done since — 76 tests

checks.py	cracking, insert capacity with sling amplification, edge-anchor shear and plumb-hang tension, per-stage derating, aspect-ratio refusal, unrated inserts as a warning
report.py	self-contained HTML; build_many puts every stage of one piece in one file behind a verdict table
layout.py	recommended insert positions and the delta from the model
cli.py	panellift job.json -o report.html [--json]
vibe/liftexport.py	the Revit side of the job file, plus the subprocess
Panel Lift Check	the button: select an assembly, confirm the picks, choose where the HTML goes

Next

1. Strain-compatibility φMn (upgrade of capacity.py's approximate-fps columns, shipped 2026-08-31): strand power curve, mild steel and WWF layers — the input paths for both are still owed before this can be honest.
2. Transverse equilibrium. layout.py reports how far a row's centroid sits off the width centreline, but a beam model cannot say what that costs. On a panel with large openings the recommended rows can be forced entirely to one side, and whether the piece twists is currently the engineer's call with no number attached.
3. Per-piece config overrides (sling angle, lift mode) without editing the plant knowledge file.

Answered against the live model (sample_job, 2026-08-18)

Probed on PNL204 — a PANEL_VERTICAL::08", design PNL1.0, 13'-10" x 4'-0" x 8", 5,533 lb, 51 members.

Panel-local frame. x is the width, y is the thickness, z is the length. On PNL204: x ∈ [-2.000, 2.000], y ∈ [-0.667, 0.000], z ∈ [0, 13.917] ft. So the form face is y = -0.667 and the exposed face y = 0.

1. Blockouts are family instances, not Opening elements. The document contains zero Opening instances. Voids are a family group under Generic Models:

family	count
VOID_RECTANGULAR	622
VOID_RECESS_3_SIDES	234
VOID_POUR_STRIP	102
VOID_DT_DAP	54
VOID_ROUND	46
V-PLATE_VOID_RECTANGULAR	22
VOID_TAPER_ROUND	17

STEM_BLOCKOUT (2694) is under Specialty Equipment and belongs to double-tee stems, not wall panels. So b_eff(x) gets populated the same way the lifters do: instance position transformed to panel-local, size from instance parameters. Whether these families actually cut the solid, or only mark the void for the detailer, still needs checking — it decides whether the geometric weight reconciliation will agree.

2. Insert role separates cleanly by geometry. On PNL204:

family	count	x	y	z
ANCHOR_FACE_4T	4	±1.000	-0.667 (form face)	2.583, 11.417
LIFT_EDGE_4T	2	±1.000	-0.333 (mid-thickness)	13.917 (top end)

Face-mounted and inboard → stripping. Mid-thickness and at an end → erection, exactly as suspected of the LIFT_EDGE_8T seen at 0'-0". Two independent signals agree, family prefix and position, so the rule can check itself rather than trusting a name list.

The real pick is 4 points on 2 support lines at z/L = 0.186 and 0.180, against the PCI optimum of 0.207 — a good first live test case.

Capacity is encoded in the family name: ANCHOR_FACE_4T → 4T, LIFT_EDGE_4T → 4T, LIFT_EDGE_8T → 8T. That makes knowledge.yaml's capacity_lb table largely derivable. Open question for the engineer: is 4T the working load limit or the ultimate? It is a factor of four on every insert check.

3. Strand positions are recoverable, through-thickness included. Four 1-2_STRAND at y = -0.500 and y = -0.167 — two layers, 2 in. from each face of the 8 in. panel. That y is precisely the depth strain compatibility needs. WWF_MESH_A sits in the same two layers, confirming per_face in the spec schema.

Unresolved: the four strands sit at only two x stations (-1.500 and 0.000) on a panel spanning -2.000 to 2.000, which is not symmetric. Either the family insertion point is off-centre or _point_of is returning a curve start. Worth pinning before trusting a lever arm.

4. Panels are boxes, and there are only two thicknesses. PNL204's local bounding box is a clean 4.000 x 0.667 x 13.917. The whole model uses only PANEL_VERTICAL and PANEL_HORIZONTAL, each in 08" and 12".

One discrepancy to carry: the bounding box gives 13.917 ft = 13'-11" while the panel's stated length parameter says 13'-10". Use the stated dimensions for the calculation and report the delta, the same way a ticket's printed length runs over the modelled one on stemmed pieces.

Smaller known gaps

• Three support lines with equal gaps on both sides make the cable grouping ambiguous; currently resolved to the first. Should warn.
• Partial-depth blockouts are carried but do not reduce S.
• Inclined slings: the horizontal component is reported, but the secondary moment it induces is not analysed. LECWall does not either, and says so.

---

Insulated (sandwich) panels

Added 2026-08-31. Read this before touching sandwich.py or the refusal in cli._refuse_sandwich.

Why it is a refusal first and mechanics second

Every section property in this package is built on one prism of concrete panel.thickness_in deep — section.NetSection, section_modulus_in3, the four-corner stress. An insulated body is two concrete wythes with insulation between them, and idealising it as solid concrete at the envelope depth overstates the section modulus and understates the tensile stress. The owner, 2026-08-31:

"把夹芯板当实心算并不 conservative。因为 insulation 并不会 100% composite, 你忽视了中间的 composite ratio 的计算和可能出现的问题。这是一个 insulated panel design 的时候非常大的一个问题。"

On the dimensions of a real 16 in. piece (4 in. architectural wythe, 4 in. EPS, 8 in. structural wythe, 64 in. of clear width) the arithmetic is:

	I, in⁴	governing S, in³
solid at the 16 in. envelope	21,845	2,731
fully composite	20,139	2,324
non-composite	3,072	768
structural wythe alone	2,731	683

So the solid idealisation overstates the governing section modulus by 3.56× against the non-composite bound and still 1.18× against the fully composite one. Both above 1.0: there is no reading of a sandwich under which treating it as solid is the safe direction, because a sandwich has a hole in the middle of its depth and is weaker than a solid piece of the same envelope however well the connectors work. test_sandwich.py keeps every one of those numbers with the arithmetic in a comment.

Until 2026-08-31 this never fired. The weight gate refused every insulated piece for an unrelated reason — the solid sum was one wythe — and that refusal accidentally protected against this. The weight is right now, so the gate opens, and it opens onto a wrong section. cli._refuse_sandwich is what closes that window, and it is deliberately upstream-independent: it does not care whether the weight gate let the piece through. If a sandwich job file reaches this package at all, it fires.

The detection signal travels in the job file

source.solid_parts — the per-solid breakdown the Revit side has written since 2026-08-31. Nothing on this side re-derives it: the file is the boundary, and a second opinion about a model this process cannot see would be a guess with a different accent. The ladder is in sandwich.detect and the only rung that may return False is one concrete solid and nothing left out. No signal at all returns None, never False.

The conventions chosen, and why each is the conservative one

Every one of these is stated on the number it touches, in the report and in sandwich.py, and every one is on the owner-question list below.

decision	what was chosen	why it is the conservative reading
wythe load sharing, non-composite bound	the wythes are tied by the connectors so they deflect together; each takes the moment in proportion to its own stiffness, M_i = M·I_i/ΣI, so f = M·(t_max/2)/ΣI	it is the compatible answer, and the extreme fibre lands on the thickest wythe rather than being averaged over both. The alternative — sharing by mass — puts less moment on the stiff wythe than compatibility does
is the face wythe structural	reported both ways. The non-composite bound assumes both wythes resist; structural_wythe_alone assumes the thickest carries the whole piece and the thinner is dead load	the second is the smallest section modulus of the three (683 in³ against 768), so printing it is the conservative half and printing only it would hide the bound the owner may actually want
which wythe is structural	the thickest, by trade convention	not measured, and it is named as not measured every time it is used. There is no conservative direction available here, only a disclosed one
openings	assumed to run through both wythes, so b_eff(x) is shared	the measured plan areas of the two wythes on the real piece differ by ~1%, which is inside the rounding on the volumes. If they diverge on some piece, each wythe needs its own opening set
insulation	contributes nothing to the section	its modulus is three orders below concrete's. This is the standard treatment, not an approximation invented here
modular ratio	1, no transformation	both wythes are the same mix on every piece measured. Where the densities differ the report says so rather than quietly scaling one
connector demand distribution	the mean over a row, at the fully-composite VQ/I, named as a mean and not as a bound	it is honest about being an assumption. It is not conservative — see below — and saying so is the only available treatment until k exists

The bounds are scaffolding, not the product

The owner's instruction, and it reshapes what this is for. The two-bound envelope is what can be computed while the connector data is absent. The partial-composite middle is the thing insulated-panel design is actually about, and the capacities and stiffnesses being hunted are the inputs to computing it, not garnish. The report presents the bounds as an interim envelope with the missing computation named.

可能出现的问题 — what the two bounds do NOT bracket

sandwich.concerns() is the enumeration, and reading it is the point. Three quantities are bracketed. Everything else about a sandwich panel is not a bounds question at all, and a reader who takes a two-bound report as an envelope over all of it is the failure the list exists to prevent.

Bracketed:

• wythe flexural tension — maximal non-composite, monotone in between. With one trap: the inner face of a wythe changes sign between the bounds (compression non-composite, tension fully composite), so both faces of both wythes have to be evaluated, not only the envelope faces.
• interface shear flow — maximal fully composite, q = VQ/I, zero non-composite. A true upper bound on the total interface force, which is why it is computed even where the plant designs the panel non-composite.
• deflection — maximal non-composite. Differential bowing from temperature and shrinkage is a service problem, not a handling one, and is declared out of scope rather than silently omitted.

Not bracketed:

• connector force distribution along the span. Both bounds are distribution-free — one puts zero on every connector, the other spreads demand smoothly as V(x). Real partial interaction concentrates slip, and therefore connector force, at the ends of each shear span, decaying over a length set by the connector stiffness k against the wythes' axial stiffness EA. A uniform-demand assumption understates the end connectors. When k arrives, the standard partial-interaction treatment is what goes in here; until then the mean is reported and named as a mean.
• connector force at discontinuities — an opening edge or a pick point restarts the slip profile and the connectors beside it see a local peak neither bound shows.
• connector NORMAL (tension) demand. A flat pick hangs one wythe off the other through the connectors in direct tension; an erection pick peels the face wythe as the piece rotates. Not an interface-shear question at all, so neither bound speaks to it — and where the panel is designed non-composite it is likely the governing connector demand. This is why a capacity is needed per failure mode, not as one number.
• local flexure of the face wythe between connectors — a slab strip on discrete supports at the connector spacing. A different mechanism from anything in this package.
• percent composite is not one number. The stiffness ratio (κ_I = (I_eff − I_nc)/(I_full − I_nc), what governs deflection and bowing) and the strength ratio (η, the degree of shear connection, what governs capacity) are different quantities in the trade's own methods. Any percentage this report prints says which one it is.

What stands down, and what unblocks it

stood down	why	unblocked by
composite ratio (both of them)	a computed ratio without connector data is not hard, it is impossible. The width of the band is printed; the position in it is not	connector slip stiffness k, lb/in per connector (stiffness ratio); connector capacity per failure mode (strength ratio)
connector sufficiency	no capacity is published in any layer. verdict stays None — never OK, never a pass	capacity per failure mode: interface shear and normal/tension, lb per connector
connector recognition on the gather side	nothing reads the connector instances off the piece. source.connectors is written with every field null and the reason beside it, because a missing key reads downstream as "this piece has no connectors"	a recognition rule. Measured by the bridge holder, and it is plant knowledge so the parameter names live in the plant layer: identity is a type-level parameter, not the family name, and a second type-level parameter is the gate. Family-name matching silently finds nothing here — a decoy family with no instances carries the same identity string
the layup on an old job file	solid_parts without z0_in/z1_in says a sandwich exists and cannot say what its section is. Layup.measured is False and section_bounds refuses rather than inventing a layup	re-export the piece

The plant calls its pins non-composite, and that settles nothing

The insulation family on these pieces carries the description "EPS with Holes for Non-composite pins". That is evidence about design intent, carried verbatim in source.connectors.declared_action and quoted in the report. It is not a structural ruling, and nothing in the mechanics branches on it: partial composite action exists physically whatever the label says, and the connector product has published stiffness data. What the owner's confirmation would settle is which bound the pass/fail line is drawn against — the report carries both either way.

Which end is up, and why a disclosed fallback is allowed

knowledge.up_end_from_origin is this project's flagship declared-coverage refusal — three measured conditions, and it never returns False. When it declines, liftexport.erected_orientation reads global elevation and answers anyway, writing the refusal's own reason into source.up_end_basis_why — and nothing read that key, partly because read_panel looked for source inside panel while the exporter writes it at job level, so panel.source came out empty on every real job file.

Both halves are fixed. The job-level source is merged onto the panel, and report.up_end_disclosure renders the fallback on the page, in the CLI's stdout and in the summary's basis key — written only when the ruled mechanism did not answer, the same "only when it is not the ordinary case" rule searched and enabled follow.

The deliberate decision, because "never fall back" is not the answer either:

• The rule declines on a vertical wall panel because it is only confirmed for horizontal ones. Global elevation is the mechanism that is sound for a piece erected on end — its two ends really are at different heights — so on that decline the fallback is the right tool for the case the rule handed over, not a guess.
• It is meaningless for a piece erected long-ways, and that case never reaches here: MIN_VERTICAL_SHARE refuses any piece with no axis convincingly up, and the aspect-ratio gate refuses a near-square one.
• It reaches one stage. Stripping and transportation are analysed flat and are invariant under mirroring x — reverse the piece end for end and the beam problem is its own mirror image. Only erection depends on it: which row exclude_top_rows drops, and which edge the anchors are on.

So the fallback answers, and it is stated on every report it touched, naming the rule's own reason for standing down. default_stages gets the same treatment one step further on: an absent source.erected_vertical_axis used to be read as or 'length', and now says so in problems.

Owner questions

Nothing below is inferred and nothing below is guessed at. Numbered so they can be answered out of order.

1. Are the insulated panels designed, and to be checked, as non-composite? The plant's own family description says the pins are non-composite. Confirming it picks which bound the pass/fail line is drawn against; the report carries both either way.
2. Which wythe is structural? The thickest is assumed, by trade convention, and named as an assumption every time. A ruling makes it a fact.
3. Is the architectural wythe to be relied on in flexure at all, or carried by the connectors and resisting nothing? The two readings differ by 768 in³ against 683 in³ on the reference piece.
4. What depth should the beam use once the refusal is lifted — the envelope, one wythe, or a bounded pair? This is the question docs/lift-check.md has been carrying as open since 2026-08-31, and the bounds are now computed for all three so it can be answered against numbers.
5. Connector capacity per failure mode — interface shear, and normal/tension — in lb per connector, and the concrete strength the ratings were derived at.
6. Connector slip stiffness k, lb/in per connector. Without it there is no ratio and no end-concentration factor, and both stay stood down.
7. Do the openings run through both wythes on every piece? Assumed yes; the measured plan areas on the reference piece agree to ~1%, which is inside the rounding.
8. Is the local thickness axis' minimum face the form face? The layup is measured from the lowest face of any solid the body draws, which is the same convention the strand and insert z_in already use, and which face that is has never been established. A symmetric layup is the same either way; an asymmetric one may be the mirror of what was cast.