CitySim Docs
Fall 2026
API

# Simulator

o1.city.Simulator
class Simulator

A `Simulator` object is a city simulator based on Schelling’s model of emergent social segregation. Its key methods are `startNew`, which launches a new simulation, and `moveResidents`, which advances the most recently launched simulation by moving dissatisfied residents into vacant homes. A selection of other methods is also provided for examining the state of the simulation.

As implied above, a `Simulator` is mutable: Calling `startNew` causes the simulator to discard any previously active simulation and start processing a new one. Calling `moveResidents` modifies the state of the active simulation.

## Attributes

Graph
Supertypes
  class Object
  trait Matchable
  class Any

## Members list

### Value members

#### Concrete methods

def allAddresses: Vector[GridPos]

Returns all the locations in the city being simulated.

Returns all the locations in the city being simulated.

## Attributes

def currentMap: CityMap

Returns the city currently being simulated.

Returns the city currently being simulated.

## Attributes

def dissatisfiedResidents: Vector[GridPos]

Returns the locations of all dissatisfied households in the city. A household is dissatisfied if it does not have a sufficient proportion of neighbors that share its demographic. For example, if the city-dwellers desire a similarity of 50%, at least four of a household’s eight neighbors need to share its demographic or it will be dissatisfied. (Dissatisfied residents will move when moveResidents is next called.)

Returns the locations of all dissatisfied households in the city. A household is dissatisfied if it does not have a sufficient proportion of neighbors that share its demographic. For example, if the city-dwellers desire a similarity of 50%, at least four of a household’s eight neighbors need to share its demographic or it will be dissatisfied. (Dissatisfied residents will move when moveResidents is next called.)

When determining a household’s neighbors, diagonally adjacent grid locations count, and many households will have a full eight neighbors. However, `Vacant` locations don’t count as neighbors, nor do locations that are beyond the edges of the grid. A corner location, then, will only have a maximum of three neighbors, less if any of the three locations are vacant.

For example, consider a non-vacant corner location. There are three locations next to it on the grid. If one of them shares the corner’s demographic, another doesn’t, and the third one is vacant (and therefore ignored), then 50% of the corner’s two neighbors are similar to the corner.

Vacant locations are never returned by this method (i.e., they count as satisfied). Any household with zero neighbors is considered to be satisfied.

## Attributes

def findDemographic(`demographic`: Demographic): Vector[GridPos]

Returns all the locations in the city that contain the given demographic.

Returns all the locations in the city that contain the given demographic.

## Attributes

def moveResidents(): Unit

Advances the most recently launched simulation by one step, moving all dissatisfied households to vacant locations on the grid. During the simulation step, the dissatisfied households move one at a time, in random order, each receiving a random home among the ones that are vacant at that moment. (That is, a household may move to a home vacated by another dissatisfied household earlier during the same simulation step.)

Advances the most recently launched simulation by one step, moving all dissatisfied households to vacant locations on the grid. During the simulation step, the dissatisfied households move one at a time, in random order, each receiving a random home among the ones that are vacant at that moment. (That is, a household may move to a home vacated by another dissatisfied household earlier during the same simulation step.)

Satisfied residents stay where they are. If a satisfied resident becomes dissatisfied during this simulation step (because others move), that does not cause them to move (yet).

Example: Suppose X and Y are residents that neighbor each other. Further suppose that X is satisfied and Y is dissatisfied when `moveResidents` is called to advance the simulation by one step. This means that Y will move to a random location. X, on the other hand, will not move during that `moveResidents` call, no matter what happens in X’s neighborhood. X will only move the next time `moveResidents` is called, if X is dissatisfied at that time.

If there are no vacant addresses at all in the city, this method does nothing.

## Attributes

See also

  dissatisfiedResidents

  startNew

def residents: Map[Demographic, Vector[GridPos]]

Returns a `Map` whose keys are all the demographics present in the city (Vacant included) and whose values list all the locations where that demographic is present.

Returns a `Map` whose keys are all the demographics present in the city (Vacant included) and whose values list all the locations where that demographic is present.

Note to students: This method will be implemented only in Chapter 10.1. You won’t need it before that.

## Attributes

def satisfactionLevel: Double

Returns the proportion of satisfied residents in the city. For example, a return value of 0.0 means that nobody is satisfied, 1.0 that everyone is, and 0.95 that most are.

Returns the proportion of satisfied residents in the city. For example, a return value of 0.0 means that nobody is satisfied, 1.0 that everyone is, and 0.95 that most are.

## Attributes

See also

  dissatisfiedResidents

def startNew(`squaresPerSide`: Int, `fillPercent`: Int, `demographics`: Vector[Occupied], `occupiedRatio`: Int, `similarityDesired`: Int): Unit

Launches a new simulation. The simulation will take place on a newly initialized city grid as specified by the parameters provided. After calling this method, moveResidents will advance the newly launched simulation; any previously ongoing simulation is simply discarded.

Launches a new simulation. The simulation will take place on a newly initialized city grid as specified by the parameters provided. After calling this method, moveResidents will advance the newly launched simulation; any previously ongoing simulation is simply discarded.

## Parameters

demographics

  the demographics that populate the non-vacant residences; the first element of the collection is the “main” demographic

fillPercent

  the percentage of residences that have a resident and are not vacant (between 0 and 100)

occupiedRatio

  the percentage of non-vacant residences occupied by the “main” demographic (between 0 and 100); the remaining residences are evenly split between the other demographics

similarityDesired

  the minimum percentage of neighboring residences that must match a household’s demographic in order for the household to be satisfied (between 0 and 100)

squaresPerSide

  the number of residences in each row and column (the city grid is always square)

## Attributes