INSTALLATION

This library is known to work on Ubuntu 22.04 using g++ 10.5.0, but it will
likely work with other configurations, too.  Lines starting with "$" are bash
commands.

1. Unzip the package into a directory called PhysBAM.  For the purposes of these
instructions, we will assume this is located at /home/user/PhysBAM.

2. Set your environment.

$ export PHYSBAM="/home/user/PhysBAM" # Point to your directory.
$ export PROJ="$PHYSBAM"/Projects
$ export PUBLIC="$PHYSBAM"/Public_Library
$ export PHYSBAM_DATA_DIRECTORY="$PHYSBAM"/Public_Data
$ export PHYSBAM_COMPILE_COUNT=4
$ export DEFAULT_ARCH=nocona
$ export PLATFORM=nocona

3. Set up our compilation command.  We will make an alias for it for convenience, but you could run it directly.

$ alias cs='nice scons --warn=no-duplicate-environment --warn=no-deprecated -Q --implicit-cache -u -j $PHYSBAM_COMPILE_COUNT'

4. Install dependencies.

$ sudo apt-get install scons cblas g++ scons libpng12-dev libjpeg62-dev
$ sudo apt-get install libavformat-dev libavcodec-dev libavutil-dev libglut3-dev freeglut3-dev bison flex

5. Move to your PhysBAM directory.

$ cd $PHYSBAM

6. The library is built using the Scons tool.  Next we need to configure the
build.  For this you will need a copy of the default SConstruct.options file.

$ cp Scripts/scons/SConstruct.options .

This sets some default configuration options.  Most compilation issues that you
run into can be corrected by changing this file or the build script (SConstruct)
directly.  This may be needed if you need to use a specific compiler or handle
non-standard install locations.

7. Build the library.  We will use the alias we made to do this:

$ cs

You can also compile in debug mode by running the commend

$ cs TYPE=debug

Notes on building: you may encounter issues with files containing "LEX" and
"YACC" in their names.  There are two issues here that you may encounter.  The
first is that scons is not correctly identifying the dependencies generated by
lex/yacc.  Running with "cs -k" will tell SCons to keep going, even past the
original build problem, which allows SCons to also get to the build step where
it calls lex/yacc to generate the missing headers.  Simply rerunning "cs -k" a
couple more times will resolve this problem automatically, as the missing
headers will now be available.

The second issue is that the "PROGRAM_YACC.cc" file that is generated (located
at build/release/Public_Library/Tools/Symbolics/PROGRAM_YACC.cc for release
builds) is constructed with an invalid include path.  This can be resolved by
opening up this file in a text editor and commenting out the include line:
#include "PROGRAM_YACC.hpp"

These issues should only occur the first time you compile.

8. Go to the mpm project.

$ cd Projects/mpm/sca-2022

9. Run the test cases.

$ ./run-all.sh 

This may take a long time, especially since some of the tests are quite large.
As written, this spawns all of the tests more or less at once.

The simulation output is placed in the current directory in subdirectories whose
names start with "out".  You can view 2d simulation results using the command

$ $PHYSBAM/Projects/opengl_2d/opengl_2d simulation-directory

You can view 3d simulation results using the command

$ $PHYSBAM/Projects/opengl_3d/opengl_3d simulation-directory

Note that these viewers are part of this package and will be built when you
compile form the root PhysBAM directory.  Pressing the '?' displays usage
shortcut keys that you can use to explore the simulation.  Use left/middle/right
drag to change the view, and shift-click objects to select them.
