Project 2: Simulation of uncoupled circadian oscillators (due Friday Feb 23rd at midnight)

This week we will get the infrastructure working. Ultimately, we will be simluting the mammalian circadian clock as a network of oscillators that signal each other, but this week we will be simulating the oscillators without any signaling. We will write the code we need to run a simulation, detect events happening in that simulation, and compute simple summary statistics about those events. Next week, we will update the code to incorporate signaling and then collect statistics about the performance (both timing and program output).

1. Read Stephanie's Reference Guide and the links within it. This week, you can ignore the signaling and the VRC.
2. On NSCC, cURL the code tarball to it. Then expand the tarball:
   1. curl -O http://cs.colby.edu/courses/S18/cs336/projects/proj02/proj02.tar
   2. tar -xf proj02.tar
   The code is organized into the following files:
   • Main programs:
     • sim_slow.c: Runs a single simulation of 5 uncoupled oscillators, outputting the results (for every time step) to a file that can later be displayed by disp_clocks.
     • disp_phase.c: A program Stephanie wrote to graphically display the results of a simulation. It reads in a file output by sim_slow.
     • dump_phase.c: A program that Stephanie wrote to make it easy to read the contents of the binary file output by sim_slow.
     • sim_events.c: A program that will run a simulation and detect each time that an oscillator's phase crosses CT6. It prints out the index of the time step at which each event occurred.
     • sim_stats.c: A program that will run a simluation and detect each time that an oscillators phase crosses CT6. This version prints out the standard deviation of those event times for each cycle.
   • Data files: Stephanie developed a file format that contains the information that allows us to view and visualize the movement of every oscillator in a simulation. It is a binary file format, so don't try to read it with Xemacs.
   • Support routines:
     • my_timing.c and my_timing.h: contains a function that allows us to time code in seconds with precision up to milliseconds.
     • phase_io.c and phase_io.h: contains file IO routines for the slow simulation and disp_clocks.
     • my_math.h: mathematical functions. You should be able to supply my_math.c from your project 1 code..
     • phase_support.c and phase_support.h: the heart of the simulation. Routines for simulating and computing statistic go here. You will be adding code to these files..

   As you can see, there are many top-level programs. They begin with more IO and less computation (good for debugging) and end with more computation and less IO (good for running lots of simulations and not getting overwhelmed with output). We also introduce code to time the computations. Our goal as we parallelize this code in the future will be to speed it up dramatically.

3. Write runPhaseSimulation (in phase_support.c). It should use the Forward Euler method to solve the set of differential equations that model Nx oscillators without any signals. See Stephanie's guide for more information about the model and method and the comments in the header file for more information about parameters and return values.
4. Test it by running sim_slow (which I have supplied). You can visualize the output of sim_slow using disp_phase or dump_phase. When you are debugging, please use lots and lots of print statements.

   If you would like to compare it to the output of my code, examine the following .phs files. They run the simulations with 5 and 100 oscillators, respectively. To generate the files, I ran sim_slow like this:

   ./sim_slow uncoupled_5.phs 5
   ./sim_slow uncoupled_100.phs 100
   

   You should generate files with your implementatin and then use disp_sim and/or dump_sim to compare my files to yours, e.g. ./disp_phase uncoupled_5.phs
5. Write runPhaseSimulationAndDetectEvents (in phase_support.c). The new feature in this version is that it finds the timestep at which the phase (which you will need to put into units of circadian hours) crosses 6 and is increasing (e.g. if the phase is 5.97 at time step 21 and 6.02 at time step 22 then the event happened at time step 22).
6. Test it with sim_events.

   I ran sim_events with the following command and output:

   ./sim_events 2 5
   Oscillator 0: 61 300
   Oscillator 1: 61 302
   Oscillator 2: 61 303
   Oscillator 3: 61 304
   Oscillator 4: 62 305
   Ran in 0.001009 seconds

7. Write runPhaseSimulationFindEventStats (in phase_support.c). The new feature in this version is that it computes the standard deviation of the event times for each cycle. Before computing the standard deviation, transform the evet time step index into a time (in hours). This way, the statistical output (the standard deviation) is in units that are easy to interpret.
8. Test is with sim_stats.

   I ran sim_events with the following command and output:

   ./sim_stats 2 5
    0.044722 0.192354
   

Ideas for Extensions

• Write a main program (and any necessary support functions) that uses the complex order parameter to determine how synchronized the oscillators are. Plot its length over time to show how the synchrony changes. Since these oscillators are not signaling each other, but they are all starting at the same phase, we should see them drift out of sync.
• Explore the effect of the distribution of periods on how quickly the oscillators desynchronize (using either the event-based or order-parameter-based measure). Can you predict the relationship mathematically?
• Use valgrind to demonstrate that you have no memory leaks.
• Add more command line arguments to sim_slow, sim_events, and/or sim_stats to control the number of oscillators, the distribution of intrinsic periods, and/or the time to run the simulation. In your project report, demonstrate the feature (e.g. show how the output changes in response to input and comment on whether or not this output makes sense).

Writeup and Handin

1. Create a named README.txt. Describe the code files (the purpose of each file) along with how to compile and run the code.
2. Create a second file for your project report and it should use a format that allows you to include images or tables (e.g. .docx or .pdf). This report should demonstrate that you have a working simulation and including the answers to the memory-drawing exercises.
3. You should hand in all code necessary to run your solutions. Place all necessary .h, .c, and Makefile files in proj03 directory along with the README file. Stephanie will probably want to compile and run the code. It should be possible to do so without looking for any more files. Tar/zip up the directory and put it in your Private folder on Courses/CS336.

Zip up the directory and put it in your Private folder on Courses/CS336.