Update README

README.md

@@ -1,3 +1,54 @@
 # LearnPI
 
-Supporting files to reproduce all figures in the article "Learning accurate path integration in ring attractor models of the head direction system".
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+Instructions to reproduce all main text, supplementary and mathematical appendix figures of the manuscript
+"Learning accurate path integration in ring attractor models of the head direction system".
+
+Instructions are based on default values of various parameters. After generating figures, please remember 
+to revert parameters to these default values.
+
+The figures are reproduced from saved networks. In order to generate the results from scratch, execute
+run_simulation.py with the desired parameters for each figure mentioned below. Simulation takes ~8 hours
+on a mid-range gaming laptop, while the reduced network drastically reduces simulation time to ~3 minutes.
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+- Fig. 1B,C, 2A-C, 3A-C,E,F, S3: Run generate_plots.py with vel_hist = True.
+
+- Fig. 2D: Run stability.py.
+
+- Fig. 3D, 4, S5E, S6A-C, S7A: Run multinet_plots.py. The diffusion coefficients for Fig. S5E were obtai-
+ ned by running stability.py with d_coeff = True for the corresponding networks.
+
+- Fig. S1: Run EB_synapses.py. The upper-left panel in Fig. S1A also appears in Fig. 1E.
+
+- Fig. S2: Run generate_plots.py with cut_exc = True.
+
+- Fig. S4: Run generate_plots.py with data_dir = '\\savefiles\\trained_networks\\Parallel\\Perturb_Conn\\'.
+ The networks were randomly generated, therefore results can vary. By varying the parameter 'run' in the 
+ dictionary params from 0 to 11, one can see multiple examples of such networks.
+
+- Fig. S5A-D: Run generate_plots.py with 'n_sigma': 0.7 in the dictionary params.
+
+- Fig. S6D,E: Run generate_plots.py with sim_run = '4Medium', PI_err = False and 'tau_s': 1 in the dictio-
+ nary params.
+
+- Fig. S7B: Run generate_plots.py with PI_err = False, and 'gain': .125 in the dictionary params.
+
+- Fig. S7C: Run generate_plots.py with PI_err = False and 'gain': 10 in the dictionary params. Also plot
+ margins in lines 761 and 766 need to be adjusted.
+
+- Fig. S7D-F: Run generate_plots.py with PI_err = False, sim_run = 'Long', and 'gain': -1 in the dictiona-
+ ry params.
+
+- Fig. S8: Run generate_plots.py with 'vary_w_rot': True and 'adj': True in the dictionary params.
+
+- Fig. S9: Run generate_plots.py with PI_example_dir = '\\savefiles\\PI_example1.npz', 'vary_w_rot': True
+ in the dictionary params and filename = "fly_rec" + util.filename(params) + 'NoLearn'. Also set 
+ err_lim = 180 in line 487.
+
+- Fig. S10: Run generate_plots.py with PI_example_dir = '\\savefiles\\PI_example_360_max.npz', PI_err = 
+ False, and 'rand_w_rot': True in the dictionary params.
+
+- Fig. A1-4: Run math_appendix.py.