CompSci 308
Spring 2024
Advanced Software Design and Implementation

Cell Society: Detailed Specifications

Basic Functional Requirements

Your project team will implement multiple types of Cellular Automata (CA), each with unique algorithms and simulations. Begin with Conway’s Game of Life, gradually adding more simulation types and configuration options. Progressively refactor your code, utilizing abstractions such as interfaces, abstract classes, and inheritance to add new features with minimal alterations to existing code. Prioritize a flexible architecture, abstracting key details like the grid’s data structure, configuration file format, and OpenJFX specifics to reduce tight coupling between code components.

Below is a table of the project’s expected functionality, following the format in the Functional Requirements Glossary (which describes the difference between Core, Variation, and Extension requirements). You are expected to implement all Core requirements, but only enough Variation and Extension requirements of your choice to validate you are making good choices to meet the Design Specifications.


All Cellular Automata have Cells laid out in a grid. Cells have states, and their states change based on rules as the simulation progresses. For example, in John Conway's Game of Life (GoL), each cell can be in one of two states: alive or dead. The transition rules are based on the number of state of neighbors surrounding each cell. In GoL, a live cell remains alive if it has two or three live neighbors, otherwise, it dies. A dead cell becomes alive if it has exactly three alive neighbors. You will implement the cell states and cell state transitions in Java code.

While we will not practice formal ways of automatically testing your code until the next project, you will create multiple XML Simulation Configurations to test each simulation type (at least 29 from the requirements below, but feel free to add more).

ID Name Priority Description
CELL-01 Simulation: Conway’s Game of Life Core A classic cellular automaton where cells on a grid live, die, or reproduce based on their neighbors. See this assignment and Wikipedia for states and state-transition rules. You must write at least 5 different configuration files that run successfully to test this simulation. Of those 5 simulations, 2 must have configurations where the active cells are on the edge and reach an expected state.
CELL-02 Simulation: Spreading of Fire Core This simulation models a forest fire, where trees catch fire and burn based on neighboring cells. It’s used to study percolation and critical phenomena, as well as fire spread in different forest densities. See Spreading of Fire and Wikipedia for states and state-transition rules. You must write at least 5 different configuration files that run successfully to test this simulation. Of those 5 simulations, 2 must have configurations where the active cells are on the edge and reach an expected state.
CELL-03 Simulation: Schelling’s Model of Segregation Core A model that demonstrates how individual preferences can lead to large-scale segregation. It simulates agents of different types moving based on neighborhood composition, revealing patterns of segregation. See Schelling's model of segregation and Wikipedia for states and state-transition rules. You must write at least 5 different configuration files that run successfully to test this simulation. Of those 5 simulations, 2 must have configurations where the active cells are on the edge and reach an expected state.
CELL-04 Simulation: Wa-Tor World Core A predator-prey ecosystem simulation. It models fish and sharks, with the dynamics of birth, death, and movement, providing insights into population dynamics and ecological systems. See the Wa-Tor World and Wikipedia for states and state-transition rules. You must write at least 8 different configuration files that run successfully to test this simulation. Of those 8 simulations, 3 must have configurations where the active cells are on the edge and reach an expected state.
CELL-05 Simulation: Percolation Core Simulates fluid flow through a porous material. See CompSci 201's old Percolation assignment and this incredibly simple CA (pg.3) for state and state-transition rules. You must write at least 3 different configuration files that run successfully to test this simulation. Of those 3 simulations, at least 1 must have a configuration where the active cells are on the edge and reach an expected state.
CELL-06 Test Configurations: Game of Life Known Patterns Core Create at least 3 simulation configuration files for Conway’s Game of Life that replicate well-known patterns (e.g., Glider, Blinker, Toad). This is in addition to your other tests.
XML Configuration

Simulation rules will be written in Java code but the kind of simulation, its starting configuration, as well as any initial parameter settings will be read from an eXtensible Markup Language, XML, formatted file. The exact tags of this configuration file should be decided by your team. The tags should allow you to configure all of the following:

ID Name Priority Description
CELL-16 XML-Based Simulation Configuration Core Implement an XML-based configuration system. For each simulation, a single XML file should contain the simulation type (e.g., Game of Life, Fire), title, authors, a description, grid dimensions, initial cell states, and specific simulation parameters. When loading a simulation, the simulator will parse these XML files to set up the simulation environment.
Graphical User Interface (GUI)

These requirements describe how the user will interact with your simulator, including how the state of the simulation should be presented to them. The exact User Interface for setting up and animating a simulation is up to your team. Examples of how the user can interact are given in the requirements (i.e., buttons, sliders, etc.), but you do not need to implement the functionality following those examples so long as the functionality works.

ID Name Priority Description
CELL-17 Cell Grid View Core When a simulation is loaded from a configuration file, the state of the simulation should be displayed in Grid View where adjacent cells are adjacent in the visualization. Cell states should be mapped to colors so that all cells in the same state are the same color and cells in different states are different colors. (This is the standard way to represent a cellular automaton.) When the simulation state changes, the Grid View should be updated to reflect the changes.
CELL-18 Display Simulation Information Core When a simulation has been loaded, the simulator should show or make easily accessible the simulation’s descriptive information, including its type, name, author, description, state colors, and parameter values. This could be implemented as an “About” dialog box.
CELL-19 Load New Configuration File Core Provide a mechanism (i.e., button, drop-down, etc) for a user to load a new simulation from a simulation configuration file. When the user invokes this load mechanism (i.e., clicks the button), they may select a new simulation configuration from their project resources. Any current simulation is stopped and removed, and the new simulation is loaded in its initial state. If a previous simulation was replaced, the application window size should remain consistent, regardless of the grid size.
CELL-20 Start Simulation Core When the user presses the start button, the simulation should execute steps at a rate determined by the current configuration until stopped. The simulation view should be updated to reflect the simulation state as it changes.
CELL-21 Pause Simulation Core When the user presses the pause button, the simulation should stop advancing steps. The simulation state from when the pause button was pressed should be displayed to the user in the simulation view.
CELL-22 Simulation Speed Adjustment Core Provide a mechanism to speed up and slow down the simulation (i.e., buttons or a slider). When the user speed ups/slow downs the simulation, the rate at which simulation steps occur should increase/decrease. The Grid View should update at the same rate as the underlying simulation.
CELL-23 Save Simulation State as XML Core Provide a mechanism to save the current state of the simulation. When the user invokes this save mechanism (i.e., clicks the button), the current state of the simulation should be saved as an XML configuration file matching the XML configuration specification. When the user loads this XML file, the simulation should return to the exact state it was in when the file was saved.
CELL-24 Edit Simulation Save Extension When a user is saving a simulation state, before writing the configuration file, allow the user to add or alter information such as a title, author, description, and save location.
CELL-25 Reset and Clear Grid Functionality Extension Provide a reset button. When the user presses the reset button, the simulation should return to its initial state, but all simulation configurations (i.e., speed, playing/paused) should be unchanged.

Design Requirements

You will be accountable for ensuring that your code's design meets the specification just like you are responsible for ensuring your code's functionality meets the Functional Specification. Keep in mind that design is more important than functionality for your final grade and you should not expect to meet all the design requirements by simply getting it “working” right before the deadline.

The design requirements for CellSociety are an extension of the design requirements you had for Breakout: DESIGN-01-DESIGN-07 were introduced in Breakout. DESIGN-08-DESIGN-15 are new for CellSociety. Below is a table of the project's expected design goals, following the format in the Design Requirements Glossary.

ID Name Adherence Description
DESIGN-01 Multiple Classes Complete Code should be divided into several classes that each have a useful purpose (i.e., non-get/set methods). Avoid these code smells: large class and data clumps.
DESIGN-02 Named Constants Complete Any constant values, including numbers and strings, should be named. This includes being declared as final variables with a name that describes the meaning and/or use of the value.
DESIGN-03 Don’t Repeat Yourself (DRY) Complete The same lines of code should not appear in multiple different places in the same project (i.e., they should not be duplicated). Instead, the code should be refactored so that the duplicated logic is written only once and called from many places.
DESIGN-04 Tightly Scoped Methods Consistent Each method should be small and single-purpose. Long methods should be decomposed into smaller pieces of functionality. Long methods are a code smell.
DESIGN-05 Code Formatting Consistent Code should follow course formatting conventions, including things that cannot be automatically checked, especially the Java naming conventions.
DESIGN-06 Interact Through Methods Consistent Classes should avoid inappropriate intimacy by collaborating via method calls. A class should not directly access the instance variables of another class. Do not use public instance variables or global variables.
DESIGN-07 Comments Consistent Follow Javadoc conventions for commenting on public classes, interfaces, methods, and packages. In-line comments should be used judiciously; self-explanatory code is preferred. See Internal Documentation.
DESIGN-08 Incremental Delivery Consistent Your team’s project GIT repository should show many, purposeful commits from all team members rather than just one or two large “kitchen sink” commits and marathon merging or redesign sessions. Commit messages should include the requirement number as described in the requirements glossary, starting with either [CELL-XX] for new features and [DESIGN-XX] for refactorings).
: Each person must push at least four commits that show the results of refactoring existing code to improve its design, with a commit message describing the issue(s) addressed. Start these commit messages with [DESIGN-XX], where XX is the ID of the design requirement your commit is addressing.
DESIGN-09 Model View Separation Consistent GUIs should be separate from the model; this requires clear articulation about what information (including errors) needs to be communicated between each part.
CELL SOCIETY NOTE: for Cell Society, this is a simplification of Model-View-Controller (there is no controller).
  • The View should be a collection of classes in package called cellsociety.view. Classes in the cellsociety.view package use OpenJFX to display to the user and interact with the Model.
  • The Model should be a collection of classes in a package called cellsociety.model. The Model maintains the state of the simulation and executes state transitions. Classes in the cellsociety.model package should not import any classes from javafx.*; classes in cellsociety.model should be agnostic to how the information is presented to user.

For both the cellsociety.view and cellsociety.model packages, you can put classes in sub-packages as well, i.e. in or You should have at least three packages.

DESIGN-10 Encapsulation Consistent Key implementation details must be hidden such that they can be changed without impacting any other classes.

  1. The data structure representing the grid should not be passed around. For instance, there should not be a public Object[][] getGrid(); method if the grid’s data structure is a 2-D array (Object[][]).
  2. The fact that configuration files are formatted as XML should not be known to any part of the program except the part that explicitly handles loading the file.
  3. The implementation of the panel component used to display the grid (such as a Canvas, a GridPane, or a Group) should be able to be changed independently of the rest of the UI.
DESIGN-11 Make and Use Abstractions Consistent Create abstractions that capture commonality (superclasses or interfaces) and encourage variability (subclasses or implementors). Build your classes to depend on the abstractions (superclasses and interfaces) rather than implementations (concrete subclasses).
  • Use the most abstract collection possible (i.e., List instead of ArrayList and Map instead of HashMap).
  • Do not downcast to specific subclasses or use instanceof checks (except in equals() methods).

CELL SOCIETY NOTE: Implement at least 3 abstractions (you are encouraged to use as many abstractions beyond that as you think are the right fit for your design problems).

DESIGN-12 Externalize Configuration Consistent Move hardcoded values into configuration files, rather than compiled into your program, specifically:
  • "magic" values stored as static final constants
  • any text displayed in the user interface, by using resource property files (the String.format() method allows you to make any complex string a single value)
  • any styles (colors, font, borders, etc.) used to customize the user interface, by using CSS files

Store these files in src/main/resources.

DESIGN-13 Programs Should Not Crash Consistent Build robustness into your program so that it does not crash or hang. Handle errors and provide a reasonable response to exceptional cases so that the user can continue to run the program.
DESIGN-14 No Dead Code Forthcoming Your project should not include unused variables, methods, or classes. Do not comment out blocks of code to save them for later; instead, use your GIT history to find old code.
DESIGN-15 Handle Errors Using Exception Flows Forthcoming Communicate errors in a thoughtful, intentional, manner rather than returning null or other error prone values.
Consider using custom Exceptions or Java's Optional.
DESIGN-16 Explicit Immutability Forthcoming For classes and values that should not change after they are instantiated, explicitly restrict them from changing using language features.
Consider using Enumerated types or Records.