aspuru-guzik-group / Qtorch

Copyright 2017 Eric Schuyler Fried, Nicolas Per Dane Sawaya, Alán Aspuru-Guzik

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

==================The qTorch Library================

There are three options to install the library: global installation, local installation, and docker. Here, we provide a tutorial for each. gcc/g++ is the compiler used to compile and run the library. The version of gcc/g++ must be recent enough support the C++14 standard library. Otherwise, errors like: "g++: error: unrecognized command line option '-std=c++14'" may appear. In this case, we suggest the user upgrade their gcc/g++ compiler to a more recent version.

::::::: Global Installation (Admin Permissions Required) :::::::::::

------- INSTALLING THE LIBRARY (REQUIRED FOR ANY TYPE OF USE) ------- Please type the command: "sudo make install" in a Unix command line to install globally for all users.

This next step is optional, but it will make it easier to write and link custom .cpp files that extend the library. If the user doesn't want to change any environment variables, they can simply run "make all", "make cut", or "make qtorch", then run the generated executables using ./bin/qtorch or ./bin/maxcutQAOA

Optional: The user should add the directories: /usr/local/bin and $HOME/usr/local/bin to the PATH environment variable. For bash shell users, this means modifying the $HOME/.bash_rc, $HOME/.bash_profile, or the $HOME/.profile file, so that every time the user logs in and opens a shell script, the PATH environment variable will change. Additionally, we recommend setting the LIBRARY_PATH environment variable as well to reference the directories that we install the library in.

----------- MAKING IT SO YOUR COMPILER CAN FIND THE EXECUTABLES ---------------

Simple commands for bash user (default shell) - please copy and paste into shell:

--THESE WILL SET THE PATH FOR THIS AND ALL FUTURE SHELL SESSIONS:--

echo 'export PATH=$PATH:/usr/local/bin:$HOME/usr/local/bin' >> $HOME/.bash_profile source $HOME/.bash_profile

--FOR ONLY CURRENT SHELL SESSION:--

export PATH=$PATH:/usr/local/bin:$HOME/usr/local/bin

--SET LIBRARY_PATH VARIABLE ONLY FOR CURRENT SHELL SESSION:--

export LIBRARY_PATH=$LIBRARY_PATH:/usr/local/lib:$HOME/usr/local/lib

--SET LIBRARY PATH FOR THIS AND ALL FUTURE SHELL SESSIONS:--

echo 'export LIBRARY_PATH=$LIBRARY_PATH:/usr/local/lib:$HOME/usr/local/lib' >> $HOME/.bash_profile source $HOME/.bash_profile

---------- LINKING THE LIBRARY ------------------------------------------------- For users with a customized shell startup script, we ask that you add /usr/local/bin and $HOME/usr/local/bin to your PATH environment variable. Additionally, add /usr/local/lib and $HOME/usr/local/lib to your LIBRARY_PATH environment variable.

If you set the LIBRARY_PATH variable, you can link the library with the compiler flag: -ltncontr, else link using -L/usr/local/lib -ltncontr

---------------- INCLUDING THE LIBRARY ---------------------------- Make sure to include the line: "#include "tncontr.hpp" at the top of any files that use the library, and link with the above linker flags.

::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::

::::::::::: Local Installation (Admin Permissions NOT NEEDED) ::::::::::::::::::

----------- INSTALLING THE LIBRARY (REQUIRED FOR ANY TYPE OF USE) ------------- Please type the command: "make installlocal" in a Unix command line to install globally for all users.

This next step is optional, but it will make it easier to write and link custom .cpp files that extend the library. If the user doesn't want to change any environment variables, they can simply run "make all", "make cut", or "make qtorch", then run the generated executables using ./bin/qtorch or ./bin/maxcutQAOA

Optional: The user should add the directory: $HOME/usr/local/bin to the PATH environment variable. For bash shell users, this means modifying the $HOME/.bash_rc, $HOME/.bash_profile, or the $HOME/.profile file, so that every time the user logs in and opens a shell script, the PATH environment variable will change. Additionally, we recommend setting the LIBRARY_PATH environment variable as well to reference the directories that we install the library in.

----------- MAKING IT SO YOUR COMPILER CAN FIND THE EXECUTABLES ---------------

Simple commands for bash user (default shell) - please copy and paste into shell:

--THESE WILL SET THE PATH FOR THIS AND ALL FUTURE SHELL SESSIONS:--

echo 'export PATH=$PATH:$HOME/usr/local/bin' >> $HOME/.bash_profile source $HOME/.bash_profile

--FOR ONLY CURRENT SHELL SESSION:--

export PATH=$PATH:$HOME/usr/local/bin

--SET LIBRARY_PATH VARIABLE ONLY FOR CURRENT SHELL SESSION:--

export LIBRARY_PATH=$LIBRARY_PATH:$HOME/usr/local/lib

--SET LIBRARY PATH FOR THIS AND ALL FUTURE SHELL SESSIONS:--

echo 'export LIBRARY_PATH=$LIBRARY_PATH:$HOME/usr/local/lib' >> $HOME/.bash_profile source $HOME/.bash_profile

---------- LINKING THE LIBRARY -------------------------------------------------

For users with a customized shell startup script, we ask that you add $HOME/usr/local/bin to your PATH environment variable. Additionally, add $HOME/usr/local/lib to your LIBRARY_PATH environment variable.

Link using: -L$(HOME)/usr/local/lib -I$(HOME)/usr/local/include

---------------- INCLUDING THE LIBRARY ---------------------------- Make sure to include the line: "#include "tncontr.hpp" at the top of any files that use the library, and link with the above linker flags.

:::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::

::::::::::::::::::::::::::::::::: Docker Installation ::::::::::::::::::::::::::: An alternative way of running qTorch is to run it inside a Docker container. This allows the user to use qTorch regardless of the local environment (operating system, package dependencies etc) of her machine. We provide the following Docker image on DockerHub: therealcaoyudong/qtorch, which contains the qTorch source code as well as the necessary libraries needed for building qTorch.

Here, we provide a step-by-step instruction on how to use the Docker image, assuming no prior experience with Docker.

1. Install Docker on your computer. Also VirtualBox is needed;

2. In a command terminal, run:

docker-machine ls

which returns a list of virtual machines. If the list is empty, create a virtual machine called default by running:

docker-machine create ---driver virtualbox default

3. Configure the shell to the virtual machine by running:

docker-machine env default

Run the command suggested by the returned message.

4. Now everything is set up, run the image using:

docker run -it therealcaoyudong/qtorch

It may take a while to download the image. When the download is complete, the shell header will look like "

docker ps