pysims reference

Every name a program can say, one line each, in the order a student meets them. The engine knows position, velocity, mass and time. It does not know energy, momentum, period, range or a coefficient of anything: those are one line of your own Python.

Start

from pysims import sim, Ball, Box, Segment, Curve, Spring, Pin, Rope, Pulley, Pivot, Label, Agent, Grid

Defaults are shown as name=value. Name your arguments. Only the first few of any call can be given by position, and the rest must be written mass=2, not slotted in by counting commas. Writing Ball(0, 5, 0.3, 2) and meaning a mass of 2 is an error, and the page will say so.

The page shows where a program starts before it runs. Reset the scene, beside Stop (Ctrl+Shift+Enter), shows it again for the code as it is written now, without running it.

The loop

Settings

sim.digits changes what is shown, in a graph's readout, a monitor and the readout under the pointer. The run keeps every figure it worked out, and so does sim.data. The clock is the exception, because sim.dt already says what a time is worth: a step of 0.1 makes tenths and they are shown as tenths whatever this is set to.

Bodies

x and y are always the center. Every body takes color, and any attribute you care to set on it (ball.team = "red" just works). name is only what its columns are called: see Data.

A Segment and a Curve are fixed scenery, so of that list they take only bounce, friction, layer, color and name. Giving one a mass or fixed=False is an error: they have no mass. A Segment also takes the vx, vy, belt and sensor of the rows above; a Curve takes none of the four and raises if it is given one.

Layers are the whole rule and there is no exception to them. Two pendulums on layers 1 and 2 swing through each other; a floor on layer 0 stops layer-0 things and nothing else. Pins and springs have no layer, and sim.near ignores layers because finding is not touching.

Rolling

On ground that grips it, a rolling ball spends part of its drop on spinning, so it reaches the bottom slower than one that slides: a sphere at sqrt(1/1.4) of the speed, a disc at sqrt(1/1.5), a hoop at sqrt(1/2).

A ball rolls because the ground grips it. On a frictionless surface it slides at g sin(theta); with grip of at least 2/7 tan(theta) a sphere rolls without slipping, and below that it slips while the spin catches up. Rolling, it does not rub: friction takes nothing and it swings in a valley for ever, so a lesson about friction wants a puck (roll=False) or a Box. Thrown at a floor it keeps 5/7 of its speed along the ground where a puck stops dead; on a conveyor it rolls along at 2/7 of the belt. It rolls on a Curve, a Segment and a Box alike, keeps its spin through a flight and a bounce, is thrown spinning with spin=, and turns a box it strikes off center if that box turns. The mark drawn on it is the turning, so you can watch it happen.

Curves

Ground with a shape. You write the shape as a function of x and the engine works out the slope at every point. The surface exists only between x0 and x1: past either end there is nothing, and a ball that gets there falls. Balls slide or roll along it; boxes and agents ignore it.

hill = Curve(lambda x: 0.05 * x * x, -10, 10, friction=0.0)
x, y = hill.center(-9, 0.4)
ball = Ball(x=x, y=y, radius=0.4)

The questions below are written curve. and in a program they carry the name you gave the curve, so here they are hill.height(x) and the rest.

A ball only touches the ground directly below it where the ground is straight. On a slope it touches off to one side, which is why there is a center call: height(x) + radius puts the ball slightly into the hillside and the first step shoves it out.

A ball wider than the hollow it sits in would really bridge across and rest higher than the engine puts it. Keep the radius smaller than the bend it has to follow, or the valley gentler than the ball.

Springs and rods

Contact and events

A program that reads sim.keys takes the plain keys for itself, so while it runs the page stops using Space and the arrows for pause and step.

Data

Every ball and box the engine moves gets four columns, named for the body and a dot: ball1.x, ball1.y, ball1.vx, ball1.vy, numbered in the order the bodies were made, and one that turns gets ball1.angle and ball1.spin as well. Ball(..., name="bob") calls them bob.x and the rest instead, which is worth doing when a graph of three balls needs a legend you can read, and is not worth doing otherwise. It is the name in the call and not the variable, because a Python object cannot see the variable it was assigned to. A fixed body and an agent get no columns at all.

Three graphs is the most the panel draws, and it says so in the panel and the console when a fourth is asked for. Several columns on one pair of axes is the way round it.

A fixed body gets no columns, because they would be columns of the same number. An agent gets none either: the record is of the physics, so a model of sheep records what it wants with sim.record. A run longer than 18000 steps is thinned, keeping every tenth step and then every hundredth, so the record always spans the whole run; the steps you recorded something on are kept in full, and a note column appears in the CSV saying what was done.

Controls

A control stays where you put it. Move a slider, press Run again, and the program gets the value on the screen, not the start in the code. It is read before the program's first line, so a slider can decide how a body is made: Ball(mass=heavy.value) works on the second run. The reset button appears in the Controls panel once something has been moved and puts every control back to what the program asks for; so does reloading the page. Changing the start in the code is the third way: a control the program describes differently is a new control, and the program's number wins.

Instruments

Read-only. They draw on the page and change nothing in the run.

Arrows are scaled like a textbook diagram: the biggest one seen so far in the run spans a little under an eighth of the view's width, the rest in proportion. Stepping back walks the run already recorded, because the engine cannot run in reverse.

Sweeps

import math

from pysims import sim, Ball

sim.realtime = False
for degrees in range(10, 81, 5):
    sim.reset()
    speed = 14
    ball = Ball(x=0, y=0, radius=0.3,
                vx=speed * math.cos(math.radians(degrees)),
                vy=speed * math.sin(math.radians(degrees)))
    while sim.running and (ball.vy > 0 or ball.y > 0):
        sim.step()
    print(degrees, round(ball.x, 2))

sim.realtime = False runs as fast as it can. sim.reset() clears the bodies and the record and keeps the settings, so each run starts clean and the loop around them collects one number per run. Make the bodies again inside the loop: reset removed the last run's.

There is no ground in that sweep, on purpose. The stopping rule is the physics question itself, "has it come back to the height it left from", and a floor to bounce off would answer a different question. Add one and the longest throw stops being the 45 degrees the textbook promises, because a shallow throw bounces further.

Agents

A thing with a heading that you move. The engine never touches it: no mass, no velocity, no contact, no gravity. sim.near finds it and sim.wrap carries it across the edge. It is not in sim.data, so record what you want to keep.

Loop over a copy when you remove while looping: for s in list(sheep):. Removing from the list you are walking skips the next one.

Cells

A grid of cells, width by height, each cell meters across, with its bottom left corner at (x, y). Each cell is an object. You write the rule; the page paints the result.

The rule for a cellular automaton reads a copy and writes the grid:

before = g.copy()
for c in before.cells():
    if c.name == "tree" and before.near(c, 1).count("fire") > 0:
        g[c.x, c.y] = "fire"

Without the copy, fire crosses the forest in one step along the scan direction, and Life does not work at all.

Angles

Degrees everywhere, measured from +x, counterclockwise: 0 points right, 90 up. Box(angle=20, fixed=True) tilts up to the right, and so does Curve.angle and an agent's heading.

A program that needs a sine or a cosine uses Python's: math.sin(math.radians(d)), as the projectile in the gallery does. Remember the radians, because math.sin does not take degrees. The package has its own sine and cosine in degrees, used by the engine so that a run comes out the same on every machine, but they are not part of the API and a program cannot import them.