CompSci 308 : Spring 2024

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.

Simulations

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:

Simulation type it represents (e.g., Game of Life, Fire, etc.)
Title for this configuration (e.g., the kind of simulation, or the name of a specific structure (such as glider, blinker, or pulsar), or what this configuration is showing or testing)
Author of this configuration (e.g., team member, someone from the Internet from whom you borrowed the example, or the original discoverer (such as glider was discovered by Richard Guy in 1970))
Description of this simulation (e.g., brief sentence or two about what you expect to see or why you think it is an interesting example)
Width and height of the grid (two numbers representing the grid's number of rows and columns of cells)
Initial configuration of the states for the cells in the grid (whose values represent the different states a cell can be in (e.g., 0 = DEAD and 1 = ALIVE))
Parameter values specific to the simulation (e.g., probCatch, the probability of a tree in a cell catching fire, but Game of Life has no parameters)

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 up`s/`slow down`s 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). CELL SOCIETY NOTE: 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 `cellsociety.model.foo` or `cellsociety.model.bar`. 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. CELL SOCIETY EXAMPLES*: 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[][]`). 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. 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). EXAMPLES: 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.