README

Biomechanical Aplysia feeding model
Author: Shannon Stork

----------------------------------------------------------------------------------------
4 May 2018
Final commit. After more parameter setting, we have reached the best outcome with the
current implementation. The mdoel is capable of generating no behavior (no input), bites
(chemical input only), and swallow-like behaviors (chemical and mechanical input). The
swallows don't have long enough protraction to actually activate the muscles, but this
would have to be fixed through a much more advanced implementation, probably involving
dynamic parameter modulation. This fulfills the main goals of the project and is a good
base to extend later.
----------------------------------------------------------------------------------------

----------------------------------------------------------------------------------------
4 May 2018
Tentative final commit. This week, I added sensory neurons (the final elements in the
circuit) and did more parameter setting. After much experimentation, it seems like the
synapse parameters I have now are ideal unless I want to totally redesign the HCO. It
turns out that changing some major implementation details might be necessary to get
closer to the biology. That said, without the sensory neurons involved, output from
my HCO linked to model muscles to produce a higher fitness than seen in the previous,
hard-coded inputs before this project began. This model neural network, then, has
already generated some insight into the biological circuit. Since this is an ongoing
project, I plan to continue improving it, but this version is capable of generating
bites with chemical stimulus or not biting with no stimulus. The runtime is very slow,
but that cannot be avoided without compromising the utility. All other main goals are
met.
----------------------------------------------------------------------------------------

----------------------------------------------------------------------------------------
27 April 2018
Added more synapses from the HCO to be passed to the muscles, as well as an additional
class that generates G values without needing a postsynaptic neuron. The synapse file
generated will be tested with the muscle model soon. Run time is awful, but there's
only so much possible optimization since the model is now running at least twice as
many differential equations as before.
----------------------------------------------------------------------------------------

----------------------------------------------------------------------------------------
27 April 2018
Implemented synapses with memory; this was necessary to get a better half-center
oscillator. This part of the circuit (currently functioning as an oversimplified CPG)
can be linked to the muscles in the next few days to test its functionality. After
synapses were redone, more parameter setting was undertaken. The new HCO will be on
the server. Additionally, g values for synapses (formerly s values) were written to a
file at each time step where one of them changed.
----------------------------------------------------------------------------------------

----------------------------------------------------------------------------------------
20 April 2018
Started implementing the circuit this week; more specifically, I worked on the half-
center oscillator, or the pair of mutually inhibitory neurons that will drive the CPG.
I spent a lot of time setting parameters, so not much code has changed. Unfortunately,
the period is way too long, and I can't seem to shorten it. This likely means that I
will need to change the basic synapse to the plastic synapse originally proposed as a
stretch goal. It shouldn't be too bad; hopefully it'll be done next week. That just
leaves one week for the full circuit, but the simple synapse probably won't work now
that I've tried it. The current HCO will be uploaded to the documents section.
----------------------------------------------------------------------------------------

----------------------------------------------------------------------------------------
12 April 2018
We realized why the standard synapse equation was not quite working; there was a typo
in an email that led to me using the wrong input, and the standard convention for
voltage adds a negative sign that this model does not have, which resulted in the sign
being flipped. Now, e_syn=40 produces excitatory psps, e_syn=-90 produces inhibitory
psps, and e_syn = the postsynaptic resting potential produces no psps; these behaviors
are all desired. Aside from a few more tests, I should be ready to start implementing
the actual circuit.
----------------------------------------------------------------------------------------

----------------------------------------------------------------------------------------
12 April 2018
This week was 99% research, but I am hoping to have a full circuit prototype for next
week, whether it is in time for my poster or not. I replicated all of the figures from
the Izhikevich paper; the figures can be found under documents. I had trouble
rigorously testing the last three because the paper used varying current amounts
(currently not supported) and did not specify the magnitude or time scale of the
currents. After much testing, however, I am confident that neurons are working well. I
also tested synapses, and I am much less happy with them. I have been waiting on a
response from a collaborator that might help clarify the issue, but for now, I cannot
really proceed until we are sure that individual synapses are working properly. I am
concerned that the parameters for exitation/inhibition don't make sense and that the
postsynaptic neuron hyperpolarizes too much between spikes. I hope to get this working
within the next few days so I can move on.
On the bright side, I played around a lot with time step parameters. The new parameter
is 0.00001 seconds instead of 0.000008 seconds, so fewer calculations are being run.
I rigorously tested everything against the data we have (data from other simulations,
biological data, and the original IK figures) and the new time step does not impede
accuracy at all. It might need to eventually change back depending on the synchron-
ization mechanism between my work and Tate's; I am waiting on him to make a few
implementation decisions before I can finalize my own. For now, though, the time step
works great and has cut runtime from 7.4 seconds to 0.6 seconds, a huge decrease.
----------------------------------------------------------------------------------------

----------------------------------------------------------------------------------------
8 April 2018
Midweek commit; I added a graph of the output from any neurons whose membrane potentials
are being outputted to the .csv.
Total run time right now before graphing is 7.4 seconds. Hoping to speed this up.
----------------------------------------------------------------------------------------

----------------------------------------------------------------------------------------
6 April 2018
The GUI was updated to allow the user to input a current amount instead of the default
value of 10. This is beyond the original design specifications for the standard GUI,
but it arose out of a desire to more easily test different amounts of excitatory or
inhibitory current, and I decided that it would be useful functionality to provide to
the user as well.
Other than this, I cleaned up and simplified some of the code, fixed comments, etc.
A graph of my output with 10 current being injected to the presynaptic neuron will
be uploaded to the documents portion of the server shortly. This output was validated
against a known working IK model and matches perfectly. I have not made the circuit
more complicated as specified in the Gantt chart for this week because I have been
doing more testing on the simple circuit than expected, but since I'm fixing all the
bugs now, I should be able to get back on target easily and expand the circuit in a
relatively pain-free manner. I'm satisfied with the presynaptic neuron's behavior but
intend to do more testing on spontaneous bursting and synapses before adding more
elements. I plan to perform these tests and add more elements next week.
Please read all 3 comments from 6 April in this document for descriptions of the work
done during week 6.
----------------------------------------------------------------------------------------

----------------------------------------------------------------------------------------
6 April 2018
Bug fixes to Neuron and Synapse; false 0 issue resolved; file writing downsampled and 
written to columns instead of rows; many figures from IK model replicated
----------------------------------------------------------------------------------------

----------------------------------------------------------------------------------------
6 April 2018
This update contains several bug fixes; I spent an embarassingly long time wondering why
synapses were working so poorly, and in the end, it was a small typo. Also fixed in
synapses was a line that mistakenly added the presynaptic neuron's membrane voltage
and a parameter, s, that needed to be repeatedly set during the run instead of the user.
The model currently dumps the first 200 ms of both neurons into a csv. This is very
useful for debugging but not useful for the end product, so I will decide how to down-
sample soon. Some neuron updates were happening at the wrong times, so the equations
were fixed and simplified. Finally, a lot of testing was done. Neurons that receive
no input and are not set to spontaneously burst slowly change from their initial
membrane potentials to their resting potentials, which is good- test 1 from last week
is passed. 2 is also passed; the neuron behaves properly with the output from the first
200 ms compared to the output from a known proper implementation of an IK neuron with
the same parameters. 3 has not yet been tested. Neither have 4 or 5, but unofficial
tests show promising results.
The biggest challenge this week is a bug where the 8th and 258th elements of both
neurons is 0. The location of the 0s is consistent across many runs, but there does not
seem to be any repeateing pattern. I have tried to figure this out and am baffled.
The wrong values don't seem to affect future time steps, but I am doing more debugging
tomorrow, so it will hopefully still be fixed this week.
Also, I have started thinking about efficiency. The current run time of my portion of
the code with this very simple circuit is sitting at about 8 seconds. I have messed
with data storage and resource allocation. Still, I'm concerned about the time, and I
can't cut down on the number of calculations, so I will likely decrease precision on
mathematical operations soon.
----------------------------------------------------------------------------------------

----------------------------------------------------------------------------------------
30 March 2018
The biggest change this week was changing the model from calculating every 0.25 seconds
to calculating every 0.000008 seconds. This brought some pretty major scaleability
challenges, and I'm not sure that my current solution is permanent. This also exposed
some numerical instability not noticible in the small-scale test with fewer
calculations. I have thus decided to hold off on adding more neurons/synapses to the
model until I figure these things out. Here are the tests I am ultimately trying to
pass, courtesy of a mentor:
1. With no input, the neuron should stay at resting potential. While it does not fire,
it depolarizes slightly. I've done quite a bit of testing but can't quite figure out
why, so I am going to consult with my peers. I think fixing this might help later tests.
2. With the synapse off, neurons can be stimulated to fire. This seems to work, but I
want to test the firing patterns more and possibly adjust the parameters again.
3. A spontaneously bursting neuron should be inhibited with negative current injection.
I haven't tested this yet, but I am thinking of adding a simple toggle switch to my
GUI so users can make the current excitatory or inhibitory for each input. Only
excitatory input is presently supported.
The final two tests involve synapses.
4. An excitatory synapse (defined by its parameters) should stimulate the postsynaptic
neuron. This works, but again, I want to test further and adjust if needed. The param-
eters that currently incite proper behavior are not biologically accurate, and I'd like
to fix this rather than just putting in the value that works.
5. An inhibitory synapse (defined by its parameters) should inhibit. Again, this seems
to work, but the parameters aren't right.
The other major fix this week was the synapses. Last week, they actually didn't do
anything, and since I still got reasonable output, I thought they were working. I
tested them more thouroughly this week, found the bug, and fixed it. The only issue
now is the parameters.
I am worried that this will be way too slow with the full size circuit. Rather than
overcomplicating things by building a larger test circuit, as indicated in my targets,
I would like to address the 5 tests and try to make things run faster next week.
Note to the grader: I am officially past the point of generating large chunks of code.
Most of my progress now relies on small adjustments and parameter fitting, so I hope
this document provides sufficient information as to what I've been doing. If you want
more detail, please let me know! I am happy to explain as much as I can.
----------------------------------------------------------------------------------------

----------------------------------------------------------------------------------------
28 March 2018
This is a midweek commit; many synapse and synchronization bugs were fixed, and the
simple circuit works now. I discovered a new bug regarding the number of time steps
required and my current system's inability to store all the values. I have several
ideas of how to fix this, but I wanted to upload a clean copy before messing with the
core of the program too much.
----------------------------------------------------------------------------------------

----------------------------------------------------------------------------------------
23 March 2018 Commit 2
After much grief, I figured out the solution to the stimulation issue. It has been
fixed. The sample circuit is very unstable because of the parameters, but it generates
numerical output, some of which actually makes sense; -65 is the resting potential,
and the output in the absense of input was sometimes -65. At some time steps the output
explodes; next week I should be able to figure out better parameter values. Things
are completely back on target.
----------------------------------------------------------------------------------------

----------------------------------------------------------------------------------------
23 March 2018
Neuron and synapse are implemented except for the stimulation itself, which I am not
sure how to do. I spent quite a while researching and asking around, but I will have to
wait to get a meeting with my superiors to get a solid answer. A lot of debugging
was accomplished, and a test circuit of two neurons and an excitatory synapse was
built. The circuit does little due to the stimulation issue, but it behaves as expected
given that the currents are not changing. The individual methods in the neuron and
synapse classes all seem to work. The neuron class now handles more synchronization,
and the interface actually passes the user input to the network. The input is trans-
lated into current at each time step and given to one of the test neurons. The
stimulation issue should be fixed by next week. Otherwise, everything is back on target.
----------------------------------------------------------------------------------------

----------------------------------------------------------------------------------------
9 March 2018
Synapse class has been added and Neurons have been modified so the AplysiaNet is now
a class and controls synchronizing the different parts of the circuit. Most time this
week was spent making design decisions for the synapse; a simple set of equations was
devised, as well as a set of differential equations to replace the simple ones if time
near the end of the project. Since I am slightly behind due to unexpected complexity
and midterms, I will catch up over break and at least have Neuron and Synapse working,
if I do not have time to commit more code later today. At this point, though, design
of Neuron and Synapse is complete, just not implementation.
----------------------------------------------------------------------------------------

----------------------------------------------------------------------------------------
2 March 2018
Neurons have been mostly implemented. Much of the code was adapted from Tate Keller's
C++ model in hopes that making very similar design decisions will minimize problems
later synchronizing the two chunks of the neural network. This code has not been
extensively tested, and many variables will problably move over to AplysiaNet once the
network starts functioning. However, nothing major will need to be added. The second
target for the week was to start implementing synapses. Dr. Chiel, Jeff Gill, and I
are discussing the best ways to do this, so we anticipate the actual coding to start
early next week. Efforts are still being made to understand Greg Sutton's code for the
biomechanical model since he is no longer on campus, and some comments are more helpful
than others.
----------------------------------------------------------------------------------------

----------------------------------------------------------------------------------------
23 Feb 2018
The main class, AplysiaNet, currently creates an Interface. The Interface class supports
all functionality; entry of all 4 stimulus parameters (chemical start, chemical end,
mechanical start, and mechanical end), checks that the entered values are valid, and
prepares to send those values to the network. The Neuron class is not yet started. Much
time this week was spent meeting with collaborators and redefining a poorly explained
aspect of the project; the design document has been updated to reflect these changes.
Also, a circuit diagram was proposed, which can also be found in the design doc.
----------------------------------------------------------------------------------------