DSL basics

The PhysLoom DSL describes a physical model, not an SVG. A model usually contains five layers of information: a scene, entities, connections, physical parameters, and presentation requests.

Scenes

Every model begins with scene:

scene inclined_plane {
  // entities and relationships
}

The scene name identifies the model. It does not automatically become the visible title.

Entities

Entities are objects in the model. Common entities include body, support, pulley, surface, spring, charge, and circuit elements.

body crate mass=8kg
support ceiling
surface ramp angle=30deg
spring S stiffness=120N/m

Keep identifiers short and unique. Reader-facing labels can be set separately, so an identifier does not need to contain a sentence.

Connections and paths

Connections state how objects relate. A rope uses an ordered path: the order is what you meet while following the rope from one end to the other.

pulley P fixed to ceiling
rope R path body(A) -> around(P) -> body(B)

around(P) means more than drawing a line through the pulley. It requires tangent contact with the rim and includes the pulley in the rope-length constraint.

Parameters and units

Numbers should carry units:

Quantity	Example
Mass	mass=2kg
Distance	distance=0.5m
Angle	angle=30deg
Stiffness	stiffness=120N/m

The compiler normalizes units before solving. Do not replace units with names or hide 1kg in a display label to avoid a model parameter.

Presentation requests

show statements decide what the reader sees. They must not change the physical model:

show tension
show displacement
show force_diagram

Tension, displacement, and the free-body diagram come from the same solution. Hiding them makes the page quieter; it does not alter the rope constraint or force balance.

When to specify layout

Let the layout engine find a clear, non-overlapping arrangement first. Add a layout hint only when the problem truly depends on a particular composition. Prefer relative intent such as “to the right” or “keep vertical” over absolute pixels tied to one screen.

The boundary matters: the model states physical facts; layout states how to see them clearly.