neural-network-420pine64backup/README.md

See 420Project17fall.pdf

Use this script to download the data files, because I'm not hosting them here.

~~~~
mkdir "data"
for i in {0..28}
do
	wget "http://courses.cse.tamu.edu/daugher/misc/PPP/homeworks/data/${i}states.bin" -O "data/${i}.bin"
done
~~~~

I didn't include that as a shell script file because it's really better
in general for one to see the shell code they're running before they just
blindly trust a script to do what they want it to do.

# Setup

## Anaconda/Miniconda (optional)

For my implementation, I'm using a native Python 3 install on Linux.

However, if you want to be safe about preserving your Python environment
(essentially, if you want to compartmentalize your Python install so if you
mess up it won't affect your native Python environment), I suggest
instead installing Anaconda or Miniconda and going through the following process
from there in your terminal:

~~~
conda create -n project420 python
conda install -n project420 jupyter
conda install -n project420 tensorflow
conda install -n project420 keras
~~~

You can replace project420 with whatever you want to call the environment.

After those are installed, when you want to activate that Python environment,
(which you'll have to do if you open a new terminal window) type:
~~~
source activate project420
~~~

## Installing natively

### Linux

If you would rather just install the necessary things to your native Python
environment, then here are the things you will need if you're on Linux:

- TensorFlow (or equivalent backend for Keras)
- Keras
- Jupyter

I suggest installing them through your respective repository's repos if you can.

### Windows

Well... I didn't set up on Windows, but the packages you will need remain the same.

I would suggest considering using the native pip install method:

~~~
pip install tensorflow
pip install keras
pip install jupyter
~~~

# Getting Started

## Parsing the .bin files

Basically, we're being instructed to parse through these .bin files in order
to get "states" of a 15-piece puzzle, illustrated in the project documentation.

Each of these n.bin files contains the corresponding states that are n many
turns away from the solution. That part of the instruction is essential to
understand before we go any further.
To illustrate better: this means that 0.bin contains every state in which
the puzzle is 0 moves away from being solved, and so on for each n.bin file.

In order to parse these binary files, we need to tell python to read in the
file in binary mode and then we need to translate that binary to a hex string
format. I've already written out some preliminary code that will do the for
you in the included "test.py" script.

Just run:
~~~
python test.py
~~~

and the output that you are given is the only state in the 0.bin file, which
represents the state of the puzzle when it is solved.

There's a lot of terminology being thrown around in the documentation about
what this hex string means, so I'm going to simplify it:

Each letter in the hex string represents a 4 bit integer.

We know that hexadecimal values can only range from 0 to f (or, at least,
you should know considering you are a senior computer science major).

This means that every 4 bits that we read in correspond to a hexadecimal
character, which represents a value from 0 to 15. These corresponding
values map perfectly to our puzzle to represent which numbered tile is
in which space. If we refer back to our documentation we see that the first
row of the solved puzzle is "1, 2, 3 ,4", and the corresponding first 4
hex characters of our string are "f, 2, 3, 4", and so on.

Now you may be questioning why this isn't exactly the same as our puzzle.
This is where the concept of negative entropy can be explained. We don't
need to define what the first place in our puzzle is because we can deduce
it from what we already know. The puzzle only has 16 pieces, and we know
where the other 15 pieces are, so what's left is the piece 1. We remove
the first 4 bits because adding that information is simply unnecessary.

That much is explained to you now and I hope that can get you started
on understanding what we need to do as far as parsing the bin files.

## Using Keras

There are a lot of comments in the included Jupyter Notebook in this
github repo, but here's just how to get started and a brief explanation
of what we're doing here.

First, you'll want to run jupyter notebook to see what we're doing.

Jupyter is a tool for python that runs an interactive HTTP server that
can allow users to test python scripts and bits of python code as well
as write reports in an interactive fashion, it's typically used for
research, and what we're doing here will be much more helpful to be
able to quickly run constantly and make modifications.

To run Jupyter, just type into a terminal:
~~~
jupyter notebook
~~~

This will open an HTTP server that will then open a window in your
current default browser allowing you to select a notebook to open
from your filesystem.

Or, if you want to directly open the journal from command-line:
~~~
jupyter notebook neural_network.ipynb
~~~

# Well there you go

I hope that helps you guys get started... LMK if you have more questions.