# Example 3: Simple Harmonic Motion

An agent-based approach to simple harmonic oscillator model. Agents are contained within a cell matrix.

## Viewing this model in Nova

To run this model:

1. Launch Nova
2. Select Menu Item File | Browse Model Library
3. Open folder 5-Agent-Based Models and double-click shm

Error creating thumbnail: File missing

The simple harmonic oscillator model is a Sim World model that defines agents and cells in submodels or sublayers. The agents are balls that oscillate back and forth at a fixed frequency with a changing phase as you move down in the y dimension. The cells get worn away as the agents continue to tread over them. By changing the initial size you can get multiple different balls at different phases at the same x value. Motion has a stable period along the x axis. This is a very useful model for seeing the simple interplay between agents and cells. The agents have a relatively simple method for movement and the cells have a simple method of erosion. This is a good model for getting a feel for the visual side of agent based models - before they begin to get more complex with lots of methods and properties.

## Model Components and Layers

### World SimWorld

This model provides a great example of using the SimWorld Component. SimWorlds use both AgentVectors and a CellMatrix where the Agents exist within a space defined by the CellMatrix. The CellMatrix is either a two-dimensional cartesian or hexagonal topology.

Right click on the SimWorld to see its Properties. We can see that we are calling `10` instances - or Counts- of ball. Also notice that the motion within this World is Continuous rather than Discrete. Each agent's behavior is determined by properties defined in the ball sublayer. On the other hand, the actual World that these agents live in is defined by the cell sublayer. In other words: the `green` part of the SimWorld is the agent section, determined by the ball sublayer. The `purple` part of the SimWorld is the cell section, determined by the cell sublayer.

### The cell Sublayer

We can look into the cell sublayer to see the properties that determine the CellMatrix aspect of the World (SimWorld) at the top-layer. In the occup term we call `MYAGENT_COUNT()`, a SimWorld Primop. This Primop returns the number of agents within the current caller, or cell. This allows the trample Flow to determine the grass Stock. We can see that grass Stock is passed to the grass_1 output Pin. At the top-layer this output determines the CellColorIn of the AgentViewerX.

### The ball Sublayer

Finally, we can look at the ball sublayer to determine the behavior of each agent at the top-layer. This sublayer contains two Flows, acceleration and velocity_1, which determine the values of two Stocks, velocity and position, respectively. The term k utilizes the `myId` Primop, which is bound to the caller's `id` within the World SimWorld at the top-layer. We can see that the acceleration Flow takes the current position and determines the velocity Stock which, in turn, determines the next value of position through the velocity_1 Flow. Lastly, the move Command uses the `MOVE(x, y)` AgentVector Primop. Thus, the agent moves to the position (x, y) that is specified by the move Command.

## Running the model

To run this model follow these steps:

Running this model:

1. Click on the Capture button in the tool bar.
2. Click Load next to “Capture.”
3. Click Exec to run the model through multiple iterations. Click Stop to stop the run before completion.
4. To run the model step by step, click Capture, Load, Init, then Step.
5. To rerun the model you may omit the Capture, Load steps.
6. To have the model run more slowly adjust the speed slider above the Dashboard.