Skip to content

Add primitive_wall reference, tilted-gravity packing strategy, servo … - #12

Merged
d-louw merged 10 commits into
masterfrom
feature_skill_refinements_7
Sep 23, 2026
Merged

d-louw merged 10 commits into
masterfrom
feature_skill_refinements_7

Conversation

@cgoniva

@cgoniva cgoniva commented Sep 18, 2026

Copy link
Copy Markdown
Member

…kp tuning

New references/commands/primitive_wall.md: when to prefer primitive_wall over mesh, and a pointer to its own docs for restrictions (no motion mechanism) and output behavior (no VTK output) -- both since documented directly in primitive_wall.html's own Restrictions section.

STRATEGIES.md: three new entries -- verifying a per-particle-state command actually took effect (mark_particles/define_group/enable_heat_transfer can run with no error while doing nothing), tilting gravity during a non-physical prep phase to pack particles at a target location for free, and mesh_module servo's kp often needing to be much larger than its default to actually reach maximum_velocity.

RULES.md: one-line addition cross-referencing the verification entry above under Simulation Output.

variable.md: merged the existing boolean-only ${name}-nesting warning with a newly confirmed equal-formula case (same underlying bug, extends to equal/atom/boolean formulas alike) into one section instead of two.

…kp tuning

New references/commands/primitive_wall.md: when to prefer primitive_wall
over mesh, and a pointer to its own docs for restrictions (no motion
mechanism) and output behavior (no VTK output) -- both since documented
directly in primitive_wall.html's own Restrictions section.

STRATEGIES.md: three new entries -- verifying a per-particle-state command
actually took effect (mark_particles/define_group/enable_heat_transfer can
run with no error while doing nothing), tilting gravity during a
non-physical prep phase to pack particles at a target location for free,
and mesh_module servo's kp often needing to be much larger than its
default to actually reach maximum_velocity.

RULES.md: one-line addition cross-referencing the verification entry above
under Simulation Output.

variable.md: merged the existing boolean-only \${name}-nesting warning with
a newly confirmed equal-formula case (same underlying bug, extends to
equal/atom/boolean formulas alike) into one section instead of two.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
@cgoniva
cgoniva requested a review from d-louw September 18, 2026 12:43
d-louw and others added 9 commits September 23, 2026 09:54
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
The previous version was a single line pointing at doc sections that
don't actually contain the claims made about them (Restrictions is
empty, not /). Replace it with an
overview of what primitive_wall covers (plane/cylinder/disk shapes,
the shear keyword's surface-velocity-only behavior, restart/output
notes), soften the unverified VTK-output claim to a flag rather than
an assertion, and add the missing SKILL.md Guidelines link per
CLAUDE.md's requirement that every new commands/<name>.md be linked
there.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Per CLAUDE.md's markdown formatting rule, sentences in RULES.md,
STRATEGIES.md, and variable.md get their own line instead of being
packed together. Also replaces '--' with an em dash to match the
surrounding style.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Basic shape examples taken verbatim from primitive_wall.html, plus
two shear examples (a sheared floor, a rotating-drum cylinder) to
illustrate the surface-velocity-only behavior called out above them.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
The three insertion-related entries (picking a simulate mode for the
insertion style, verifying a pack insertion's target, and the
multi-step rate_in_region recipe for a high cumulative target) are
substantial enough -- the last one is a full numbered walkthrough --
to warrant their own file per CLAUDE.md's rule, same as
MESH_PREPROCESSING.md. STRATEGIES.md now links to INSERTION.md
instead of carrying the content inline.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
It's a way of getting particles into position that's an alternative
to a direct insertion, so it belongs with the other insertion
strategies rather than sitting separately in STRATEGIES.md.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Both entries came out of the same compacted-bed development work
(gravity tilt to place the bed, then servo to compact it further),
and the servo entry's until_settled caveat is the same
convergence-check family as the until_filled/until_settled entry
above it, so it belongs with the other insertion/packing strategies
rather than sitting alone in STRATEGIES.md. Also expands the entry
with why servo compacts a bed and cross-links the until_settled note.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
The rule is about event ordering relative to the last capturing
output write; the entry it pointed to is about verifying a command
took effect at all -- a separate concern. Reword to state the
ordering rule on its own terms (using write_output_timestep instead
of the legacy 'dump' term) and reframe the cross-reference to make
clear why it's related: verification doesn't help if the event ran
after the last write that was meant to capture it.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
…la style

The PR's merge implied equal/atom/boolean formula style was the
deciding factor; the actual distinguishing factor is whether the
formula is a quoted string, per user testing:

  variable y equal 1-${x}     # valid, immediate substitution
  variable y equal "1-${x}"   # invalid
  variable y equal 1-v_x      # valid, dynamic
  variable y equal "1-v_x"    # valid, dynamic

Restores the 'known Aspherix bug, not a workaround' framing and the
concrete boolean example that the PR's merge had dropped, and adds
the quoted/unquoted equal example to make the actual rule explicit.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
@d-louw

d-louw commented Sep 23, 2026

Copy link
Copy Markdown
Contributor

Pushed a follow-up round of fixes on top of the original commit:

  • primitive_wall.md: rewrote it from a one-line stub into a real reference (what it's for, what it can't do — no motion mechanism, shear is surface-velocity only — shape/keyword overview, restart/output notes) and linked it from SKILL.md's Guidelines, per CLAUDE.md. Added an Examples section (verbatim shape examples from the docs, plus sheared-floor and rotating-drum shear examples). Also softened the "no VTK output" claim to a flag-for-verification since it isn't actually in the docs' Restrictions section (which just says "none").
  • STRATEGIES.md: moved the "verify a per-particle-state command" entry below the file's own intro paragraph (it had landed above it). Pulled the insertion-related entries (until_filled/until_settled mode choice, verifying a pack target, the rate_in_region recipe) plus the tilt-gravity and mesh_module servo kp entries into a new references/strategies/INSERTION.md, since the tilt-gravity and servo entries turned out to be notes from the same compacted-bed workflow and the rate_in_region recipe is a full walkthrough — same pattern as the existing MESH_PREPROCESSING.md.
  • RULES.md: the new dump-ordering line pointed at a strategy entry about a different failure mode (verifying a command took effect vs. ordering relative to the last output write). Reworded so the rule stands on its own (using write_output_timestep instead of the legacy "dump" term) and reframed the cross-reference to explain why they're related.
  • variable.md: the merged nesting-rule section implied equal/atom/boolean formula style was the deciding factor for when ${name} fails; it's actually whether the formula is a quoted string, confirmed against:
    variable y equal 1-${x}     # valid
    variable y equal "1-${x}"   # invalid
    variable y equal 1-v_x      # valid, dynamic
    variable y equal "1-v_x"    # valid, dynamic
    
    Restored the "known Aspherix bug" framing and the concrete boolean example that the merge had dropped, and added the quoted/unquoted example to make the actual rule explicit.
  • Reflowed all new prose to one sentence per line per CLAUDE.md's formatting rule, and fixed -- to match the surrounding style.

@d-louw
d-louw merged commit 5275148 into master Sep 23, 2026
d-louw added a commit that referenced this pull request Sep 23, 2026
It was a new top-level heading holding a single entry, on the same
theme as the existing Cross-script Parameter Consistency section
(state leaking across a restart split) -- move it there instead.
While there, fix that section's now-stale claim that ${name} always
crashes at evaluation; per the quoting fix landed in variable.md via
#12, only a *quoted* ${name} fails.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
d-louw added a commit that referenced this pull request Sep 23, 2026
* Add multi-phase restart/output hygiene notes, servo center_of_mass caveat

RULES.md: two new entries under Command Ordering/Simulation Output --
only declare a physics setting (e.g. heating) in the script phase that
actually needs it, since a packing/prep phase split off via
write_restart/read_restart can silently inherit one left over from an
earlier script version; and give each named script its own
output_settings folder, clearing it (not just the restart file) before
rerunning outside a full clean, since Aspherix renumbers rather than
overwrites colliding step files with no error.

STRATEGIES.md: two new entries -- mesh_module servo's center_of_mass
must track the pushed body's actual current position when the same
piston geometry is reused across scripts/restarts, since the mesh's
imported STL coordinates don't update on their own; and only
regenerate a restart when the phase that produced it actually needs to
change, since re-running an earlier phase unnecessarily wastes
wall-clock time on an expensive DEM/CFD case.

SKILL.md: link primitive_wall.md from the Guidelines list (it existed
but wasn't linked).

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

* Fold Known Silent-Failure Traps into Cross-script Parameter Consistency

It was a new top-level heading holding a single entry, on the same
theme as the existing Cross-script Parameter Consistency section
(state leaking across a restart split) -- move it there instead.
While there, fix that section's now-stale claim that ${name} always
crashes at evaluation; per the quoting fix landed in variable.md via
#12, only a *quoted* ${name} fails.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

* Group the two mesh_module servo entries under a compaction header

kp tuning and center_of_mass tracking are both about the same
mesh_module servo bed-compaction workflow, so nest them as
subheaders under one 'Compacting a bed with mesh_module servo'
header instead of two flat, redundantly-titled entries.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Sonnet 5 <noreply@anthropic.com>
Co-authored-by: Daniel Louw <daniel.louw@dcs-computing.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants