Team Project: Cell Society

The chess-board is the world; the pieces are the phenomena of the universe; the rules of the game are what we call the laws of Nature. — T. H. Huxley

Submitting Your Work

Use GIT to push your team's implementation to the master branch of the provided, shared, cellsociety_teamNN repository hosted in the course's Gitlab group.

As your submission for this project, use GIT to add, commit, and push the following:

• src/main/java folder: all project code
• src/main/resources folder: any images or program files
• src/test/java folder: all JUnit test code
• src/test/resources folder: any test program files
• doc folder: all design documentation and any supporting images
• data folder: all example simulation files
• top-level (no separate folder): project README, and otherwise no other files created by you

Your code is expected to follow the course coding conventions and follow Javadoc conventions.

Your team's project GIT repository must show many, purposeful, commits from all team members rather than just one or two large "kitchen sink" commits and marathon merging or redesign sessions. Specifically, we will be looking for deliberate attempts to regularly:

• integrate each other's work
• refactor code to improve its design
• test your functionality

We strongly suggest using the course's suggested GIT workflow for teams to manage this process.

Specification

In teams, write a Java program from scratch using straight OpenJFX (without FXML), that allows users to simulate Cellular Automata (CA) models, such as those described in the following CompSci 101 level assignments:

• Conway's Game of Life (and Wikipedia's description)
• Spreading of Fire (and Wikipedia's description)
• Schelling's model of segregation (and Wikipedia's description)
• Wa-Tor World model of predator-prey relationships (and Wikipedia's description)
• Rock, Paper, Scissors as a CA effectively models competing bacteria colonies
• Even CompSci 201's old Percolation assignment can be modeled using an incredibly simple CA (rules are given on page 3)

Generally, your program should make it easy to animate a variety of CA simulations as a 2D grid (with a number of rows and columns) of cells (with an initial state such as on and off). A simulation's rules (such as whether a cell changes state, is created, or moves to another position in the grid) are applied on each cell "simultaneously" (i.e., based on their current state and that of their neighbors) and then cell states are updated in a second pass (so a cell is affected only by information from their immediate neighbors). The grid's edges represent closed bounds, i.e., cells on the grid's edges should have smaller, partial, neighborhoods than those in the middle, with full neighborhoods (i.e., 8 neighbors).

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 a pair of data files (with appropriate error checking):

• initial states of the grid's cells for a simulation, in a file with a .csv extension (as might be saved from a spreadsheet)
  • header row: two numbers representing the grid's dimensions (number of rows and columns of cells)
  • remaining rows: initial 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)
• initial settings for a simulation, in a file with a .sim extension that uses Java's property list format (i.e., key=value pairs), containing:
  Required keys:
  • simulation type it represents (e.g., Game of Life, Fire, etc.)
  • title (e.g., just the kind of simulation, or a description of what this configuration is showing or testing, or the name of a specific structure (such as glider, blinker, or pulsar))
  • author (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 (e.g., what you expect to see or why you think it is an interesting example)
  • filename for the CSV data that has the grid's number of rows and columns and the cells' initial states
  Optional keys:
  • 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)
  • cell state colors (e.g., for EMPTY state, blue might represent a water world, black a space world)
• examples are given here, but you are expected to make your own example files as well (including ones with known errors)

While the exact User Interface for setting up and animating a simulation is up to your team to decide, it should allow the user to:

• see the simulation's descriptive information (or make it easily accessible, like in a dialog box created by pressing an "About" button):
  its type, name, author, description, state colors, and parameter values (if any)
• animate a simulation from its initial state indefinitely until they choose to stop it, displaying the current states of the cells in the grid with different colors
• pause and resume the simulation, as well as step forward through it
• speed up or slow down the simulation's animation rate
• change a cell's state by clicking on it
  NOTE, users should be able to choose a color to represent all cells of the same state (with appropriate defaults if none have been)
• load a new configuration file, which stops the current simulation and starts the new one
  NOTE, the app's window size should not change based on the size of the grid to be displayed (i.e., the display size of an individual cell should be calculated to fit within the app's current scene size)
• save the current state of the simulation to both property and CSV files that share one name entered by the user (with different extensions: .sim and .csv)
  NOTE, this requires providing the user fields for entering or changing information such as the title, author, and description
• run multiple simulations at the same time in such a way that they can be seen side by side (perhaps to compare results, so do not use tabs like a browser)

Any colors, fonts, or other appearance styling should be able to be changed dynamically between at least three different options (such as Dark or Light modes, Duke or UNC colors, larger fonts for presentation mode, etc.). Any text displayed should be able to appear in at least three different languages (Pig Latin is a popular option or you can use Google Translate if no one on your team can do it).

• it is not required to change the language at any time while the program is running, so a very reasonable options is to present the user with an introductory screen showing all available languages
• even these six options must not be hardcoded, but made dynamically using configuration properties or algorithmically from the files available in resources folders

Test your program using JUnit 5 (with assertions both for typical situations and all possible thrown Exceptions) to separately verify the Model and View work as intended. Generally, aim to create a test class for each of your concrete classes with at least two well-named tests for each non-trivial public method (more than two are expected for complex methods) and achieve at least 75% Line test coverage of each class.

• make well named tests that test both "happy" and "sad" possible code paths (here are many, many, many examples in case you are having trouble thinking of possible negative tests)
• for each Exception expected to be thrown (both for when it is thrown and caught directly in the JUnit test for the Model and when it is caught and handled appropriately in the View using TestFX)

Deliverables

This project will be submitted in stages:

• Plan and Test: implement and thoroughly test an initial part of the project
• Basic: implement the core of the project with appropriate tests
• Change: extend the project based on a new set of features

It is encouraged that you to start simply in order to verify your understanding of the project's core features. Then refactor your code to help it serve as a foundation for the more diverse functionality expected.

Design Specifications

The functionality features emphasize design goals, so your focus should be implementing them in such a way as to promote creating abstractions that generalize your core code, not simply as special cases added without a clear plan. Ideally, a well-designed program will make implementing new features easier so, when choosing a new feature to implement, look for something that fits into your design or refactor your code first to accommodate it. Specifically, your design should be thoughtful and intentional: clearly avoiding duplicate code structures and making it easy to add more simulations without changing the existing code.

Adding functionality not related to an abstraction or resulting in poor code that diminishes your overall design efforts will not be rewarded. Specifically, the credit you receive for a functionality feature will be in proportion to how clearly it shows that your core classes are closed to modification while open to extension using abstractions to remove dependencies on concrete classes. Thus, a program with fewer features, but plenty of clear paths to easy expansion, is worth more than a program with many features but lacking clean code and good abstractions.

In addition to following the course Code Design Habits Checklist, your project design should clearly show the your progress learning the topics we have discussed so far in the course:

• Model View Controller (MVC). Create a cleanly structured GUI that completely separates the view from model with controller(s) that mediate the flow of information (including errors)
  • no references to OpenJFX classes (i.e., import javafx.XXX) should be used within your model classes (even javafx.scene.paint.Color)
• Clean code. Write your code primarily for communication: avoids duplication, supports your team mates writing clean code, and demonstrates your design intents
• Avoid hardcoded values. Move all "magic" values into files, rather than compiled into your program, using resources, properties, and styles
• Exceptions. Communicate errors in a thoughtful, intentional, manner instead of returning null or other error prone values (possibly using Java's Optional)
• Open/Closed Principle. Structure the main code algorithms around abstractions (built using inheritance and polymorphism) rather than directly on concrete classes
• Build abstractions. Create inheritance hierarchies to define common methods that can be implemented in multiple ways in separate concrete classes
• Encapsulation. Key implementation details must be hidden such that they can be changed without impacting any other classes:
  • the grid data structure (such as between a List of Lists, a 2D array, or a Map)
  • the configuration file format (such as using different key names, one file instead of two, or a JSON format instead of a Java properties file)
  • the panel component used to display the grid (such as a Canvas, a GridPane, or a Group)
• Interfaces. Be intentional about how you expect other classes to use your object by controlling its available methods
• Dependency Inversion Principle. Communicate between classes using abstractions, ensuring implementation details can more easily be changed, perhaps by using Lambda expressions
• Immutability. Be intentional about what data you expect to be modified by explicitly restricting what other classes can change, perhaps by using Enumerated types or Records

The overall program should still be organized into several packages: some that are intended to be public, consisting primarily of abstractions that are used by other packages, and the rest intended to be private, consisting primarily of concrete subclasses that are not imported or known about directly by other packages.

CompSci Context

This project highlights the following interesting and foundational Computer Science concepts. You are not expected to write a general or complete version of any of these concepts, but learning about them may help provide a context to begin thinking about some design issues or connect your work in this course to the broader computing community.

• Cellular Automata are simulations based on a model that consists of a regular grid of cells, each in one of a finite number of states that are each updated based on a set of fixed rules described in terms of the cell's current state and the states of its immediate neighbors. Though this model is simply described, it can be used to simulate a wide variety of complex phenomena, such as ant foraging to modeling fur patterns to natural patterns to economic theory to city growth to image processing to generative music to terrain generation in video games! In fact, after 20 years of study, Stephen Wolfram declared CA were a universal mechanism for moving scientific study forward in his 1280 page book A New Kind of Science that contains hundreds of example models and others argue it could explain the universe scientifically and philosophically.
• Computational Modeling is the process of defining an algorithmic model of a physical system that is difficult or impossible to observe or control, much less experiment with. Such models can help better understand a complex system by allowing people to perform many experiments and explore the effect of even subtle changes. This helps especially for systems that involve events that are not precisely predictable even though the relative frequencies of event results may be known, e.g., a flipped coin's particular result cannot be known certainly. However, a model's accuracy can lead to ethical questions).
• The Model, View, and Controller (MVC) architecture has proven so successful that it is the de facto standard for designing web and mobile applications, with many popular frameworks actually requiring it. This is done to separate internal representations of information from the ways information is presented to and accepted from the user, decoupling these components and allowing for effective code reuse and more opportunities to develop and test separately and in parallel (often by people with very different skill sets). As programs become more complex, a Controller (middleware) is introduced between the Model (backend) and the View (frontend) to act as a mediator to process their interactions and provide specific application logic. There are many ways to organize a Controller that range from a single class tightly coupled to a specific application to many classes that manage more "micro tasks" to just responses to application events.
• Configuration, or config, files are a standard way to customize how you interact with an application or how an application interacts with the rest of your system. There are thousands of config files on your computer, hidden by starting with a period or in system folders like /etc. It is also thanks to config files that any time you launch an application, it has "memories" of how you like to use it (or how GIT remembers your name and which repository to send your code to). There are many standard formats but Java prefers .properties and XML files. XML is an open, industry standard, flexible format, supported by most companies (including rivals Google, Facebook, Microsoft, and Apple) as well as many web protocols and Linux programs. It is supported in all modern programming languages and, while it may be viewed as "overly-verbose", it is generally easy to read and generate algorithmically.

Individual Responsibilities when Working as a Team

This project requires steady, consistent, work — only by putting in consistent time each week will you see measurable progress and not have to pull "heroic" all-nighters.

Although this is a team project, everyone has individual responsibilities to the team that can be summed up as follows:

• actively participate in all team meetings
• regularly contribute clean code to the shared repository in reasonably sized chunks
• solving and coding at least one "interesting" design problem
• helping teammates at least once by going above and beyond

Unfortunately conflicts are likely to occur, so please let the Teaching Team know as soon as possible — even if it has happened just once or twice since it is better to deal with the situation early rather than having a disaster at the end when little can be done to get back on track.

Resources

Experiment online with the Game of Life or NetLogo Fire Simulation.

• Cellular Automata (or as a video series), from The Nature of Code by Daniel Shiffman
• John Conway's Game of Life, the most famous CA (including "battles" and running the Game of Life within a Game of Life simulation!)
• NetLogo, CA models contributed by hundreds of scientists and educators that use a Logo inspired programming language