========================================================================
README for MD Visualizer 1.5
Copyright (c) 2019-2025 Oliver Kreylos
========================================================================

Overview
========

The MD Visualizer is a simple viewer for simulation traces from a
variety of molecular dynamics simulation codes. The MD Visualizer is
based on the Vrui software development toolkit (see
http://idav.ucdavis.edu/~okreylos/ResDev/Vrui), and runs in a variety of
environments ranging from laptop or desktop computers over semi-
immersive environments such as Geowalls to fully immersive virtual
reality environments such as CAVEs.

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

The MD Visualizer requires Vrui version 14.1 build 001 or
newer, and the Vrui Collaboration Infrastructure version 10.3 or newer.

Installation Guide
==================

It is recommended to download or move the source packages for Vrui and
the MD Visualizer into a src directory underneath the user's home
directory. Otherwise, references to ~/src in the following instructions
need to be changed.

It is also recommended to skip optional steps 4 and 6 in the following
instructions. The MD Visualizer does not need to be installed in order
to be used; installation (to a system directory such as /usr/local) is
only recommended if the MD Visualizer will be used from multiple user
accounts.

0.1. Install Vrui from ~/src/Vrui-<version>-<build> (see Vrui README file).
0.2. Install the Vrui Collaboration Infrastructure from
     ~/src/CollaborationInfrastructure-<version> (see Vrui Collaboration
     Infrastructure README file).

1. Change into ~/src directory and unpack the MD Visualizer tarball:
   > cd ~/src
   > tar xfz <download path>/MDVisualizer-<version>.tar.gz
   - or -
   > tar xf <download path>/MDVisualizer-<version>.tar

2. Change into the MD Visualizer base directory:
   > cd MDVisualizer-<version>

3. If the Vrui version installed in step 0 was not 14.1, or Vrui's
   installation directory was changed from the default of /usr/local,
   adapt the makefile using a text editor. Change the value of
   VRUI_MAKEDIR close to the beginning of the file as follows:
   VRUI_MAKEDIR := <Vrui install dir>/share/make
   Where <Vrui install dir> is the installation directory chosen in
   step 0. Use $(HOME) to refer to the user's home directory instead
   of ~.

4. Optional: Adapt makefile if the MD Visualizer is to be installed in a
   different location, for example /usr/local. Set INSTALLDIR to the
   desired target location. The MD Visualizer will then be installed in
   <INSTALLDIR>/bin (where <INSTALLDIR> is the value of INSTALLDIR set
   in the makefile).

5. Build the MD Visualizer:
   > make
   This creates the MDVisualizer executable in ./bin.

6. Optional: Install the MD Visualizr in the selected target location.
   This is only necessary if the INSTALLDIR variable in the makefile was
   changed. By default, the MD Visualizer can be run from its base
   directory. To install:
   > make install
   - or, if the target location is a system directory -
   > sudo make install
   This will copy all executables into <INSTALLDIR>/bin.

7. Optional: Add directory containing the MDVisualizer executable (in
   ~/src/MDVisualizer-<version>/bin in the default installation, in
   <INSTALLDIR>/bin otherwise) to the user's search path. This allows
   running the MD Visualizer from any directory. Using csh or tcsh:
   > setenv PATH ${PATH}:~/src/MDVisualizer-<version>/bin
   - or -
   > setenv PATH ${PATH}:<INSTALLDIR>/bin
   where <INSTALLDIR> is the target location set in the makefile.
   Using bash:
   > export PATH=${PATH}:~/src/MDVisualizer-<version>/bin
   - or -
   > export PATH=${PATH}:<INSTALLDIR>/bin
   These lines can also be added to the user's .cshrc or .bashrc files
   to make the additions persist between logins.

Running the MD Visualizer
=========================

These instructions assume that the MD Visualizer was installed in its
base directory, (see steps 4 and 6 above).

1. On MacOS X: Start X11. The MD Visualizer requires a running X server,
   but, if preferred, it can be started from a MacOS X terminal instead
   of xterm.

2. See Vrui's HTML documentation on Vrui's basic user interface and how
   to use the MD Visualizer.