Model recipes

The language reference answers “which words exist.” This chapter shows how those words form models. Every complete scene below can be pasted into Studio. Declare entities, connect their physical roles with structural lines or named models, then request motion and visible results. Only the common on relationship can be included in an entity declaration. Model names must be unique among entities and models.

Mechanics: how a body moves

A projectile needs a surface, a body, and an initial-motion relationship. animate asks the solver to evolve the state in physical time. show chooses which solved results appear.

scene projectile_flight

surface ground horizontal
body ball 1kg shape=point
launch flight body=ball origin=ground speed=20m/s angle=45deg

animate ball speed=0.72
show ball ball.path

Inclines, collisions, orbits, and oscillators keep this structure while changing the entities and physical models.

body crate 1kg on ramp places a one-kilogram body on a ramp. For a rolling sphere, declare body ball 1kg shape=sphere radius=6cm, then write rolling roll body=ball surface=ramp mode=without_slipping. Entity parameters and model parameters remain separate. In the projectile example, 1kg is the body’s mass, while speed=20m/s and angle=45deg belong to the launch. Named properties can appear in either order.

For a continuous route, trajectory route body=block stages=(ramp, floor, S) transition=lossless lists the smooth incline, rough horizontal run and anchored spring in travel order. animate block ends at the first stop or maximum compression; floor.length is the distance before spring contact, and friction continues during compression. The lossless bend preserves speed but does not simulate a corner collision. Declare the slider separately with body block 1kg shape=point. The parentheses group the repeating stages role in travel order. Referenced entities may be declared later in the scene. Explore the complete ramp-to-spring problem and change friction to compare compression with stopping before the spring.

Circuits: how components connect

<-> continues a series route. <=> creates parallel branches. The compiler generates hidden ports and nodes, so an ordinary circuit does not start with abstract node declarations.

scene parallel_circuit

source V 12V
resistor R1 100ohm
resistor R2 200ohm

V <-> (R1 <=> R2) <-> V

The default diagram contains only the source, components, and wires. Add show R1 R2 when teaching Ohm’s law or current division; this requests each component’s default electrical details. Add animate V speed=1 only for a lesson about conventional-current direction. Current tracing is an optional teaching overlay, not the default circuit style.

Switch state belongs to the model source. After open or closed changes, Studio parses and solves the circuit again. The diagram presents the state described by the source rather than acting as a second editing surface. A lamp’s two positional values are its rated voltage and rated power; the parser matches them by physical dimension, so lamp L 6V 3W and lamp L 3W 6V mean the same thing. Color sets the light hue, while brightness comes from solved electrical power.

scene switched_colored_lamp

source V 6V
switch S closed
lamp L 6V 3W #gold

V <-> S <-> L <-> V

This example stays focused on the state change caused by the switch: an open switch gives zero current and a dark lamp; closing it solves the circuit again and sets brightness from actual power. It does not show current markers, direction arrows, or branch readouts by default. Add show L for the lamp’s electrical details, and animate V speed=1 only for a lesson specifically about conventional-current direction.

The current lamp model uses its rated operating point, with hot resistance R = V² / P. It is intended for introductory DC diagrams and does not claim to simulate nonlinear filament warm-up.

Introductory circuits are usually better compared as explicit model states than presented as moving current dots. A rheostat’s position is the effective-resistance fraction of its maximum value. Changing this source parameter solves the network again and changes lamp brightness.

scene rheostat_lamp_control

source V 6V
rheostat R 18ohm position=50%
lamp L 6V 3W #gold

V <-> R <-> L <-> V

A short circuit is likewise a state to compare. The switch below is parallel to the lamp; closing it bypasses the lamp. The limiter keeps the ideal source from being shorted by an ideal wire, so both switch states remain solvable.

scene lamp_bypass_short

source V 6V
resistor limiter 1ohm
lamp L 6V 3W #gold
switch S open

V <-> limiter <-> (L <=> S) <-> V

Optics: what light meets

The optical path names its participants in order: the laser passes from air into glass. Their declared kinds identify refraction. Reflection, refraction, and total internal reflection share one optical state as the incidence angle changes.

scene snell_refraction

medium air refractive_index=1
medium glass refractive_index=1.5
light laser role=ray #red

laser -> air -> glass incidence_angle=20deg

animate laser incidence_angle=60deg duration=3s speed=1
show laser laser.normal

A thin-lens scene can name a familiar visual subject directly. object candle draws a candle and uses the solved image inversion and magnification to draw its image. Its appearance does not participate in the lens calculation.

scene thin_lens_image

object candle 4cm
lens L converging 10cm

candle -> L object_distance=30cm

animate candle object_distance=15cm duration=3s speed=1

When the entity name and appearance should differ, write object specimen height=4cm subject=candle. Later relationships still refer to specimen; subject selects only its visual subject. The same physical model can therefore use another diagram theme or subject skin without changing its relationships or solved results.

Here 4cm is object height, 30cm is object distance, and 10cm is focal length. They belong to separate declarations or relationship lines, not one positional list of lengths. The arrow is valid because the declared object and lens identify one physical relationship. An explicit equivalent is imaging view object=candle optic=L object_distance=30cm. Use named models when participants do not uniquely determine an arrow’s meaning. Named name=value properties remain core syntax when a value cannot bind uniquely.

Reflection, lenses, prisms, interference, and traveling waves use the same entity + relationship + observation structure.

Electromagnetic fields: what a particle crosses

The structural in line can name several fields. Direction and magnitude belong to the field or particle rather than to separate drawing commands.

scene crossed_field_velocity_selector

particle electron charge=-1e direction=right #red
field E type=electric electric_strength=20kV/m direction=down #blue
field B type=magnetic magnetic_strength=10mT direction=into_page #green

electron in E, B length=20cm

animate electron speed=3.3e-8
show electron

Thermal physics and fluids: transfer and state

A heat engine connects two reservoirs through an energy cycle:

scene carnot_cycle

reservoir hot temperature=600K
reservoir cold temperature=300K
engine motor efficiency=0.4

cycle engine_cycle engine=motor hot=hot cold=cold

show motor motor.efficiency

A buoyancy model places a body in a fluid. Density, mass, and volume determine the equilibrium state together:

scene floating_body

fluid water density=1000kg/m3
body block mass=1kg volume=0.002m3

equilibrium floating_state body=block fluid=water

show block.buoyancy block.gravity

For small vertical oscillations, put the initial position on the body/fluid relation:

scene buoyant_small_heave

fluid water 1000kg/m3
body block 1kg volume=0.002m3 area=0.02m2

equilibrium floating_state body=block fluid=water initial_displacement=1cm

animate block speed=0.15
show block.buoyancy block.gravity water.waterline

initial_displacement=1cm means 1 cm above equilibrium, starting from rest; -1cm means below it. Removing animate keeps that initial position and its buoyancy. Zero displacement stays still. This example observes one natural cycle (about 0.449 s); speed=0.15 plays it at 0.15x speed, about 2.99 screen seconds. Legacy action-only amplitude remains supported, but cannot override a conflicting initial displacement.

Modern physics: events and energy relationships

A modern-physics scene may not look like a classical machine, but it still names entities and a physical relationship. Here a photon releases an electron from a metal, and the work function belongs to that emission relationship:

scene photoelectric_effect

particle photon energy=4.5eV
body metal material=sodium
particle electron

photoelectric emission incident=photon material=metal emitted=electron work_function=2.3eV angle=35deg incident_distance=3.40787507337368um

animate electron until electron.displacement == 10nm speed=7.6e-15
show electron electron.energy

incident_distance sets the photon’s initial distance from the metal. The animation’s displacement sets how far to observe the emitted electron; changing it does not move the photon or change its arrival time. Removing animate keeps the initial distance in the static model. Existing files without incident_distance retain their legacy timing.

Color and custom paths

An entity suffix such as #red or #blue changes visual emphasis only. Ordinary pulley routes are inferred. Declare a rope only when its topology or segment colors need explicit control:

rope R #gray
R: ceiling -[#red]-> M -> F -[#blue]-> R.free

This is a path fragment, not a complete scene. R.free is the built-in free end of R. Use the language reference for every property and color, or open a working model from Examples.