Introduction
============

Date: 2018-01-17
Author: Sam Clark, CPFD Software, LLC

This folder contains files necessary for running the Barracuda timing problem.
The purpose of this problem is to provide hardware performance information.  The
timing problem is a generic system (a large version of the Wednesday Gasifier
problem from the Barracuda new user training materials), and is intended to test
both CPU and GPU speed.

For users who wish to provide timing information from their systems, CPFD
Software will collect, aggregate, and post timing statistics on our support
site.  This information will be anonymous, so that no specific customer could
be identified based on the timing information.  Step 6 in the run instructions,
below, discusses how to provide this information to CPFD.

Requirements
============

1. Barracuda 17.2.0 must be installed on your system.  If you need to download
   and install this version, please see this webpage:

   http://cpfd-software.com/customer-support/knowledge-base/barracuda-virtual-reactor-17.2-release

2. The Anaconda Python distribution must be installed on your system.  The run
   script is written in Python, and the Anaconda distribution provides several
   modules on which the script relies.  If you need to install this Python
   distribution, please see this webpage:

   http://cpfd-software.com/customer-support/knowledge-base/installing-the-anaconda-python-distribution

3. An extra package, 'py-cpuinfo', which is not included by default in the
   Anaconda Python distribution, must be installed.  This package is used to
   identify the CPU model installed in the system.  The RUN_TIMING_PROBLEM.py
   script will try to automatically install the 'py-cpuinfo' if it is not found
   on the system.  Note that this requires an active internet connection.
   
   If the automatic package installation fails, you can try manually installing
   it with the command:

   python -m pip install -U py-cpuinfo

4. The timing problem uses chemistry, GPU parallel, and CPU parallel.  If you do
   not have chemistry and parallel licenses, CPFD Software can provide short-
   term testing licenses for the purpose of collecting timing information.
   Email licensing@cpfd-software.com to request test licenses, if necessary.

5. In the default run sequence, about 20 GB of data will be produced.  Ensure
   that the hard drive has enough space to accomodate this.  Once the timing
   tests are complete, and you have emailed the timing results to CPFD, the
   entire timing problem directory can be deleted.

Running the Timing Problem
==========================

1. Stop all Barracuda simulations currently running on the system, as well as
   any other processes that heavily use the CPU, GPU, disks, or RAM.  In order
   to collect the best quality timing data possible, it is important to make
   sure that the Barracuda process has full access to the machine's resources.
   Therefore, it is necessary to stop any other resource-intensive processes,
   and ensure that no such processes are started again until the timing runs
   are complete.

2. Open the timing problem in the Barracuda 17.2.0 GUI.  For consistent timing
   information collection, it is important that all tests be performed with
   Barracuda version 17.2.0.

3. Generate the grid (the 00* files are not included by default, due to their
   large size).

4. Open a terminal from the Barracuda GUI.  This will ensure that the correct
   solver and other utilities are found, by setting up the environment in a
   standard way.  In the terminal, go up one directory using the command:

   cd ..

5. Start the run script.  The simplest (and most common) invocation is:

   python RUN_TIMING_PROBLEM.py

   When the script is started in this manner, it will run the default timing
   test sequence, which is:

   a. Run the timing problem in CPU-only mode
   b. Run the timing problem with CPU + GPU parallel
   c. Run the timing problem with CPU parallel + GPU parallel

   By running these three variations of the problem, timing information will be
   collected showing how fast both the CPU and GPU are capable of running.

   By default, all GPU cards on the system with enough memory to run the timing
   problem will be tested.  If you wish to limit the timing test to a single GPU
   card, or multiple specific GPU cards, use the --gpudevice flag to do so.  To
   see the GPUs available on your system, run:

   python RUN_TIMING_PROBLEM.py --listgpus

   For more complex invocations of the run script, use the "--help" flag and the
   script will output detailed usage information.

6. Email the results text file to: support@cpfd-software.com

   The results file will be named: <timestamp>_barracuda_timing_results.txt

   where <timestamp> is the date and time at which the script was started.
