sofistik-dynamo

# SOFiSTiK Dynamo Script Builder Build Dynamo `.dyn` graphs that target the **Revit Dynamo Player** workflow: input nodes feed parameters at the top, the graph runs, output (Watch) nodes display the result. Simple data flow lives in Dynamo nodes; non-trivial logic lives in CPython3 Python Script nodes inside the graph. ## Core principles 1. **Plan first, then build.** Never start emitting JSON before the user has approved a plan. Dynamo graphs cannot be partially fixed in chat — a wrong shape means the file won't open in Revit. 2. **One graph = one job.** If the user describes two unrelated jobs (e.g. "select walls AND export reactions"), suggest splitting them. 3. **Logic in Python, plumbing in nodes.** Use Zero-Touch nodes for selection, package calls (SOFiSTiK), parameter reads/writes, and Watch outputs. Use a Python Script node any time logic exceeds a single function call (filtering, transforming, transactional Revit modifications, regex, joins beyond `Utils.TableLeftJoin`, anything iterative). 4. **Player-friendly.** Inputs that the user is meant to set in the Dynamo Player must be marked `IsSetAsInput: true` — but **only** when the user explicitly asks for that parameter to be a Player input. By default, leave `IsSetAsInput: false`. Watch nodes that should display in Player are marked `IsSetAsOutput: true`. 5. **Always unwrap.** Inside Python nodes, every Revit element coming through `IN[i]` must be passed through `UnwrapElement(...)` before `.Id`, `.get_Parameter`, etc. 6. **Revit 2024+ `ElementId`.** Always use `el.Id.Value` (Int64), never `el.Id.IntegerValue` — the latter was deprecated in Revit 2024 and throws on modern projects. The builder's `add_python` rejects code containing `.IntegerValue`. See `references/python_node.md` → "Revit 2024+ API breaking changes" for the full migration table. 7. **Convert units at the SOFiSTiK ↔ Revit boundary.** Revit stores lengths in feet, forces in non-standard internal units, etc. SOFiSTiK `.cdb` results come in metres and kilonewtons. Any Python node that *writes* a SOFiSTiK value to a Revit element must wrap it in `UnitUtils.ConvertToInternalUnits(value, UnitTypeId.Meters/Kilonewtons/...)`; any node that *reads* a Revit value to compare with SOFiSTiK must use `ConvertFromInternalUnits`. The builder's `add_python` warns when a script touches Revit element data without any conversion call. See `references/python_node.md` → "Units — converting between SOFiSTiK and Revit" for the unit table and patterns. ## Workflow — follow these steps in order ### Step 1: Capture intent Ask only what's necessary. The minimum you need before drafting a plan: - **What is the script's job?** One sentence. Read / modify / export? - **What's the input?** Selection in Revit, all elements of a category, a path to a `.cdb` or `.xlsx`, a parameter name, etc. - **What's the output?** A modified model, a Watch that shows a list, an Excel file, a created Revit element? - **Which inputs should appear in the Dynamo Player?** Don't assume — ask. The user told you their convention: `IsSetAsInput` is set **only on request**, per parameter. - **Does it touch SOFiSTiK results?** If yes, where does the `.cdb` come from — currently active view, a fixed path, or a user-supplied path? If the user's prompt already contains all of this, skip to Step 2. ### Step 2: Propose a plan and wait for approval Write a plan in this exact format and stop. Do not write any `.dyn` JSON yet. ``` ## Plan: <script name> **Job:** <one sentence> **Input group** (left side of graph) - <node 1 — e.g. "String input 'Parameter name' (Player input: yes)"> - <node 2 — e.g. "File path to .cdb (Player input: yes)"> **Processing group** (middle) - <node — e.g. "All Elements of Category: OST_AnalyticalMember"> - <Python node: <what it does in one line>> - <SOFiSTiK call: Model.CreateByActiveView → Results.GetSupportForces> **Output group** (right) - <Watch node "Filtered elements" (Player output)> **Files this skill will produce:** `<name>.dyn` (and a separate `<name>.py` reference copy of any Python code longer than ~30 lines, for easier review) **Open questions:** <only if any> ``` Then ask: *"Does this plan look right? Any changes before I build the .dyn?"* For complex graphs (more than ~10 nodes, multiple Python nodes, or anything the user calls out as tricky), instead of building everything at once, present a **TODO list** in the plan and offer to walk through it step-by-step. Example: ``` This is a larger graph. I suggest building it in steps: - [ ] Step 1: Set up inputs (paths, parameter names) and the SOFiSTiK Model node - [ ] Step 2: Pull support forces and join with element GUIDs - [ ] Step 3: Python filter for max reactions per support type - [ ] Step 4: Watch outputs and Player input flags Which step should we tackle first, or shall I draft step 1? ``` ### Step 3: Build the `.dyn` After approval, use the build helper rather than hand-writing JSON. See `scripts/build_dyn.py` and the canonical schema in `references/dyn_schema.md`. Workflow: 1. Read `references/dyn_schema.md` once if it isn't already in context — it is the source of truth for the Dynamo 3.x JSON shape. 2. For any SOFiSTiK call, look up the exact `FunctionSignature` and port names in `references/sofistik_api.md`. 3. For Python nodes, start from the boilerplate in `references/python_node.md` (Revit imports, DocumentManager, transaction pattern, `UnwrapElement`). 4. Pick the closest template in `assets/templates/`, copy it to `/home/claude/<workspace>/build_<n>.py`, and adapt. Builder API: - `g = DynGraph(name=..., description=...)` — start a graph. - `g.add_string_input(value, label, x, y, player_input=False)` — string input. Set `player_input=True` only when the user explicitly asked for that parameter to appear in the Player. - `g.add_filename(value, hint_path, label, x, y, player_input=False, external_label="my.xlsx")` — file path input. `external_label` adds it to `NodeLibraryDependencies` as External. - `g.add_boolean(...)`, `g.add_integer_slider(...)` — other Player inputs. - `g.add_zero_touch(function_signature, in_ports=[(name, desc), ...], out_ports=[...], x, y, sofistik=True/False)` — any .NET function call. Set `sofistik=True` for any `SOFiSTiK.*` signature. - `g.add_zero_touch_varargs(...)` — for `List.Join` and similar variadic functions. - `g.add_python(code, n_inputs, x, y, label)` — CPython3 Python node. Pass `code` with normal `\n` line breaks; the builder normalizes. - `g.add_watch(label, x, y, player_output=False)` — Watch. `player_output=True` makes it a Player output. - `g.add_categories(selected="OST_...")`, `g.add_elements_of_category()`, `g.add_select_model_elements(category=...)` — common Revit selectors. - `g.connect(src_node, "src_port", dst_node, "dst_port")` — wire two ports. For single-port nodes (StringInput, Watch) pass `""`. - `g.group("Title", [nodes...], color="input"|"processing"|"output"|"sofistik")` — group annotation with the convention from `dyn_schema.md`. - `g.mark_player_input(node, label)`, `g.mark_player_output(node, label)` — toggle Player flags after the fact. - `g.validate()` returns a list of structural problems; should be `[]` before saving. - `g.save(path)` writes the `.dyn`. 5. Run the build script. Always assert `g.validate() == []` before `g.save(...)` — catches unwired ports, unknown port refs, missing display names. 6. Save to `/mnt/user-data/outputs/<n>.dyn`. If any embedded Python is longer than ~30 lines, also save a standalone `<n>.py` next to it so the user can review/edit Python without opening the JSON. 7. Present the file(s) with `present_files`. ### Step 4: Hand off End with a short summary of: - What the script does - Which nodes are Player inputs/outputs (be explicit if none) - Any manual step the user must do in Revit (e.g. "open the script in Revit, click 'Run' once to verify, then it will show in Dynamo Player") - Known limitations (e.g. "the SOFiSTiK package version is pinned to 2026.5.0 in NodeLibraryDependencies — adjust if your install differs") ## Reference files Read these as needed; they are the source of truth. - `references/dyn_schema.md` — Dynamo 3.x `.dyn` JSON schema: top-level keys, node `ConcreteType`s, port/connector wiring, NodeView geometry, group annotations, the `IsSetAsInput`/`IsSetAsOutput` mechanism, the Inputs/Outputs declarations. - `references/sofistik_api.md` — Quick reference for the SOFiSTiK Analysis + Design Zero-Touch nodes: `Analyze`, `Model`, `Results`, `Reinforcement`, `Design`, `Utils`, `Export`. Lists exact `FunctionSignature` strings and return-tuple column indices. - `references/python_node.md` — CPython3 boilerplate for Python Script nodes: Revit API imports, DocumentManager pattern, transaction handling, `UnwrapElement`, common pitfalls (level changes, list-vs-single inputs, returning `OUT`). - `scripts/build_dyn.py` — Python builder. Use this rather than hand-writing JSON. Has docstrings for every method. - `assets/templates/` — Four runnable starter scripts that exercise every feature of the builder. Read the one closest to the user's task, copy it, then adapt: - `template_minimal.py` — one Player input → Python → Watch (the "hello world"). - `template_read_results.py` — `Model.CreateByActiveView` → `Results.GetSupportForces` → 3 Watch outputs (the canonical SOFiSTiK results-reading pattern, no unit conversion needed because data stays inside SOFiSTiK). - `template_modify_revit.py` — bulk parameter set with a transactional Python node (the canonical write-to-Revit pattern, including `UnwrapElement` and `TransactionManager`; sets a string parameter so no unit conversion is needed — see the inline note for how to adapt to numeric values). - `template_sofistik_to_revit_units.py` — read column normal force from SOFiSTiK and write it onto the matching Revit column with the **correct `UnitUtils.ConvertToInternalUnits` boundary conversion**. This is the canonical SOFiSTiK-results → Revit pattern; copy this whenever a Python node needs to push a numeric SOFiSTiK value back into Revit. ## Triggering anti-patterns Don't use this skill for: - Pure Revit API questions with no Dynamo involved (just answer them directly). - Reading existing `.dyn` files to explain them — you can do that with `view`/`bash` directly without the builder. Do use it for: - Anything that ends with "...and save it as a .dyn". - Iterating on an existing `.dyn` the user uploaded — read it, propose a diff plan, then rebuild affected sections with the builder.