.

Thoth, v. 5.0


Russ Laher (laher@ipac.caltech.edu)
IPAC, California Institute of Technology, MC 100-22, Pasadena, CA 91125
Copyright 2010-2018, All rights reserved.

Software Documentation

An introduction to Thoth, as well as more detailed documentation, can be found here.

System Requirements

Thoth is an all-Java software implementation. There are no software dependencies on other astronomical packages or libraries. However, you will need to have a recent version of the Java Runtime Environment (JRE) installed on your machine. This version of Thoth was compiled with javac 1.6.0_65.

Thoth can be installed and run on any machine with the JRE installed. This includes, but is not limited to, machines running Mac, Windows, Linux, and Solaris operating systems.

Software Download

Download platform-independent Thoth in the preferred package from here:

Thoth PackageMD5 Checksum
*.tar file c5806848ea8e7ab8d5abbac6b1881184
*.zip file 73b1d655d92ed6440b15afe12033a8c8
*.dmg file (for Macs only) 8cf903824054a3ffb7cdc57a8fcadc1a

Customizing Thoth's Database Settings

To use Thoth, you will need to set up a default database connection. To do this, you need to download the following files and then copy them to your home directory (which is a location that is looked up by the software and commonly denoted as ~/ on non-Windows machines):

thoth.run.properties

thoth.query.deliveries.properties
thoth.query.exposures.properties
thoth.query.jobs.properties
thoth.query.nights.properties
thoth.query.procimages.properties
thoth.query.rawimages.properties
thoth.query.sdqa.properties
thoth.query.versions.properties

These are plain-text files, which you can edit as needed (more on that below). The first file gives an example of how to connect to four different databases. If the first file is to contain passwords, then file permissions must be set so that only the user can view its contents. The database connections are numbered in the first file for differentiation. The second set of files (thoth.query.*.properties) contain canned database queries organized under different names (denoted by the wildcard character *). The names can be changed to those that make sense to the user. The idea behind the second set of files is that users will want to create a similar set containing commonly-used queries for all of their own databases.

The first time Thoth is executed, it will create a hidden directory in the user's home directory, called ".Thoth". Once this has been done, the user may choose to move thoth.run.properties and thoth.query.*.properties to ~/.Thoth as a means of decluttering ~/. Note that upon start up of a new Thoth session, the aforementioned properties files are, by default, loaded from the user's ~/.Thoth hidden directory. Thoth also makes, by default, a database connection to ~/.Thoth/thoth.db (a SQLite scratch database created by Thoth, the purpose of which is discussed in the software documention), which is a connection that does not need to be listed in the thoth.run.properties file.

The thoth.run.properties file contains database-connection settings. You need to know the name of the database to which you want to connect, your database account name, and password if required. In the example thoth.run.properties file above, none of the database connections actually require a password, and only two of the database connections acturally require an account name. Specific differences in specifying the database URL for Windows are explained at the end of the Windows section below.

The thoth.query.*.properties files above contain common database queries for the operations database of the Palomar Transient Factory (http://ptf.caltech.edu/iptf/), as an example. You can edit these files and replace the queries with your own favorites. Each new query added MUST have a unique name, which can be arbitrarily specified. You can also create new thoth.query.*.properties files, where * is an arbitrary name. When Thoth is executed, the names are used to name the tabbed panes in which the canned queries are organized.

General Installation and Execution Instructions

Except for Thoth packaged as a double-click Mac application or as a double-click Windows application, Thoth is launched via the Thoth.csh script on UNIX-based machines, which contains

#! /bin/csh

echo "THOTH_ARCH=$THOTH_ARCH";
echo "THOTH_HOME=$THOTH_HOME";

if ($THOTH_ARCH == "MAC") then
    java -mx4096M -Xdock:name="Thoth" -Xdock:icon=$THOTH_HOME/Thoth.app/Contents/Resources/Thoth.icns -jar ${THOTH_HOME}/Thoth.jar
else
    java -mx4096M -jar ${THOTH_HOME}/Thoth.jar
endif

For Windows machines, there is a Thoth.bat file, which is similar in functionality to the UNIX-based Thoth.csh file.

If you will be using Thoth.csh or Thoth.bat to launch the software, you must set the following environment variables:

THOTH_ARCH
THOTH_HOME
PATH
Common settings for THOTH_ARCH are "MAC", "WIN", "LINUX", or "SOLARIS". THOTH_HOME must be set to the directory containing the file Thoth.jar. The PATH setting must be augmented with the same location as THOTH_HOME.

If the platform-specific instructions below do not work for your particular machine, you might try modifying Thoth.csh (or Thoth.bat in the case of Windows) to include the required environment settings at the very top of the file.

If, when running Thoth, you get out-of-memory errors, you might try modifying -mx4096M to a larger value (this specifies the heap size). For Mac users running Thoth as a double-click application, you can similarly edit the -Xmx4096M specification in "/Applications/Thoth.app/Contents/Info.plist" to allocate more memory.

The platform-specific instructions below are written for uncompressing and expanding the downloaded *.tar file via the "tar" command. If you prefer to download the *.zip file, the "unzip" command should be used instead to uncompress and expand the file.

Platform-Specific Installation and Execution Instructions

Mac

You have the options of installing Thoth as a double-click application, a command-line application, or both.

Double-Click Application

The easiest way to install Thoth on a Mac is to download the *.dmg file, double click on it to bring up the Thoth folder (if it doesn't open up by itself), open up another Finder window and change directories to the Applications folder, and then drag the Thoth icon to the Applications folder.

This method of Thoth installation will result in a double-click Mac application, which you can add to your dock for convenient access to Thoth as a single-click application.

Finally, if you want to install Thoth in a location different from /Applications or you want switch GUI options in the *.dmg package that you downloaded, then you will need to change Thoth's environment settings. To change Thoth's environment settings, you simply do the following:

  1. Drag Thoth icon to your home directory (commonly denoted as ~/);
  2. Edit the settings in "~/Thoth.app/Contents/Info.plist" as appropriate (search for the dictionary with key "LSEnvironment" at the end of this file, and make your changes there); and then
  3. Drag Thoth icon to your installation directory of choice.

On newer Macs, the following error may be displayed upon attempting to install the software: "Thoth" is damaged and can't be opened. However, the file is not damaged (and one can verify the MD5 checksum), and should work just fine after the security settings are (temporarily) loosened. To do this, change your

System Preferences > Security & Privacy > General 
to "Allow apps to be downloaded from Anywhere".

You may have to do the following terminal fix to get the "Anywhere" option back, as it disappeared from a later Mac OSX version:

System Preferences > Security & Privacy
  1. Close System preferences
  2. Open a Terminal window
  3. Enter
    sudo spctl --master-disable
  4. Enter Password
  5. Click on
    System Preferences > Security & Privacy > Anywhere
  6. Open Thoth application
  7. To restore the higher-security setting, click
    System Preferences > Security & Privacy > Appstore and Identified Developers

Command-Line Application

Installation instructions for tar file:

     cp Thoth_v5.0.tar /Applications
     cd /Applications
     rm -rf Thoth_v4.9 (if you installed it here last time)
     tar xvf Thoth_v5.0.tar
     rm Thoth_v5.0.tar

Now, you need to set up your environment. If your default shell is bash, add these lines to your .bash_profile file:

     export THOTH_ARCH=MAC
     export THOTH_HOME=/Applications/Thoth_v5.0
     export PATH=$THOTH_HOME:$PATH
If your default shell is csh or tcsh, add the following lines to your .cshrc file:
     setenv THOTH_ARCH MAC
     setenv THOTH_HOME /Applications/Thoth_v5.0
     setenv PATH ${THOTH_HOME}:${PATH}

Execution instructions:

  1. Bring up a new terminal window.
  2. Change to a working directory.
  3. Execute the following command in the new terminal window:
     Thoth.csh

Linux

Installation instructions for tar file:

     cp Thoth_v5.0.tar ~/Applications
     cd ~/Applications
     rm -rf Thoth_v4.9 (if you installed it here last time)
     tar xvf Thoth_v5.0.tar
     rm Thoth_v5.0.tar

Now, you need to set up your environment. If your default shell is bash, add these lines to your .bash_profile file:

     export THOTH_ARCH=LINUX
     export THOTH_HOME=~/Applications/Thoth_v5.0
     export PATH=$THOTH_HOME:$PATH
If your default shell is csh or tcsh, add the following lines to your .cshrc file:
     setenv THOTH_ARCH LINUX
     setenv THOTH_HOME ~/Applications/Thoth_v5.0
     setenv PATH ${THOTH_HOME}:${PATH}

Execution instructions:

  1. Bring up a new terminal window.
  2. Change to a working directory.
  3. Execute the following command in the new terminal window:
     Thoth.csh

Solaris

Installation instructions for tar file:

     cp Thoth_v5.0.tar ~/Applications
     cd ~/Applications
     rm -rf Thoth_v4.9 (if you installed it here last time)
     tar xvf Thoth_v5.0.tar
     rm Thoth_v5.0.tar

Now, you need to set up your environment. If your default shell is bash, add these lines to your .bash_profile file:

     export THOTH_ARCH=SOLARIS
     export THOTH_HOME=~/Applications/Thoth_v5.0
     export PATH=$THOTH_HOME:$PATH
If your default shell is csh or tcsh, add the following lines to your .cshrc file:
     setenv THOTH_ARCH SOLARIS
     setenv THOTH_HOME ~/Applications/Thoth_v5.0
     setenv PATH ${THOTH_HOME}:${PATH}

Execution instructions:

  1. Bring up a new terminal window.
  2. Change to a working directory.
  3. Execute the following command in the new terminal window:
     Thoth.csh

Windows

The easiest way to install Thoth on a Windows machine is to download the zip file, double click on it to bring up the WinZip extraction tool, then click on the extract button and save the Thoth files in a directory of your choice (e.g., C:\Thoth).

Normally, the user will double click on the Thoth.exe binary executable to run Thoth, which is located in the installation directory. The user can create a shortcut to Thoth.exe and place it on the desktop for convenience in running the software each time. This is the preferred method of running Thoth, and requires no additional installation steps (as the runtime environment and Java location is fully determined Thoth.exe).

If you plan to run Thoth.bat instead of Thoth.exe as an alternate means of launching Thoth, you must set up the environment for Thoth, and this is described further below in this section.

System requirements for Thoth: you must have java installed (version 1.6.1_65 or greater). To find this out, type the following command in a Command-Prompt window:

C:\>java -version
You should see a response like
java version "1.6.1_65"
Java(TM) SE Runtime Environment (build 1.6.1_65-b11-457-11M4509)
Java HotSpot(TM) 64-Bit Server VM (build 21.01-b01-457, mixed mode)
If your java version is less than 1.6.1_65, you must first download and install the JDK from www.sun.com.

Now, you need to set up your environment (only if you will run Thoth.bat instead of Thoth.exe). Add the installation subdirectory to your path using the following steps:

  1. Bring up the following menu:
      Start > Control Panel > System > Advanced > Environment Variables
      
  2. Under "System variables", look for the "Path" variable, click on it, then hit the "Edit" button, and then add
      ;C:\Thoth\Thoth_v5.0
      
    to its current setting (assuming that is where you installed the Thoth package). Note the use of the beginning semi-colon delimiter and backslashes ("\") in the path.

  3. Under "User variables for Administrator", hit the "New" button to add the following required variable:
      Variable Name: THOTH_HOME
      Variable Setting: C:\Thoth\Thoth_v5.0
      
  4. Under "User variables for Administrator", hit the "New" button to add the following required variable:
      Variable Name: THOTH_ARCH
      Variable Setting: WIN
      

Execution instructions:

You can run Thoth simply by double-clicking on the "Thoth.exe" file in a Windows Explorer window.

You can also run Thoth by double-clicking on the Windows batch file "Thoth.bat" in a Windows Explorer window (this is not recommended as the normal runtime method, but can be useful if more memory needs to be allocated by increasing the memory parameters in Thoth.bat).

You can also run Thoth from either a Command-Prompt window or a Cygwin window:

  • From a Command-Prompt window:
         Thoth.bat
      
  • From a Cygwin window:
         source Thoth.csh
      

It is also possible to run Thoth from a C shell or Korn shell window (provided that you have the shell of interest installed), but you must first take care to set up the environment properly.

Finally, it is noted that the Windows file system uses the backslash character (\) to delimit a directory/filename tree. Since Java uses the backslash character as an escape charactor, a double backslash must be used as the delimeter on Windows in Java input files. In the example thoth.run.properties file above, which is set up for UNIX-type file systems, the change in the database URL for Windows would look something like the following:

databaseUrl2=jdbc:sqlite:C:\\Databases\\russ.db
which indicates the SQLite database russ.db is located on the C: drive at
C:\Databases\russ.db