Due Dates

  • Fill out the Project 2 Partner Form by Oct.16th 9pm EST
  • Design Checks Oct. 19th – Oct. 21st
  • Design Check Response and SRC Response due Oct. 21st at 9pm EST
  • Project Code is due Oct. 27th at 9pm EST


We’re taking a quick detour from our Amazing Race to visit Branlex! Like Earth, the planet Branlex (home of the Branlexians) is facing down the prospect of catastrophic anthropogenic (technically branlexogenic) climate change. In this project, you’ll develop components of a graphical climate change simulator and use it to observe the effects of various possible national emissions policies.

Branlexian scientists have determined that its climate is much simpler than that of Earth. On Branlex, there is one molecule that contributes to global temperature increases: the badicule (chemical formula BAd, boron aldebaranide). Temperature on Branlex is directly proportional to the amount of BAd in the atmosphere. Unfortunately, the various nations of Branlex have been emitting BAd into the atmosphere as a product of industrial processes, agricultural processes, and elaborate dance routines. As temperatures on Branlex increase, different nations will respond in different ways. Can Branlex be saved?

The climate change simulator you’re developing will have several components:

  • The graphical display. It runs the simulator and presents a graphical portrayal of Branlex (as shown in the image above!). We’ve provided this for you.
  • The simulator. This is the engine that simulates the process of time on Branlex. It tracks the countries on Branlex and their policies, the amount of BAd in the atmosphere, and the current year, and computes global temperatures. You’ll implement the simulator.
  • Country policies. You’ll implement a number of classes representing different possible policies. Every class will need to implement methods that the simulator calls in order to determine a country’s emissions.

Learning goals

This project will give you experience:

  • Writing code across multiple modules
  • Creating classes and methods
  • Designing interactions between classes
  • Using polymorphism
  • Thinking about the interaction between computing and climate change

Project tasks

  1. Find a partner: Find a partner and fill out the Project 2 Partner Form by Oct.16th 9pm EST. If you would like to have the same partner as Project 1, that is fine! You could also select a new partner if you would like. Regardless of what you decide, you must still fill out that Project 2 Partner Form by Friday. After Friday, you will be paired with a TA and they will send you an email to schedule Design Check, which will be happening Oct. 19th – Oct. 21st. If you’re having trouble finding a partner, please post on Piazza under the post titled “Find Project 2 Partner Thread”!
  2. Read through this document in its entirety!
  3. Setup: Download the project’s stencil code from here.
  4. Design Check: Complete the Design Check questions due by Oct. 21st at 9pm EST
  5. SRC response: See below.
  6. Implement and test the simulator and the Baseline country policy.
  7. Implement and test the rest of the country policies (and make any necessary changes to the simulator).

When writing code, please follow the testing and style guide.

SRC Response

Just like the last project, there will be a Socially Responsible Computing response for Project 2. For this and subsequent projects, we’re asking you to do some short readings on the responsible usage of technology. You’ll write a response to the readings, which will be due with the design check. We’ll read your responses and then anonymously distribute each response to another student, who will then write a response to your response, identifying areas of agreement or disagreement. We’re hoping to foster some thoughtful discussion about the responsible usage of technology.

This project’s responsible computing readings can be found here

Your initial response is due October 21st at 9pm EST

Project components

The project includes several components: the simulator (which you will write), the country policies (which you will write), and the display (which is provided to you).

The simulator

The simulator is implemented as a class Simulator in the simulator.py file. The simulator tracks the amount of BAd in the atmosphere of Branlex and the temperature of each country. The simulator’s advance_year method is called by the display to simulate the passage of a year. The report method is called to generate a report of the countries on Branlex and their current temperatures.

The add_country method

This method is implemented for you in the stencil code. It adds a country’s name to the simulator’s country_names list, and adds its corresponding policy to the simulator’s policies dictionary.

The advance_year method

In the stencil code, advance_year just increments the current year. It will also need to:

  • Reduce the amount of BAd in the atmosphere by 1 ppm, to a minimum of 150 ppm. This simulates BAd being absorbed by natural processes.
  • Calculate each country’s emissions by calling the emit method on each country’s policy, passing any necessary arguments. (More on the emit method later.) Each country’s emissions should be added the BAd total.
  • Calculate the temperature of each country. Country temperatures are calculated as follows:
    • The first country in the country_names list is the northernmost country. Its temperature should be the current BAd divided by 5.
    • Each subsequent country’s temperature should be 5º greater than the previous temperature.
    • For example: if the countries are Canada, the United States, and Mexico and the current BAd is 150 ppm, the countries’ temperatures should be 30º, 35º, and 40º.

If any country’s temperature ever reaches the maximum temperature (self.max_temperature), the simulation should stop updating (i.e., don’t increment the year or update any other state). This represents a failure to avert catastrophic climate change.

The report method

The report method generates a report for the graphical display. It is formatted as a list of hashtables representing country data (which should be in the same order as the simulator’s country_names list). Each hashtable should have two keys:

  • "name", the country’s name
  • "temperature", the country’s current temperature

In the stencil code, report always returns the same report. You should fix it so that it actually reports the current state of the simulation.


Your advance_year and report methods should have tests in test_simulator.py. You may find it useful to create one or more special policy classes to use for testing; these should also be in test_simulator.py.

The policies

The policies are defined as classes in policies.py. The policies are as follows:

  • Baseline emits at a constant rate
  • Reducing reduces emissions by a constant amount every year to a minimum of zero
  • TemperaturePanic emits at a constant rate until the country’s temperature is greater than a certain threshold, after which it reduces emissions at a constant rate to a minimum of zero
  • NeighborAverage tries to emit as much as its neighbors do:
    • If its neighbors are emitting less on average than it is, it reduces its emissions by a constant amount
    • Otherwise it raises its emissions by a constant amount

The stencil code includes an __init__ method for each policy, which takes as arguments the parameters for that policy. For instance, TemperaturePanic takes the initial emissions rate, the temperature threshold, and the rate at which it reduces its emissions once it starts panicking.

For each policy, you will need to:

  • Initialize the necessary data in __init__
  • Implement the emit method, which is called by the simulator once per year

You will have to determine the arguments the simulator should pass to the emit method. You should make sure you can implement all of the policies listed above using the information the simulator passes!

Many policies reduce or increase their emissions over time, so you will need to track past emissions as part of a policy object’s state.

Every policy should have tests in test_policies.py.

The display

The display is implemented for you in display.py. It has two buttons: the play/pause button, which starts calling the simulator’s advance_year method 10 times per second until it is paused, and the step button, which calls advance_year once. The rest of the interface displays the countries and temperatures reported by the simulator, as well as the current year.

You can run the display by running python main.py. main.py initializes the display, the simulator, and a number of policies. You can edit it to experiment with different combinations of policies!

PyCharm setup

In order to edit the project files using PyCharm, you should:

  • Open the project folder in PyCharm
  • Create a new Python environment for the project:
    • Open PyCharm’s settings
    • Click on “Project: climate”
    • Click on “Project Interpreter”
    • In the interpreter dropdown, select “Show all…”
    • Click the “+” button at the bottom of the window
    • Click “OK”
  • Install the project’s needed Python libraries:
    • On Windows, run the following commands in PyCharm’s terminal:
      pip install pytest
      pip install pygame
    • On MacOS, run the following commands in PyCharm’s terminal:
      pip install pytest
      pip install pygame==2.0.0.dev6

      If you have any trouble with this process, please post on Piazza!

Design Check

For the design check, you should submit a README.txt file with answers to the following questions:

  1. What state will the simulator need to track? Be specific about the data structures you will use to track each piece of state.
  2. Why does each policy’s emit method need to take in the same arguments? Think about the implementation of the simulator’s advance_year method.
  3. What arguments should the emit methods take?

README Question

In addition to late day information, your final README should answer the following question.

Imagine creating a similar pollution simulation, this time for Earth. Detail the full process you’d take to create an accurate model and the advantages/disadvantages of your design choices. Feel free to draw inspiration from similar simulations that exist. Consider addressing:

  • Collecting data: what kind of data, where you’d source it from, assumptions/allowances you’d make, etc.
  • Constructing the simulation: variables to include, testing methods, consultations with experts to check its accuracy, etc.
  • Publicizing your work: how you will frame its purpose, the reactions of parties who may be affected, how it could be used in a positive or negative way, etc.

Emphasize the differences between this simulation for Earth and one for a fictional planet, like in this assignment — what ethical considerations must you take into account given the real impact this simulation can have?


You may submit as many times as you want. Only your latest submission will be graded. This means that if you submit after the deadline, you will be using a late day – so do NOT submit after the deadline unless you plan on using late days.

The README template can be found here.

Please follow the design and clarity guide–part of your grade will be for code style and clarity. After completing the homework, you will submit:

  • README.txt
  • simulator.py
  • test_simulator.py
  • policies.py
  • test_policies.py

Because all we need are the files, you do not need to submit the whole project folder. As long as the file you create has the same name as what needs to be submitted, you’re good to go! Only one of your partners should submit the project on Gradescope! Make sure to add your partner as a Group Member on your Gradescope submission so that you both can see the submission. Please DO NOT write your partner’s name in the README when listing other collaborators’ cslogins.

If you are using late days, make sure to make a note of that in your README. Remember, you may only use a maximum of 3 late days per assignment. If the assignment is late (and you do NOT have anymore late days) no credit will be given.

Please don’t put your name anywhere in any of the handin files–we grade assignments anonymously!

You can follow this step-by-step guide for submitting assignments through Gradescope here.