TITLE: A Simple Exploration of Simulated Annealing: Protocol
AUTHORS: Chasz Griego

[DESCRIPTION]
This protocol describes technical steps to understand the computational environment for A Simple Exploration of Simulated Annealing hosted on Code Ocean.

[STEPS]
SECTION: Reproducing the Data Analysis
2. The analysis was completed with Python in a Jupyter Notebook. The following notebook is found in the code folder in the file manager:
 


SECTION: Reproducing the Data Analysis
1. Access the capsule for this project at Code Ocean. Select "Edit Capsule" to work with your own copy.






SECTION: Reproducing the Data Analysis
2.2. Data for the analysis is found in separate folders in the data folder in the file manager:

grid_sample: A .npy file of the sample grid used in simulated annealing
separated_grids: Multiple .npy files for every grid resulting from a simulation
simulation_data: Multiple .csv files with run details at every iteration of a simulation


SECTION: Reproducing the Data Analysis
2.1. Details about the computational environment, including the versions of Python, Jupyter, and other libraries are found in the environment section of the file manager, which contains a Dockerfile.
SECTION: Reproducing the Data Analysis
4. Once the reproducible run is complete, the resulting figures, an HTML copy of the executed analysis.ipynb, and a run output log are stored in the results section found in the file manager.
SECTION: Reproducing the Data Analysis
3. To execute analysis.ipynb, select "Reproducible Run"
SECTION: Running Additional Simulations and Producing New Data
5. Each simulation can be run again, with the same sample grid, by executing the following Jupyter Notebook found in the code folder:

 

SECTION: Running Additional Simulations and Producing New Data
6. WARNING: Running production.ipynb will overwrite all of the data in each subdirectory of data.
SECTION: Running Additional Simulations and Producing New Data
6.1. Copy each subdirectory in a new folder with a title such as "original" or something that is more descriptive. Do this before each subsequent run of production.ipynb. Update file paths in analysis.ipynb if you wish to analyze data that was moved.
SECTION: Running Additional Simulations and Producing New Data
7. Modify line 10 of the run file inside the code section to select production.ipynb to run in a reproducible run:
 

SECTION: Running Additional Simulations and Producing New Data
8. Select "Reproducible Run" to run additional simulations and produce new data.
SECTION: Running Additional Simulations and Producing New Data
9. To reanalyze the new data, modify line 10 of the run file to select analysis.ipynb.

 

SECTION: Running Additional Simulations and Producing New Data
10. Select "Reproducible Run" to execute a new analysis.
SECTION: Running Simulations with Different Parameters
11. There are various ways to alter parameters to run additional simulations:
SECTION: Running Simulations with Different Parameters
12. There are several parameters that can be changed in production.ipynb to produce a new sample grid:
rows: number of rows in the grid
cols: number of columns in the grid
percentage: composition of 1's in the randomly generated grid of mixed 1's and 0's
seed: defines the random number seed used to generate the random mixture of 1's and 0's
SECTION: Running Simulations with Different Parameters
12. In production.ipynb, there are two schemes of simulations that are run:

Testing various numbers of iterations in each simulation
Testing various temperature settings in each simulation

For each variable tested, 5 simulation trials are run. 
SECTION: Running Simulations with Different Parameters
13. Change any of these parameters (individually or in combination), and after running production.ipynb, a new .npy file will be generated in data/grid_sample.


 

SECTION: Running Simulations with Different Parameters
14. Repeat all steps in "Running Additional Simulations and Producing New Data" to produce new data from the new sample. 
SECTION: Running Simulations with Different Parameters
13. These parameters can be found and altered in various locations in the notebook:


 

SECTION: Running Simulations with Different Parameters
13.1. To change the numbers of iterations, edit the first line of code in the fourth code block:


 

This code employs a NumPy function called logspace. It generates an array of numbers that are evenly spaced on a logarithmic scale. The first argument 1 is the starting value of the sequence. The second argument 5 is the ending value of the sequence. The third argument 5 is the number of elements in the generated array. The current code creates an array containing 5 elements, with values ranging from 10^1 (10) to 10^5 (100000) evenly spaced on a logarithmic scale.

If you want to edit this line of code, you can change the arguments of the logspace function to generate a different array of numbers. For example:


 


SECTION: Running Simulations with Different Parameters
13.2. To change the temperature settings, edit the first line of code in the fifth code block:

 

This code employs another NumPy function called linspace. It generates an array of numbers that are evenly spaced between the specified start and end values, with a specified number of elements. The first argument 100 is the starting value of the sequence. The second argument 10 is the ending value of the sequence. The third argument 10 is the number of elements in the generated array.

The linspace function will create an array containing 10 elements, with values ranging from 100 to 10, spaced evenly between these two values. If you want to edit this line of code, you can change the arguments of the linspace function to generate a different array of numbers. For example:


 

SECTION: Running Simulations with Different Parameters
13.3. To change the number of simulation trials, in both the fourth and fifth code blocks, the second line of code defines the number of trials:


 

To either increase or decrease the number of trials from 5, edit the number in the range function.
SECTION: Running Simulations with Different Parameters
14. Repeat all steps in "Running Additional Simulations and Producing New Data" to produce new data  with the new simulation settings.