Team:BCCS-Bristol/Modeling-To Do List



Wiki
General tasks that must be done to keep the wiki up to date.
 * Modelling Approach [Done] - Section needs completing to include a discussion of the different models.
 * GRN Model Section [Done] - Section needs to be completed.
 * Stochastic Agent Based Simulation Section [Done] - Section needs to be completed.
 * Simulation File Definition [Done] - A full table detailing the format and types of parameter that can be entered in simulation definition files needs to be included.
 * Hybrid Model Section [Done] - Section needs to be completed.

General

 * BSimCollisionPhysics [Done] - Parameterise the potential function for the different interactions to allow for differing binding forces to be modelled. Can now be read from the parameter file.
 * BSimVisualAid [Done] - Create a new interface to allow for visual effects to be defined and added to a simulation scene.
 * Convert Existing Visual Aids [Done] - We already have a mean bacteria and particle movement tracer implemented, these need to be re-coded to use the new interface defined above.
 * BSimSceneClock [Done] - A new visual aid that allows for the time of a scene to be seen (in seconds). Will make it easier to reference parts of a simulation. Added and fixed the scaling issue (had to perform inverse linear transformation before drawing to the graphics context).
 * BSimScene Parameters [Done] - We need to update the parameters that BSimScene currently used for the size and zoom factors such that they are not dependant on the GUI. This is necessary to allow for scripts to alter the view of the simulation without the need for interacting with GUI code. Completed with two way update so gui will also update BSimParameters object.
 * Bacteria and Particle Creators [Done] - These need to be updated to take the arguments list from the BSimParameters object and create sets and single objects as required. Have also added the function to bacteria creator to ensure that no bacteria overlap particles present.
 * Potential Testing [Done] - We need to make sure that the timestep and repulsion part of the potential function are sufficient to stop objects moving through each other. Testing needs to be carried out to make sure this happens as issues have been seen on solid boundaries. May have to use some form of squared or exponential type function to ensure it grows fast enough. Because this is dependant on the number of bacteria present in the simulation and the timestep, we have added this as a parameter so that is can be tuned for individual simulations.
 * BSimParameters [Done] - Bacteria, Particle and Chemical Field create methods need to be completed in this class. Once done the BSimScene class should be updated to use these instead of the temporary function currently in place. The BSimScene class now creates all objects using the BSimParameter object.
 * Code Cleanup [Done] - We need to go through every file and ensure that comments are included where appropriate and that and debugging code is removed. All files are now using the correct commenting format and are up to date.
 * Wrapping Boundary [Done] - An option needs to be added which states if the memory of any bacteria wrapped is filled with the new location or if the old memory is retained. Option added to parameter file.
 * Bacterium Definitions [Done] - We need to develop multiple types of bacterium that allow us to test various behaviours. Each should allow for switching delays to be altered.
 * BSimBacterium [Done] - Basic bacterium needs to be developed that will follow the goal chemoattractant. This is encapsulated in the normal bacterium class.
 * BSimSensingBacterium [Done] - Sensing bacterium needs to be developed that will ignore the chemoattractant until contact with a particle is made. Finished with an additional parameter for the delay before the contact with the particle is lost.
 * BSimCoordBacterium [Done] - Co-ordinating bacterium needs to be developed that will ignore the chemoattractant until contact with a particle is made and then co-ordinate the behaviour of others in the local area through the use of a chemical signal. This has been developed but testing still is required.
 * BSimRecruitBacterium [Done] - Recruiting bacterium needs to be developed that will carry out the same tasks as the BSimCoordBacterium but also send out its own long range chemoattractant that the bacteria will search for by default.
 * BSimGRNBacterium - Bacterium that will implement the proposed GRN to see if other emergent behaviours are observed.
 * Particle Binding - We can create potentials between bacteria and particles that cause strong binding to occur, however, we may also want to model the torque forces exerted on the particle if the bacteria become fixed to a single point on the surface. This may include restricting the movement that a bacteria can make.
 * Test BSimChemicalField [Done] - As we will be using the chemical fields extensively we need to test that they are working correctly first. The bacteria are reading the correct values and diffusion is working as expected.
 * Potential Reaction Force - It was noticed on simulations of a high bacterial density that if a large number of bacteria were all pushing each other into a solid boundary that they could overshoot and pass through. To fix this we need to ensure that the reaction force can be large enough and that the time step is small enough to ensure no movement over a boundary in a single timestep. We have added parameters to allow for extreme simulations to alter these as required.
 * Implementing drift during run - A nice to have but not thought to add much to the simulation.
 * Updating bacteria memory on wrapping boundaries [Done] - Make the memory reset on wrapping boundaries optional, add flag in parameter file. This has been added to the parameter file.

Multi-threading Optimisations
Update the main computational classes to split up work into separate threads. Should improve performance when running on a single computer, or cluster node, with the appropriate resources.
 * BSimChemicalField [Done] - Update class to use worker threads when calculating the new diffusion field.
 * BSimCollisionPhysics [Done] - Update class to use worker threads when calculating the force matrix.
 * BSimCollisionPhysics [Done] - Update class to use multithread the call to the runLogic method on each bacterium. Physics class has been restructured to use the same worker threads that calculate the force matrix.

Batch Processing
We need to be able to run batch runs of simulations to get enough results for statistical analysis. Viscosity: 0.0001 Dt: 0.01 CreateBacterium: 10, 10, 3.7, 50 CreateRandomBacteriaSet: 0, 0, 500, 600, 3.7, 50 ... BSimParticleFileExport File Format: Timestep, Particle_1_x, Particle_1_y, ..., Particle_n_x, Particle_n_y, Particle_Average_x, Particle_Average_y
 * Parameter File Definition [Done] - We need a simple text file defined that allows for all the parameters in the simulation and sets of bacteria, particles and boundaries defined. It should look something like the example below with each line either giving a parameter definition or BSimObject creation details. First version has been completed but still a few areas that need loaders added. Full specification will be uploaded to the wiki once all loaders are available.
 * BSimBatch [Done] - Class to read the parameter files and run a set number of simulations, outputting videos and a data file of particle movement.
 * Blue Crystal Accounts [Done] - Contact university about getting accounts to run some larger scale simulations. Accounts have been setup and are working! Have meeting arranged to talk through best approach to schedule the jobs we require.
 * Output Filters [Done] - Create new classes that can be attached to a simulation scene, allowing for information about the scene be output, e.g. in the form of text based or movie files. This ties in with the parameters that need to be monitored for the statistical analysis. This has been completed with two output types BSimParticleFileExport and BSimBacteriaFileExport, the formats are below:

BSimBacteriaFileExport File Format: Timestep, Bacteria_Average_x, Bacteria_Average_y

BSim Simulations
Once the framework is in a working state we will need to have in place an approach for using it to understand the sensitivity of each of the parameters, test the viability and compare different methods. It is expected that the list of simulations to run will evolve as the design becomes refined in the wet lab.


 * Define Simulation Process [Done] - Ensure that the full end-to-end simulation setup and execution process is understood. Define the inputs, parameters that can be altered, and output required to calculate useful statistics for comparison. As many simulations will be run we want to make sure that problems will not arise during the runs. This should be placed on the wiki under the stochastic agent based model section.
 * Specify Simulations [Done] - We need a list of all important simulations that need to be run to understand the effect various parameters have on the designs stability and viability. A list should be developed on the wiki giving a short description of the run, the parameter ranges, statistical analysis to be performed, hypothesis, actual outcome after the run and data files/example video.
 * Bacteria Chemotaxis [Done] - Run tests to show that basic bacterial chemotaxis is working correctly.
 * Chemotaxis with Particles [Done] - Insert particles into a field of bacteria performing chemotaxis and show that the particle is also directed towards the chemoattractant.
 * Particle Sensing Bacteria [Done] - Bacteria move randomly until coming in contact with a particle at which point they head towards the chemoattractant. Will consider differing delays for switching off response when loosing contact with bacteria.
 * Co-ordinating Bacteria [Done] - Bacteria act in the same way as the sensing type but now also co-ordinate local behaviour by using local signalling (AHL).
 * Recruitment Bacteria [Done] -
 * Permanent Adhesion [Done] - Due to experiments showing adhesion of bacteria to the particle, we will investigate how this effects the chemotaxis that can take place. To start with we consider simple adhesion by using an altered potential function. For a fuller analysis we may have to include torque forces on particles. These are currently not included and so this final aspect may be skipped due to time constraints.
 * Parameter Sensitivity [Done] - See the batch smulations section for a full outline of parameters we want to investigate.
 * Full Scale Lab Experiment Simulation [Done] - This will have to be run on the BlueCrystal cluster. It will perform a full scale lab experiment in silco (if possible).
 * Run the simulations [Done] - Work through the previous list running the simulation sets.

Analysis
Results from the simulations need to be analysed. For this we will use MATLAB to automate the process carrying out statistical calculations on the output files generated by the simulations.