
\documentstyle[a4,html]{article}
\pagestyle{empty}
% DIN A4
\setlength{\topmargin}{0.46cm}
\setlength{\oddsidemargin}{0.46cm}
\setlength{\textwidth}{15cm}
\setlength{\textheight}{22cm}

\def\undertext#1{$\underline{\smash{\hbox{#1}}}$}

\def\ni{\noindent}
\def\sk{\smallskip}
\def\ms{\medskip}
\def\bs{\bigskip}
\def\vs{\vspace*}
\def\hs{\hspace*}

\bodytext{<BODY  text="#000000" bgcolor="#ffffff">}

\begin{document}

\vspace*{4cm}

\begin{center}

\huge{\bf Nightfall User Manual}
\end{center}

\vspace*{2cm}

\begin{center}
\large{\bf 
  by R. Wichmann\\
  (rwichman@lsw.uni-heidelberg.de)
}
\end{center}

\newpage

\tableofcontents

\newpage
\begin{rawhtml}
<HR>
\end{rawhtml}

\section{Introduction}

\noindent
{\sc nightfall} is an interactive application that introduces into 
the fascinating realm of eclipsing binary stars. Apart from their light
variations that make them interesting objects for observations,
eclipsing binaries are of fundamental importance for astrophysics, e.g.
for measuring the mass of stars. 
{\sc nightfall} is capable of producing:

\begin{itemize}
   \item animated views of eclipsing binary
         stars,
   \item lightcurves and radial 
         velocity curves,
   \item best-fit binary star parameters for a given set of observational data.
\end{itemize}
It is, however, not able to fry your breakfast
egg on your harddisk.\\


\noindent
Eclipsing binary stars are most often very close systems. In such systems,
owing to tidal forces, the shapes of both stars can be highly nonspherical,
up to the possible formation of an 'overcontact' system, where both stars
form a single, dumbbell-shaped object.\\


\noindent
{\sc nightfall} is a mildly ultramundane program of baroque complexity
(I like Verdi and H\"andel on lazy sunday mornings - friday evenings are
better with Iron Maiden and a good whisky). 
{\sc nightfall} is based on a physical model that 
takes into account the nonspherical
shape of stars in close binary systems, as well as mutual irradiance
of both stars, and a number of additional physical effects.\\

\noindent
{\sc nightfall} can handle a large range of configurations, including
overcontact systems,
eccentric (non-circular) orbits, 
surface spots and asynchroneous rotations (stars rotating
slower or faster than the orbital period), and the possible presence of a
third star in the system.\\

\noindent
{\sc nightfall} supports OpenGL (or MesaGL) for an animated display of
binary systems. Individual frames of the animation can be saved as JPEGs
to create am MPEG movie.\\

\noindent
{\sc nightfall} can be build in a parallelized version, if you have
an implementation of MPI (i.e. an MPI library) installed. \\

\noindent
{\sc nightfall} supports the GNOME desktop (if installed), but does
{\it not} require it.\\
Also, {\sc nightfall} supports {\it internationalization}. Currently,
besides the default language (english), only german is supported. The
language is selected by the environment variable LANG (must be set
before starting the program,
in sh, bash: {\tt LANG=de; export LANG}\\
in csh, tcsh: {\tt setenv LANG de}).

\subsection{Remarks}

\noindent
{\sc nightfall} is not part of my
research work - rather it is the result of a recreational activity aimed
at distracting myself
from daily research work.\\

\ni
I have tested {\sc nightfall} with published data on several binary stars.
Data for these systems are included in the source code 
distribution. As no two light curve programs use exactly the same
algorithms, results are never identical; however, results from
 {\sc nightfall} appear to be within the range of similar 
light curve programs used in the literature. I hope 
that I have found most flaws in the logic of the code, at least in the
'scientific' part. If you want to use
{\sc nightfall} for a publication, you may want to evaluate its
performance by yourself. 
{\sc nightfall} comes WITHOUT ANY WARRANTY 
(see also  
\hyperref
  {the copyright statement}
  {Section } 
  {\ }
  {copyright}                           
for more information).

\subsection{Bugs}

\ni
Several, probably.
If you find a bug and can eliminate it, send me a diff. If you find a bug
and can't cope with it, send me a report, and wait for the next version.
If you would like a feature, tell me.

\subsection{Copyright}

\noindent
{\sc nightfall} is copyright (c) 1998-2002 Rainer Wichmann, (c) 2001-2002
Markus Kuster, (c) 2001-2002 Patrick Risse 
\label{copyright}
\\

\ni
{\sc nightfall} is free software; you can redistribute it                
and/or modify                                                         
it under the terms of the GNU General Public License as               
published by                                                          
the Free Software Foundation; either version 2 of the License, or     
(at your option) any later version.\\               
   
\ni                                                                   
{\sc nightfall} is distributed in the hope that it will be useful,       
but WITHOUT ANY WARRANTY; without even the implied warranty of        
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the         
GNU General Public License for more details.\\                          
   
\ni                                                                   
You should have received a copy of the GNU General Public License     
along with this program; if not, write to the Free Software           
Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.             

\ni
This document is considered part of the {\sc nightfall} program.

\newpage
\begin{rawhtml}
<HR>
\end{rawhtml}

\section{Requirements and Installation}

\subsection{Requirements}

\ni
{\sc nightfall} has been developed with the aim of being able
to compile and run the program on a typical Linux system without
any need of downloading/installing additional libraries or programs.
Although I have not tested this, {\sc nightfall} should compile
on other Unix systems as well.\\ 

\ni
For command line use/file output, all you need is a C compiler (e.g. gcc). 
For interactive use and plotting, {\sc nightfall} requires additional
libraries/programs, which, however, should already be included in
your Linux distribution (most probably). All required libraries/programs
are available for a wide variety of Unix systems.\\

\begin{itemize}

  \item
  {\bf For interactive use} of {\sc nightfall}, a GUI is provided, 
  which is based 
  on the GTK library (available at http://www.gtk.org, GNU Library General 
  Public License). GTK should compile on most Unix systems. 
  If you have a recent Linux distribution, GTK should 
  already be included (Debian: libgtk1.2, libgtk1.2-dev). 
  To see whether GTK is installed, try to run

  \$  gtk-config --libs

  which should yield something like: '-L/usr/lib -L/usr/X11R6/lib -lgtk 
  -lgdk -lglib -lXext -lX11 -lm' (might be different for your system).
  If you get a message like 'sh: gtk-config: not found', you might
  need to install GTK.  (On SuSE Linux -- and maybe other distributions --,
  GTK is split in two packages.
  For running GTK applications, you need only the 'gtk' package. For compiling 
  applications (like {\sc nightfall}), you also need the 'gtkdev' package.
  Debian package names: libgtk1.2, libgtk1.2-dev)

  \item
  {\bf For plots and graphs}, {\sc nightfall} requires either

  \begin{itemize}

     \item
     {\sc GNUPLOT}, version 3.5 (pre 3.6) patchlevel beta 347, or higher
     (Debian: gnuplot). 
     Earlier versions may or may not work. You need a version with 'multiplot'
     support. To verify this, try:

     \$ gnuplot\\
     gnuplot\$ set multiplot

     If you get an error message, you have to update your GNUPLOT.\\
     You also need write permission to the directory '/tmp' on your system.
     To test this, try:

     \$ touch /tmp/foo
     
     \item
     or the {\sc PGPLOT} Fortran graphics subroutine library 
     (Debian: pgplot5, also available at:

       http://astro.caltech.edu/~tjp/pgplot
 
     free for non-commercial use). You need a Fortran compiler
     (g77 is fine) to compile it. You have to compile it with 
     the Xserver and postscript drivers, and also have to compile
     the C wrapper library that comes with {\sc PGPLOT}.
     
  \end{itemize}

  \item
  {\bf For OpenGL support}, {\sc nightfall} requires

  \begin{itemize}

    \item
    {\sc OpenGL} or  {\sc MesaGL} (Debian: xlibmesa3, xlibmesa3-dev),
	
    \item
    {\sc GLUT}, the OpenGL Utility Toolkit
    (Debian: glutg3, glutg3-dev),

    \item
    {\sc gtkglarea} (Debian: gtkglarea5, gtkglarea5-dev), and

    \item
    {\sc libjpeg} (Debian: libjpeg62, libjpeg62-dev).
     
  \end{itemize}

  \item
  For building a {\bf parallelized version}, {\sc nightfall} requires
  a MPI (Message Passing Interface) library. If your vendor does
  not supply one, you may consider the MPICH library, which is freely
  available from http://www-unix.mcs.anl.gov/mpi/mpich/. With
  MPICH, you can easily run a parallelized version of {\sc nightfall}
  e.g. on a cluster of networked PCs (Debian: mpich).\\

  MPI parallelization has been tested with the MPICH library on a 
  Linux PC cluster. The MPICH library has been compiled using the
  flags {\it ./configure --with-device=ch\_p4 -rsh=ssh}.

  \item
  If you have installed the Gnome Desktop on your system, {\sc nightfall} 
  will build with support for it. However, Gnome is {\it not} required
  for {\sc nightfall} - it compiles just as well without Gnome.


\end{itemize}

\ni
{\bf Note}: With GNUPLOT, plots are not that nice sometimes, but
animated mode runs much smoother with GNUPLOT than with PGPLOT. 
GNUPLOT does not support
incremental plotting and display of images, thus a few options are
only available with PGPLOT.

\newpage

\subsection{Installation}

\ni
After downloading the source code, do:\\

\ni
\$ gunzip -c  nightfall-{\it (version number)}.tar.gz $|$ tar -xvf -\\
\$ cd nightfall-{\it (version number)}\\
\$ ./DoInstall.sh\\

\ni
The 'DoInstall.sh' script will query you for some information (e.g. where
to install the program),
and then (optionally) build, test, and install the application.
If you want to do it by hand, instead of './DoInstall.sh' run the following
sequence of commands:\\

\ni
\$ ./configure\\
\$ make\\
\$ make install\\

\ni
If you want to use {\sc PGPLOT}, 'configure' might find it by itself; 
otherwise 
you might need the 'configure' option\\
'--with-pgplot-include=PFX' (where PFX should be the directory where 
the PGPLOT header file cpgplot.h is installed), and 
'--with-pgplot-lib=PFX' (where PFX should be the directory where the 
PGPLOT library files libpgplot.a, libcpgplot.a are installed).\\

\ni
If you want to build a {\bf parallelized version}, you need 
the 'configure' option '--enable-mpi', {\bf and} you need to
set the compiler flags to
indicate the location of include and library files, if these are not
in the default search path. There are two ways to do this:\\


(a) The MPICH library provides a C compiler
wrapper 'mpicc' that will automatically set the correct flags, so
if mpicc is in your PATH, you may just say (for compiling with
PGPLOT, you need also the Fortran77 compiler wrapper 'mpif77'): \\
\$ ./configure --enable-mpi CC=mpicc F77=mpif77\\
or\\
\$ ./configure --with-gnuplot --enable-mpi CC=mpicc\\

(b) If this fails (e.g. because ./configure may not find the correct
preprocessor), you have to specify the correct flags: \\
\$ mpicc -show\\
cc -DUSE\_STDARG -L/usr/local/lib -lmpich\\
\$ ./configure --enable-mpi CC=cc CFLAGS='' -DUSE\_STDARG'' LIBS=''-L/usr/local/lib -lmpich''\\

\subsubsection{Install locations}

By default, the binary is installed to /usr/local/bin, the 
data/help/configuration files to \\
/usr/local/share/nightfall. If you don't
like this, use the 'configure' option
'--prefix=/where/to/install', where '/where/to/install' will
replace '/usr/local'.

\subsection{Compile/configure problems}

  If you want to use a different compiler, you can supply the
  option CC=myCCompiler to {\tt configure} (and also F77=myFortranCompiler,
  if you compile with PGPLOT).
 
\begin{itemize}

  \item Have gnuplot, but configure does not find it
   
  \begin{itemize}
    \item is gnuplot in your path ?
    if no, update your PATH environment variable

    \item does it support 'set multiplot' ?
      ( start interactively by typing 'gnuplot',
          then type 'set multiplot' to test)
    if no, update your gnuplot

    \item does 'gnuplot\_x11 -persist' work, or does it
      give an error message like:
         gnuplot: bad option: -persist ?
    if error, update your gnuplot

    \item There was at least one gnuplot version that
      supports the required 'multiplot' option, but does not
      list it as supported. 
      In this case, enforce gnuplot support with:\\
      {\tt ./configure --with-gnuplot}
  \end{itemize}
   
    
  \item Have gnuplot and pgplot, want gnuplot support

  \begin{itemize}
   \item use:\\
      {\tt ./configure --with-gnuplot}
   \end{itemize}
  
  \item  Have pgplot, but configure does not find it

  \begin{itemize}
   \item do you have a fortran compiler (required) ?

   \item the following files are required:
      cpgplot.h, libcpgplot.a, libpgplot.a\\
     Use {\tt ./configure --with-pgplot-include=/my/pgplot/include/dir 
     --with-pgplot-lib=/my/pgplot/lib/dir}, \\
     where '/my/pgplot/include/dir' is the directory where
     cpgplot.h is located, and '/my/pgplot/lib/dir' is the directory
     where libcpgplot.a, libpgplot.a are located.
   \end{itemize}

  \item Have pgplot, get compile error

  \begin{itemize}
   \item maybe your fortran compiler does not understand the
     link options required by Gtk.
     upgrade to a recent version of g77.

   \item maybe pgplot was compiled with a different fortran compiler.
     Recompile it with the fortran compiler found by configure, or 
     convince configure to use a different compiler (use the 
     configure option F77=myFortranCompiler and/or CC=myCCompiler). 
   \end{itemize}

  \item Other compile errors

  \begin{itemize}
  \item There might be problems related to internationalization,
     that may be caused by a broken installation of a respective
     utility on your system.
     For solving this, you should choose one of the
     following switches for the 'configure' script:\\
      {\tt --disable-nls}\\
      {\tt --with-included-gettext}\\
     like, e.g.:    {\tt ./configure --with-included-gettext}\\
     The first switch will completely disable internationalization,
     i.e. only the english version will be available.
     The second switch will use the internationalization
     program that is included in this source code distribution,
     thus bypassing any preinstalled, maybe broken, utility on
     your system.
  \end{itemize}


\end{itemize}




\subsection{Compile-time configuration}

\ni
Several aspects/limits of {\sc nightfall} can be configured at
compile time. Mostly, these are related to fixed array sizes.
For most users, the defaults should be sufficient.

\ni 
To configure, edit the file 'Light.h' and change the default value(s) of
the '\#define ITEM' statement(s) in the first section of this file
(where 'ITEM' stands for any of the bold words on the list below).
Configuration options include (but are not limited to):
\begin{itemize}

    \item NIGHTFALL\_PLOTFILE -- the name of the output plot file 
          (default is 'Nightfall.ps').

    \item STEPS\_PER\_PI, MAXELEMENTS -- the number of surface elements 
          for stars. This number cannot be set
          exactly, as the algorithm determines it at run time, trying to
          achieve a more or less constant area per surface element (for the
          lightcurve computation, of course the exact surface area is taken
          into account). You can, however, set the number of steps per
          one Pi (= 180 degree) on the equator, which is
          STEPS\_PER\_PI.
          You also have to adjust
          the size of the array holding the surface, which is
          MAXELEMENTS.

    \item MAXOBS -- the maximum number of observational data per filter 

    \item PHASESTEPS -- the maximum number of steps for a full orbit

    \item N\_SPOT --  the maximum number of spots per star 

    \item GNU\_GEOMETRY -- the plot window geometry, if you use {\sc GNUPLOT} 
          as plotting program\\
          Please note: it is not possible to fully 
          specify the {\sc PGPLOT} plot window
          geometry from within the program.
          It can be defined (in pixels) by:\\
          X resource: pgxwin.Win.geometry: WIDTHxHEIGHT+X+Y\\
          or environment variable: PGPLOT\_XW\_WIDTH 
          [fractional display width].\\
          PGPLOTS's default is width=867, height=669 and aspect=8.5/11.\\
          If PGPLOT\_XW\_WIDTH is undefined, {\sc nightfall} will set
          it to scale down the window width to the GNU\_GEOMETRY width.\\
          Set PGPLOT\_XW\_WIDTH to 1.0, if you don't like this\\ 
	  (bash, ksh: 'PGPLOT\_XW\_WIDTH=1.0; export PGPLOT\_XW\_WIDTH' \\
          csh, tcsh: 'setenv PGPLOT\_XW\_WIDTH 1.0').

    \item OUT\_FILE, OUT\_SIMPLEX -- the names of output files for the 
          lightcurve (OUT\_FILE)
          and eventual fit results (OUT\_SIMPLEX).

    \item PROFILE\_ARRAY, PROFILE\_RES -- the size of the array for 
          line profile computation 
          (PROFILE\_ARRAY) and the default resolution 
          (PROFILE\_RES).

\end{itemize}

\newpage
\begin{rawhtml}
<HR>
\end{rawhtml}

\section{Usage}

\subsection{General}

If used in non-interactive mode, unless a configuration file is 
read in at startup 
(see
\hyperref
  {info on configuration files}
  {Section\ } 
  {}
  {config}),                           
{\sc nightfall} requires at least the following six numerical arguments on the
command line (in that order): 

\begin{itemize}

  \item
  (1) the mass ratio of both stars 
  (mass(Secondary)/mass(Primary), allowed range 0.0001 -- 10000.0.
  For Roche lobe fill
          factors (see below) above one, the mass ratio is restricted to
          0.003 - 50.



  \item
  (2) orbital inclination ( = viewing angle of orbital plane, 
  range 0 -- 90 degree), where 0 deg corresponds to face-on view (no eclipse
  possible), and 90 deg to edge-on view (eclipse guaranteed). For
  angles in between, the occurence of an eclipse depends on the mass
  ratio and the Roche fill factors (see below).

  \item
  (3,4) Roche lobe fill factors. The {\it Roche lobe} is the maximum
  volume a star can fill in a binary system. Its size is, in general,
  different for the two stars, and depends on the mass ratio (see 
  \hyperref
    {details on 'Roche lobe'}
    {Section\ } 
    {}
    {roche}                            
  for an explanation). The Roche lobe fill factor 
  is in units of the polar radius of the {\it Roche lobe}.
  The allowed range is  0.001 -- 1.3. For values above 1.0, both stars 
  merge into a {\it common envelope/overcontact} system.

  \item
  (5,6) surface temperatures of both stars
  (in Kelvin, range 350 -- 350000; Kelvin = degree Celsius + 273.15).
  Just for comparison, the surface temperature of the sun is 5780 K.
  If you use the 'model atmosphere' option, the minimum temperature is
  2000\,K, the maximum temperature is 31000\,K 
  (for surface gravity $\log{g} = 3.5$), 39000\,K ($\log{g} = 4.0$), and
  49000\,K ($\log{g} = 4.5, 5.0$)
  

\end{itemize}

\ni
{\bf These six numerical arguments are always required, if
{\sc nightfall} is used in command-line (i.e. non-interactive) mode 
without reading in a configuration file} (see below)\\


\ni
\$ nightfall -U -C ty\_boo.cfg\\

\ni
will read parameters from a configuration file and start {\sc nightfall}
in interactive mode. The configuration file is a simple text file
that can be edited by hand. In interactive mode, you can also
write out the current parameters to a configuration file.\\

\noindent
\$ nightfall (without arguments) will produce a full list of options (many).\\

\ni
{\bf By default, {\sc nightfall} will do nothing more than 
     run in non-interactive mode, compute
     the lightcurve, write it to an output file 'NightfallCurve.dat',
     and exit silently. If you want more (nifty plots, etc.), read on.}

\subsection{Plotting, Graphics}

\ni
requires that {\sc nightfall} has been 
compiled with support for PGPLOT or Gnuplot.

\ni
In interactive mode, there are several menu options available to produce plots.
In non-interactive (command-line) mode, you can choose from the following:

\begin{itemize}

\item For a real-time animation of the two stars orbiting each other, use 
      {\bf  -A}

\item To select plotting of the output light curve, use {\bf -G}

\item To select the filter for the plottted lightcurve, use {\bf -Bfilter}
      where 'filter'is one of UBVRIJHKuvby (see 
  \hyperref
    {details on filters}
    {Section\ } 
    {}
    {filter})

\item To visualize the geometry, use {\bf -V}.\\
      There are four sub-options (-Va, -Vi, -Vc, -Vv):
      \begin{itemize}
         \item -Vc for a contour plot of the potential,
         \item -Vi for an image of the potential,
         \item -Vv for viewing the stars, 
         \item -Va for all in one plot.
      \end{itemize}
      The default is 'c'. Only
      'c' and 'v' are supported by {\sc GNUPLOT} 
      ({\sc GNUPLOT} cannot display images).

\item To obtain a hardcopy, use {\bf -H}.
\end{itemize}

\ni
{\it Detailed output is always written to a file 'NightfallCurve.dat'.}


\subsection{Interactive usage - the graphical user interface (GUI)}

\ni
Use command line option {\bf -U} to choose this option. 
A GUI will (hopefully) come up.\\

\ni
In the menu bar, there is a {\bf File} menu for 
reading data/configuration files.
Please note that you need to reset the data memory {\bf [Reset Memory]}
before reading in data for another binary, otherwise you will end up 
in a mess ...\\
The {\bf Output} menu allows to choose between several facilities for
viewing the output of a computation and visualizing the binary system.
Some of them allow interactive change of parameters like viewing angle etc.
Please read the online help for more details.\\

\noindent
In the toolbar below, 
there are buttons for computing a lightcurve {\bf [Compute]},
toggling animated view of the binary {\bf [Animate]} while computing, 
writing out the current binary configuration {\bf [Write]}, 
and getting help on the currently active notebook page {\bf [Context]}.\\

\noindent
The rest of the GUI is layed out as a 'notebook' with several 
different pages for setting options:

\begin{itemize}

      \item 
      {\bf Basic} Here you can define the basic configuration of the
      binary - mass ratio, inclination, fill-out ratios and temperatures.
      I know, reading manuals is not much fun, but you should read at least 
      \hyperref
        {the basic introduction}
        {Section\ } 
        {}
        {basic}
      to know what's going on. Use animated mode
      for 'learning by doing'. 

      \item 
      {\bf Disk} For defining the parameters of an optional accretion disk. See
      See
       \hyperref
        {'Disk'.}
        {Section\ } 
        {.}
        {disk}

      \item 
      {\bf Advanced} For advanced options like asyncroneous rotation,
      non-circular orbit, etc. See
       \hyperref
        {'Advanced Options'.}
        {Section\ } 
        {.}
        {advanced}

      \item 
      {\bf Plot Options} for the selection of output filter 
      (see 
  \hyperref
    {details on filters}
    {Section\ } 
    {}
    {filter}),
      and plot window for lightcurve, as well
      as options for geometry visualization.\\
      If compiled with OpenGL support, you can also switch on/off
      OpenGL viewing mode here.

      \item 
      {\bf Data Fiting} Computation of best-fit parameters.
      Also: definition of absolute system parameters (for radial velocity).
      See 
  \hyperref
    {details on data fitting.}
    {Section\ } 
    {.}
    {fitting}

      \item 
      {\bf Spots} Here you can interactively define up to two spots per star
      (additional spots can be defined on the command line or in a
      configuration file).  Both spots can be switched on/off independently.
      See 
  \hyperref
    {details on surface spots.}
    {Section\ } 
    {.}
    {spotted}

      \item 
      {\bf Third Light} For definition of the brightness of an (eventual)
      third star in the system. Third Light is just added to 
      the total brightness, 
      never eclipsed, i.e. it only has an effect on the relative depth
      of the eclipses. See 
  \hyperref
    {the section on third light.}
    {Section\ } 
    {.}
    {third}
      
\end{itemize}    

\ni
On the bottom of the GUI, there is a status/progress bar.

\subsection{OpenGL}

\ni
{\bf Note} that OpenGL can lead to program crashes with some graphic cards.

\ni
If compiled with OpenGL support, the animated display will by default
run in OpenGL mode. You can switch to {\sc GNUPLOT}/{\sc PGPLOT} mode
in the PlotOptions page in the GUI. In OpenGL 
mode, you have the following options:

\begin{itemize}
	\item {\bf Zoom} by clicking into the display area and drag with the
	middle mouse button.

	\item {\bf Change viewpoint} by clicking into the display area 
	and drag with the
	left mouse button.

	\item {\bf Reset} with the space bar.

	\item {\bf Save animation} as JPEG images with File->Save animation

	\item {\bf Edit preferences} with Edit->Preferences. 
	\begin{itemize}
		\item You can switch
		between wireframe, solid, and points display. 
		\item For solid mode, you
		can switch on textures, and choose different texture types.
		\item You can switch on/off the display of labels and axes.
	\end{itemize}

	\item The following keybindings are available in the OpenGL window:\\
	\begin{tabbing}
	right arrow \= zoom out\\
	left arrow \> zoom in\\
	space \> reset to real observer viewpoint\\
	f     \> switch to 'points' display mode\\
	l     \> switch to 'wireframe' display mode\\
	o     \> switch to 'opaque' display mode\\
	t     \> toggle textures on/off\\
	w     \> cycle through texture type \\
	      \> (image/temperature/gravity/flux/velocity)\\
	p     \> toggle primary texture on/off\\
	s     \> toggle secondary texture on/off\\
	a     \> toggle axes on/off\\
	m     \> toggle movie mode on/off\\
	\end{tabbing}
	
\end{itemize} 

\ni
With textures enabled, the default is to use a pixmap as texture. All
other textures display the variation of physical quantities 
(caused by the non-spherical shape and/or limb darkening) 
across the stellar surface. Available choices are: surface temperature,
surface gravity, flux {\it towards the observer}, and the velocity of surface
elements {\it towards the observer} relative to the star's centre of mass.

\subsection{MPI}

\ni
Please read the documentation of your MPI library for details about
how to start a parallel application. The MPICH library (and some
other MPI implementations) provides a command {\bf mpirun} that
handles everything:\\

\ni
\$ mpirun -np {\it number\_of\_processes} nightfall {\it nightfall-options}\\

\ni
(Note that for MPICH, you need to enter the machines where the different 
processes should run into a {\it machines file}. See the MPICH documentation.)


\subsection{Problems}

\begin{itemize}

  \item OpenGL can lead to program crashes with some graphic cards.

  \item Overcontact systems are not displayed correctly with OpenGL.

  \item The {\sc Gnuplot} PS-driver apparently does not support
	the 'multiplot' option.

  \item For eccentric (non-circular) orbits, very small fill factors
        produce strong numerical artifacts in the light curve.

  \item There seem to be some numerical artifacts also in the line
        profiles sometimes, preferentially at quadrature.

\end{itemize}


\newpage
\begin{rawhtml}
<HR>
\end{rawhtml}



\subsection{Configuration File}

\ni
{\sc nightfall} comes with a set of configuration files, each of which
will set the system parameters for a particular (real) binary system,
and automatically load some data files with observed data for 
this particular binary star (see next section).\label{config}\\ 

\ni
For the file format, see the commented example file 'ty\_boo.cfg'
in the source code distribution. To read in such a file, on the
command line use:\\

{\bf  -C path/to/config/file}\\

\ni
If you don't give the full path,
{\sc Nightfall} will search (in this order of priority) the present working
directory, an eventual subdirectory './cfg', and the default
data directory set at compile time. If the configuration file is in one
of these, only the name, not the full path is required.\\


\subsection{Data files}

\ni
{\sc nightfall} comes with a set of sample observational data for several
different eclipsing binaries. For each included binary system, the data 
comprise lightcurves in several filters, as well as radial velocity curves.
Also, for each of these systems there is a configuration file
(see 
  \hyperref
    {details on configuration files}
    {Section\ } 
    {}
    {config}).
Loading this configuration file will set the
appropriate parameters for that particular system, and also read in the data.
You can then compute the lightcurve and visualize the binary, with the
observed data overlayed on the lightcurve. \\

\ni
E.g. you might call {\sc nightfall} 
as 'nightfall -U -C data/ty\_boo.cfg', then press 'ANIMATE' to switch
on the real-time animation, and press 'COMPUTE' to compute the
lightcurve. With 'PlotCurve' you can then get a plot of the final lightcurve,
with the data overlayed.\\

\ni
Of course, you can also experiment by yourself and try to fit the
lightcurve by varying the system parameters, or use the automatic
fitting option.\\

\ni
To read in a single data file, use\\

{\bf  -I path/to/data/file}.\\

\ni
If you don't give the full path,
{\sc Nightfall} will search (in this order) the present working
directory, an eventual subdirectory './data', and the default
data directory set at compile time. If the data file is in one
of these, only the name, not the full path is required.
For details on the format of the files, see 
  \hyperref
    {here.}
    {Section\ } 
    {.}
    {dataread}

\ni
Data are available for the following systems:

\begin{itemize}

  \item
  {\bf TY Boo:} a 'common-envelope' ('overcontact') system with two
  cool stars. This is a so-called 'shallow' overcontact system, as
  the stars are only slightly overfilling their Roche lobes (for the 
  explanation of the term 'Roche lobe' see
   \hyperref
    {here.}
    {Section\ } 
    {).}
    {roche}
  The two
  stars have slightly different temperatures.

  \item
  {\bf MR Cyg:} a semi-detached system (the cooler fills its Roche lobe)
  with two stars of very different temperature (but both much hotter
  than the Sun). Lightcurve should be
  computed with some advanved options: model atmosphere fluxes,
  detailed reflection (2-3 iterations), quadratic limb darkening.

  \item
  {\bf DD Mon:} another semi-detached system (the cooler star fills its
  Roche lobe). The cooler star is slightly cooler than the Sun, the other one
  slightly hotter than the Sun. The total mass is very low -- both stars
  together have only about 0.6 solar masses. It seems difficult to
  fit the lightcurve without spots (did not try as yet). 

  \item
  {\bf BH Vir:} a detached system with two stars, one slightly hotter,
  the other slightly cooler than the Sun. At least one of the stars
  has surface spots, which cause a slight, but noticeable distotion
  of the lightcurve. The config file includes two spots on the cooler star.
  The BV lightcurves and the uvby lightcurves are 
  from different years. As the stars exhibit some variability, you might want
  to use either the BV or the uvby lightcurves, 
  but not all six simultaneously.

  \item
  {\bf LZ Cen:} a detached, but near-contact system with two rather
  similar stars, both very hot. The stars are rotating very slightly faster
  than synchroneously. Lightcurve should be
  computed with some advanved options: model atmosphere fluxes,
  detailed reflection (2-3 iterations), quadratic limb darkening.

  \item
  {\bf ER Vul:} a detached system of two stars that are both slightly 
  hotter than the sun, and also have masses only slightly higher than
  the sun. The stars show strong and variable activity, i.e.
  large starspots that are varying with time. Thus the derived parameters
  of the spots can vary a lot from one observation to the next.

  \item
  {\bf V541 Cyg:} a well-detached (i.e. wide) binary system with an 
  eccentric (i.e. non-circular) orbit. As the binary is very wide, the
  eclipses are narrow, and it is {\bf important} to set the number of
  steps for the lightcurve to a high value (say, 600, instead of the
  default of 80) in order to resolve the eclipses.

  \item
  {\bf 51 Peg:} an extrasolar planetary system. Only the radial velocity
  curve of the primary is known, thus for the planet only the product
  $m \times \sin(i)$ is known (0.45 Jupiter masses). Depending on the
  unknown inclination angle, the mass may be as high as 15 Jupiter masses,
  while higher masses are probably ruled out, because a higher-mass 
  companion would have synchronized the primary, which is not the case 
  (the rotation period of 51 Peg is 29-37 days, while the
  orbital period of the planet is 4.23 days). The model assumes an inclination
  angle of 25 deg, and a density similar to Jupiter's for the planet. The
  parameters of the star (mass, radius, temperature) are well known; the
  temperature of the planet can be calculated from its distance to the star.
  No eclipses (by the planet) have been observed, but the amplitude would be
  at the limit of even the most sensitive measurements.

\end{itemize}


\subsection{Environment variables}

\noindent
The run-time behaviour of the program can be modified by the value of
some {\it environment variables}. To set an {\it environment variable}
to some value, depending on your shell the following command is required:\\

in csh, tcsh: {\tt setenv VARIABLE=value}\\

in sh, bash: {\tt VARIABLE=value; export VARIABLE}\\


\begin{itemize}

  \item
  {\bf HOME} your home directory, usually automatically set by your shell

  \item
  {\bf TEMPDIR or TMPDIR} location for temporary files 
  (should not be on NFS mounted filesystem). If these variables are not set,
  {\sc nightfall} will use /tmp as default.

  \item
  {\bf LANGUAGE or LC\_ALL or LC\_MESSAGES or LANG} (in this order of priority)
  will be used to determine your language. The default is English. At the
  time of this writing, the only other supported language is German
  (LANG=de).

  \item
  {\bf NIGHTFALL\_DATAROOT} the root directory to search for the data/, cfg/, 
  and doc/ subdirectories (containing data, config, and help files, 
  respectively). Only needed if this directory has been moved after
  installation.

  \item
  {\bf NIGHTFALL\_DATA\_DIR} the directory where data are located. Only needed
  if these have been moved after installation, and {\bf NIGHTFALL\_DATAROOT}
  is not set or data are not in {\bf \$NIGHTFALL\_DATAROOT}/data.

  \item
  {\bf NIGHTFALL\_CFG\_DIR} for location of config files. 
  See {\bf NIGHTFALL\_DATA\_DIR}.

  \item
  {\bf NIGHTFALL\_DOC\_DIR} for location of help files. 
  See {\bf NIGHTFALL\_DATA\_DIR}.

  \item
  {\bf NIGHTFALL\_LOCALE\_DIR} for location of data for 
  localization. Only important if you use internationalization to
  support your language. See {\bf NIGHTFALL\_DATA\_DIR}.

  \item
  {\bf NIGHTFALL\_PLOTFILE} the name of the output file for plots. Default
  is nightfall.ps.

  \item {\bf GNUPLOT\_GEOMETRY} the window size for gnuplot. Default is
	550x424+300+20.

  \item {\bf PGPLOT\_XW\_WIDTH} fractional display width for PGPLOT X window.
  
  \item {\bf NIGHTFALL\_RADIATIVE} limiting upper temperature for stars with 
	convective envelope (default is 7700; unit is Kelvin). Above
	that temperature the envelope will be considered radiative. The only
	effect this has to to switch the albedo from 0.5 (below) to 1.0 (above).

  \item {\bf NIGHTFALL\_SMAP\_PATH} base path to the surface map. To this,
	the index for the bandpass and the 
	current phase will be appended. No surface map
	will be output if this environment variable is not set.

  \item {\bf NIGHTFALL\_SMAP\_BAND} bandpass (0..11 for UBVRIJHKuvby) for 
	which surface map is output.

  \item {\bf NIGHTFALL\_MONO\_WAVE} a comma-delimited list of up to twelve
	monochromatic wavelengths (unit: micrometer) 
	to replace the effective wavelengths for the 
	blackbody approximation.

\end{itemize}

\newpage
\begin{rawhtml}
<HR>
\end{rawhtml}

\section{Introduction to Binary Stars}

\noindent
This section (and the next) provide(s) an introduction 
to the problem (at a popular science \label{basic}
level, hopefully), the options, and the algorithm(s) used. More technical
aspects are in italics. If you find the less technical part too arcane,
feel free to supply (constructive) suggestions.


\subsection{The Roche Geometry}

\noindent
Imagine two lakes, seperated by a ridge. There are about three possible
configurations: \label{roche}

\begin{itemize}
  \item In both lakes, the water level is well below the level of the ridge.
        This is a {\bf detached system}.

  \item One of the lakes reaches up to the lowest point of the ridge, and water
        may spill over to the other lake. 
        This is a {\bf semi-detached system}. 

  \item Both lakes overflow the ridge and form one single lake.
        This is a {\bf contact\,/\,overcontact system}.

\end{itemize}

\ni
Replace 'water' by 'gas', 'lake' by 'star', and you have the possible
configurations of a close binary star system.\\

\noindent
The stellar shapes in such a system are given by the sum of the 
gravitational forces, and the centrifugal force due to the orbital motion.
Instead of using the forces, it is easier to use a {\bf potential} (forces
can then be expressed as the derivative of the potential, if needed). 
In the case of binary stars, this potential is called 
the {\bf Roche potential}, named after the French mathematician 
Edouard Albert Roche (1820-1883).
The stellar surface is then given by an {\bf equipotential surface} 
(a surface, on which the potential is constant). 
Thus, the introduction of the potential makes
the computation of any forces superfluous in this particular application.\\ 

\noindent
The largest size a single star can have in a binary system is given by the
{\bf Roche lobe} - a teardrop-shaped equipotential surface, 
whose cusp touches the cusp of the
Roche lobe of the other star at a point called {\bf Lagrange 1 (L1)}
(there are four more Lagrange points, which are of less interest here).
L1 is located between both stars, on the line connecting their centres.
At L1, the sum the forces is zero, thus, if a star fills its Roche lobe, at L1 
matter can flow into the Roche lobe of the other star (provided it is not
filled as well). \\

\noindent
Thus, L1 would correspond to 'lowest point of the ridge' in the two-lake 
example above, and the Roche lobes would correspond to the two valleys below
that point, that potentially can be filled by the two lakes. But just as
the two lakes in the example above may be smaller than their
maximum size (before flowing together), also the stars in a binary system
may be smaller than their respective Roche lobes.
A star that completely fills its Roche lobe will assume
its teardrop-like shape. A star filling only a small fraction of its Roche lobe
will be more spherical - distortion increases with the {\bf Roche lobe filling
factor}.\\

\ni
Note that the {\it relative} size of the Roche lobe of the two stars 
in the system depends on their mass ratio. The {\it absolute} size of the 
Roche lobe also scales with the separation of the two stars.
Thus, with a fixed mass ratio and fixed absolute sizes of the stars (e.g.
in kilometers), a star may fill its Roche lobe (and have a highly distorted 
figure), if the stars are rather close,
but the same star might fill just a tiny fraction of its  Roche lobe
(and thus would be nearly spherical) if the binary separation 
would be rather large.  \\

\ni
To define the sizes of stars in {\sc nightfall}, you have to 
give the 'Roche lobe filling factor', which is defined in units of the
Roche lobe (actually, its polar radius).
{\sc nightfall} uses a dimensionless potential, i.e. the distance between 
both stars is arbitrarily set to unity. 
Thus, for a fixed absolute size of the stars, decreasing the
'Roche lobe filling factor' would be equivalent to increasing the
distance. 

\subsection{Shape of the lightcurve}

The shape of the lightcurve depends mainly on three factors:
\begin{itemize}

  \item temperatures - as the eclipsed areas are equal for the eclipse of
        the Primary and the eclipse of the Secondary, the depths of the
        eclipses are only different if the temperatures of both stars 
        differ. See 
  \hyperref
    {here}
    {Section\ } 
    {}
    {norm}
        for details on temperature and
        brightness.

  \item relative sizes and shapes of the stars, which are determined
        by the mass ratio (that determines the relative sizes of both 
        Roche lobes) and the Roche lobe filling factors 
        (see
   \hyperref
    {the info on 'Roche lobe'}
    {Section\ } 
    {}
    {roche}).

  \item temperature distribution on the stellar surface. If the Roche lobe
        filling factor is large, the star is very nonspherical, and its
        temperature can vary significantly over its surface. This effect
        is known as gravity brightening (see 
   \hyperref
    {details on gravity brightening}
    {Section\ } 
    {}
    {gravbright}).
        The result is that the lightcurve varies strongly, even if there
        is no eclipse.

  \item mutual irradiation of both stars (see 
   \hyperref
    {details on reflection treatment}
    {Section\ } 
    {}
    {reflect}).

  \item cool/hot surface spots (like sunspots, but can be much larger
        in some stars, see 
   \hyperref
    {details on surface spots}
    {Section\ } 
    {).}
    {spotted}

\end{itemize}

\subsection{Suggested experiments}

\begin{itemize}
 
  \item to begin, set the mass ratio to 1.0, 
        both stars to equal fill factor and 
        both temperatures to equal values. You will find that
        both eclipses have the same depth, as the eclipsed areas 
        are equal (and have the same limb darkening).

  \item as soon as one star is hotter than the other, the depth of 
        the eclipses will become different.

  \item the width of the eclipses depends on the sizes of the stars

  \item the 'textbook' case of a flat lightcurve between eclipses
        is very rare. The reason is that due to the aspherical shape of
        stars in close binary systems, the visible surface area
        of the star varies during the orbit. Also, this aspherical shape
        causes strong temperature
        (= brightness) variations over the surface of the star 
        an effect called 'gravity brightening' (or 'gravity darkening'). 
	For more details, see
    \hyperref
    {here}
    {Section\ } 
    {.}
    {gravbright}
        You will see that the lightcurve only becomes flat between
        eclipses if the Roche lobe fill factors (and thus the
        aspherical distortions) of the stars are very small. Which
        means that the distance of the two stars is large compared
        to their sizes, and 
	an eclipse con only be observed if the orbital inclination
	is very close to 90 degrees - a rather rare case.

  \item on the other hand, the aspherical shape of the stars 
        can cause deep throughs in the lightcurve
        even if there is no eclipse at all ! To see this,
        set the mass ratio to 0.9, the Primary fill factor to 1.0,
        the Secondary fill factor to 0.1, and the inclination to
        40 degree (just as an example).
        In animated mode, you can verify that there is
        no eclipse at all, but still you see 
        deep throughs in the light curve.

  \item the 'bottom' of an eclipse only becomes (more or less) flat
        if the star is eclipsed for a prolonged time, i.e. if it is
        significantly smaller than the other, eclipsing star.

  \item in an eccentric (non-circular) orbit, the velocity of the stars
        is not constant. Thus, also the width of both eclipses may be 
        different, and the times between them as well 
         (see 
    \hyperref
    {details on eccentric orbits}
    {Section\ } 
    {).}
    {eccentric}
	There is a config file
        'v541\_cyg.cfg' for the binary system V541 Cygni, which
        shows both effects.

  \item the shape of the stars can vary a lot in an eccentric orbit,
        because the varying distance is equivalent to a varying Roche
        lobe filling factor. To demonstrate this, set the mass ratio
        to 1.0, and both Roche lobe filling factors to 1.0. Set 
        the eccentricity to a large value (say, 0.6), and the orbital
        inclination to 0.0, to see what's going on (don't forget to 
        switch on 'eccentric orbit', if you are in interactive mode).
        Use animated mode and enjoy.

\end{itemize}

\newpage
\begin{rawhtml}
<HR>
\end{rawhtml}

\section{More details}

\subsection{Which star is which ?}

\noindent
Stars in binary systems are labelled 'Primary' and 'Secondary'.
In {\sc nightfall}, the star called 'Primary' is the star which 
is {\it eclipsing} first, i.e.
the star that passes {\it in front} of the other one at
orbital phase zero (orbital phase indicates the position of the stars
in the orbit on a scale from zero to one). The secondary is the star that
is {\it eclipsed} first.  In animated view, at start the Primary is left,
the Secondary right. Note that this labelling of 'Primary' and 'Secondary' 
is inverse to the usual
convention ... mea culpa. Maybe I fix it sometime.\\

\noindent
To exchange the stars (if needed), you can either (i) swap the eclipses
in your data, or (ii) swap the stars themselves.\\
For (i), add half an orbital period to the phase zeropoint in your datafile
(for a circular orbit), or the time lag of the second eclipse (for an eccentric
orbit).\\
For (ii), swap temperatures and Roche lobe fill factors, and replace the
mass ratio q by 1/q. Don't forget to swap spots, if you have. For an
eccentric orbit, add or subtract 180 deg to/from the Periastron length.\\

\noindent
For a circular orbit, {\sc nightfall} 
starts at orbital phase -0.25 -- which is identical to +0.75 --, 
and calculates up to +0.75.
In a circular orbit, eclipses are at orbital phase 0.0 and 0.5.).\\

\noindent
{\sc nightfall} uses a dimensionless potential, i.e. the distance between 
both stars is arbitrarily set to unity. 
The relative size of both Roche lobes then depends
only on the mass ratio of both stars. The size of both stars has to be
given as a fraction of the Roche lobe (actually, its polar radius).
This fraction might be larger than one, if you want to specify an overcontact
system.  To specify a semi-detached system, set the Roche lobe filling fraction
to 1.0 for one star, less for the other.\\


\subsection{How is eclipse testing done ?}

\noindent
{\sc nightfall} divides each stellar surface into a grid of a few thousand
elements. Eclipse testing is done by checking - for each surface element 
individually- whether the line of sight towards that surface element 
intersects the other star. For overcontact systems, a star might eclipse
its own throat region 
(the region connecting both stars). This condition is tested as well.

\noindent
Although simple tests based on orbital phase or intersection of sperical
regions suffice in most cases, still sometimes a rigorous and expensive
test is needed. \\


\subsection{Temperature and Brightness}

\noindent
Stellar \label{norm} surface temperatures can range from a 
few 1000 Kelvin to several 
10000 Kelvin. The respective brightness can be calculated
from the so-called blackbody law (a blackbody is an idealized thermal
radiation source). The blackbody law is applicable to thermal radiation,
such as infrared radiation of your own body, or radiation by stars; it is
not applicable to non-thermal radiation sources like lasers.\\

\noindent
By default, {\sc nightfall} uses the blackbody law, which is neither terribly
good nor terribly bad. It is possible to use, instead, light fluxes
from detailed numerical computations of stellar atmospheres. Contrary
to blackbody fluxes, these model atmosphere fluxes (like real stellar fluxes)
depend not only on temperature, but also (mildly) 
on surface gravity, and on the chemical composition of the stellar atmosphere. 
As actual atmosphere calculations
would be prohibitively expensive, model atmosphere fluxes  are taken from
tables that cover only a limited range in temperature (3000 K to 35000 K).
Tables are hardcoded, and only available for one surface gravity value 
(a compromise value that should be ok for most cases), and solar
chemical composition. \\

\ni
To switch on model atmosphere fluxes, use \\

{\bf  -M}

\subsection{Output Lightcurves}

\noindent
Lightcurves are \label{filter} output in eight commonly 
used broad-band filters (UBVRIJHK from
near-UV to near-infrared), 
and four narrow-band filters (Stroemgren uvby). The shape of the lightcurve 
depends on the filter passband. \\

\noindent
The human eye itself also is not equally sensitive to all wavelengths 
of light -- it also is a kind of 'filter' for light. To create a lightcurve
that looks like the human eye would see it, you have to choose an output
filter that matches as close as possible the sensitivity of the human
eye. For broadband filters, the V filter gives the best match to the human 
eye. In the Stroemgren filter system, you might want to choose Stroemgren v.\\


\noindent
Lightcurves are output in {\bf magnitudes}. 
This is a relative unit commonly used in astronomy,
and defined as \[ m_1 - m_2 = -2.5 \times \log{\frac{flux_1}{flux_2}}. \] 
(For magnitude differences smaller than about 0.4, the difference
in magnitude times 100 is nearly equal to the percentage difference in flux, 
i.e. 0.1 mag is about 10 per cent difference.)
The brighter an object, the smaller its magnitude (Sun is -26.7 in the 
V filter, while the faintest stars visible by naked eye are about +6).
{\sc nightfall} uses the brightness at quadrature (phase -0.25 in a circular
orbit, both stars fully visible) as 
normalization (i.e. as $flux_2$ in the equation above).\\

\noindent
{\bf Output} goes to a file 'NightfallCurve.dat'.
To select plotting of output light curve, use \\

{\bf  -G}\\

\noindent
To select the filter for the plotted lightcurve, use\\

{\bf  -Bfilter},\\

\ni
where {\bf filter} should be one of UBVRIJHKuvby. The default for plotting
is the V filter, which is the best match to the human eye. If you read in
data files with observed lightcurves (see 
  \hyperref
    {here for more info}
    {Section\ } 
    {\ for more info}
    {dataread}
), the default
will be the filter of the first lightcurve read in.

\noindent
To obtain a hardcopy (i.e. PS file), use \\

{\bf  -H}\\

 
\subsection{Gravity Brightening}


\ni
The nonspherical shape \label{gravbright} 
of both stars causes a non-constant surface gravity.
This, in term, causes brightness variations, with regions of higher
surface gravity having higher brightness. This effect is called gravity
brightening or  gravity darkening (depending on which article you read).
Gravity brightening can produce deep minima in the lightcurve, 
even if there is no eclipse at all !!
{\sc nightfall} always takes care of this effect - there is no option to 
switch it off. \\

\newpage
\begin{rawhtml}
<HR>
\end{rawhtml}

\section{Disk}
\label{disk}

\ni
In a binary system where one star fills its Roche lobe, there may be mass transfer via
Roche lobe overflow. I.e. at the L1 point between the two stars, matter from the
Roche-lobe filling star can flow into the Roche lobe of the other star. For physical
reasons (conservation of angular momentum), this matter will not just fall onto the
other star, but rather form a so-called {\bf accretion disk}.\\

\ni
Within this disk, the
gas orbits the star and loses angular momentum by friction, thus slowly moving towards
the stellar surface. If the star has a strong magnetic field, this field may disrupt
the disk close to the star. I.e. the disk will not reach all the way to the stellar surface,
but rather there will be a gap between the inner edge and the star, and the gas will take
the last part of its journey along the magnetic field lines.\\

\ni
The disk is characterized by inner and outer radius, temperature, height, and the {\bf disk model}. 
Furthermore, optionally a {\bf hot spot} may be included in the model.\\

\ni
The outer and inner edge of the disk are modelled as vertical ``walls''.

\subsection{Disk model}

\ni
For all models, the height of the disk at radius {\bf r} is computed as 
\[ a + b * r^c. \]

\subsubsection{Simple disk}

\ni
For a {\bf simple disk}, $c = 1$, $a$ is set equal to half of the {\bf thickness} parameter, and
$b$ is set equal to the {\bf H/R} parameter. Setting H/R to zero results in a flat disk.
The {\bf temperature} is constant and equal to the respective input parameter.

\subsubsection{Isothermal disk}

\ni
While the {\bf simple} disk model is isothermal, it's run of the height with radius is not
physically correct for an isothermal disk. In the {\bf isothermal disk}, the exponent $c$
is set to $c = 1.5$, which is the correct value for an isothermal disk. Furthermore,
the {\bf H/R} parameter is ignored, the constant $a$ is set to $a = 0.0$, and the factor
$b$ is chosen such that at the inner disk radius, the disk thickness equals the 
{\bf thickness} input parameter.

\subsubsection{Reprocessing disk}

\ni
The {\bf reprocessing disk} is the model for a disk that is reprocessing (absobing/re-radiating) the
radiation from the central star.  The exponent $c$
is set to $c = 9/8$, which is the correct value for a reprocessing disk. Furthermore,
the {\bf H/R} parameter is ignored, the constant $a$ is set to $a = 0.0$, and the factor
$b$ is chosen such that at the inner disk radius, the disk thickness equals the 
{\bf thickness} input parameter. Lastly, the {\bf temperature} falls off with radius
as $r^{-frac{3}{4}}$.

\subsection{Disk parameters}

\begin{itemize}

  \item
  (1, 2) inner and outer radius,

  \item
  (3) thickness at inner edge,

  \item
  (4) H/R (height/radius), only used in {\bf simple disk} model,

  \item
  (5) temperature at inner edge, constant throughout the disk for
  {\bf simple disk} model and {\bf isothermal disk} model.

\end{itemize}

\subsection{Hot spot parameters}

\ni
The disk may have a hot spot (where the accretion stream from the donor star
hits the outer edge of the disk). The hot spot is assumed to have constant 
temperature and constant depth (as measured from the outer edge of the disk).

\ni
To {\bf switch off} the hot spot, set the extent in longitude to zero.

\begin{itemize}

  \item
  (1) T(hot spot) the temperature of the hot spot (assumed constant),

  \item
  (2) Longitude(hot spot) the longitude where the hot spot centre is located
  on the disk rim.

  \item
  (3) Extent(hot spot) the extent in longitude, and 

  \item
  (4) Depth(hot spot) the depth, as measured from the outer disk edge, to
  which the hot spot extends into the disk.

\end{itemize}



\section{Advanced Options}
\label{advanced}

\subsection{Fractional Visibility}

As eclipse testing is only done for the centres of surface elements, 
the coarse surface grid introduces numerical artifacts that are readily 
visible sometimes. To fix this problem, it is possible to compute 
{\bf fractional visibilities} for the surface elements (i.e. compute what 
fraction of a surface element is eclipsed). To switch on, use \\

{\bf  -F}\\


\subsection{Reflection}

\ni
Due to the mutual \label{reflect} 
irradiance of both stars, in addition to its own light, 
each star will also reflect light of its companion. This can be a very 
important effect, especially if the two stars are close (large Roche fill
factor) or the temperature difference is large.
{\sc nightfall} offers two options:\\
 (1) by default, the irradiating
star is treated as a point source. This is ok for low Roche lobe
filling factors, but not very accurate for stars filling a large fraction of
the Roche lobe. It is rather fast, however.\\
 (2) it is possible to compute the mutual irradiance of all pairs of surface
elements, with up to nine iterations (usually, two to three are sufficient).
This is an $N^2$ algorithm (N the number of surface elements), and thus
computationally very expensive. To switch on, use \\

{\bf  -Rn}\\

\ni
where 'n' is the number of iterations.


\subsection{Overcontact systems}

\noindent
For overcontact systems, the second Lagrange point (L2) comes into play.
It is located behind the less massive star (as seen from the more massive),
and has the same property as L1, i.e. the force vanishes there, and matter
might flow out of the common envelope of an overcontact system (I suppose,
by now you know where L3 is. L4 and L5 are in the orbital plane, left and
right of the line connecting the centres of both stars. L3-5 are not
terribly important for binary stars.)\\

\noindent
Thus, the surface of the common envelope of an overcontact system has to be
between the two equipotential surfaces given by the potentials of L1 and L2
(remember, the force is the derivative of the potential, thus if the net force
is zero, the potential can still have a non-zero value - it just has to be
'flat' locally).\\

\noindent
To have an overcontact system, set the Roche lobe filling factor of one star
larger than 1.0 (as there is only one surface now, the smaller Roche lobe 
filling factor will be ignored).
If you choose a too large value, {\sc nightfall} will adjust it. (The largest
possible value depends on the mass ratio. Anything
larger than about 1.3 is rather unreasonable for any mass ratio.)\\

\noindent
The combination of overcontact and non-circular orbit or 
asynchroneous rotation (see below) 
is not supported. It would be rather unphysical anyway, 
as the strong interaction (tidal forces and friction) would 
circularize and synchronize the system
extremely rapidly.

\subsection{Asynchroneous Rotation}

\noindent
Tidal forces in close binaries will tend to enforce synchroneous rotation
(both stars rotating with the orbital period, thus showing each other
always the same side) on a timescale usually shorter than stellar lifetimes.\\

\ni
There are, however, occasions when stars might rotate asynchroneously, e.g.
young stars that are not yet rotating synchroneously, 
or massive stars that have short livetimes anyway, too short for 
synchronization to occur during their lifetime. Also, tidal forces
fall off very rapidly with increasing distance, thus wide binaries
are likely candidates for asynchroneous rotation 
(the tidal force is inverse proportional to
the cube of the distance - unlike e.g. gravity, which is inverse proportional
to the square of the distance and thus falls off much less rapidly).\\ 

\ni
A (nonstellar) example for synchronization is the Earth-Moon system,
where Moon's rotation has been synchronized already, while Earth's rotation
is known to slow down gradually. This would eventually lead to Earth's 
synchronization as well, but I suspect it might take longer than the lifetime
of our solar system ...\\
  
\ni
To switch on asynchroneous rotation, 
use \\

{\bf  -fP fratio} or {\bf  -fS fratio}\\

\ni
[-fP for Primary, -fS for Secondary). 'fratio' is the ratio between 
stellar rotation period and orbital
period. \\

\noindent
Asynchroneous rotation modifies the Roche potential (see
  \hyperref
    {the info on 'Roche lobe'}
    {Section\ } 
    {}
    {roche}), 
and hence
the equipotential surface which defines the stellar shape. One effect
is a 'flattening' of the star for faster rotation.
Another effect is that the 'critical lobe',
i.e. the largest possible surface, is modified. For faster rotation, it
becomes smaller than the Roche lobe (which is the 'critical lobe' for
a synchroneously rotating star, as discussed 
  \hyperref
    {here}
    {in Section\ } 
    {}
    {roche}).
In this situation, you might have two binary component, both filling
their 'critical lobes', but well separated from each other.\\

\ni
For slower rotation, the 'critical lobe' can become larger than the Roche 
lobe... {\sc nightfall} will check (and complain), if both stars intersect.
(While an overcontact system with synchroneous rotation is no problem,
asynchroneous rotation, with contact, will cause heavy friction, I would
think, presumably leading to rapid synchronization. Thus a contact
system with asynchroneous rotation probably is unrealistic.)\\

\ni
Surface spots  (if there are any) 
will move with the stellar rotation rate (just as they should).

\subsection{Eccentric Orbit}

\noindent
According to Keplers \label{eccentric} laws, the shape of the orbit is 
an ellipse. Often, it is close to a special case of an ellipse - a circle.
However, sometimes binary orbits are markedly eccentric, i.e. non-circular.
In an eccentric orbit,
the distance and the orbital velocity is not constant. The stars will
gain velocity, as they fall toward each other, and 
move fastest at Periastron (closest approach). They will lose
velocity again as they move away from each other, and move slowest at Apastron
(largest distance). Thus the time between first and second
eclipse in general is different from the time between second and first.
Also, the width of the eclipses may be different, as in general 
the stars will move with different velocities during the two eclipses.
{\sc nightfall} comes with sample data for the star 'V541 Cygni', an eccentric
binary system where you can observe both effects.\\

\ni
Similar to asynchroneous rotation, the comment applies that tidal forces
will act towards circularization of the orbit. Eccentric orbits are more
likely in wide binaries than in close ones. \\

\ni
The problem is, that in an eccentric orbit the changing distance 
is equivalent to a changing Roche lobe filling factor, 
and thus a changing shape of the star 
(remember, the larger the Roche lobe filling factor, the
larger also is the nonspherical distortion of a star's shape). 
While in a circular orbit the stellar surface is calculated only once,
and then just rotated in space, in an eccentric orbit the stellar surface
must be re-calculated at each step in orbital phase, thus causing substantial
computational overhead. \\

\ni
To switch on this option, use \\

{\bf  -e eccentricity periastron\_length}\\

\ni
where 'eccentricity' (range 0-1, 0 is circular orbit) is defined as
\[ e = \frac{r_2 - r_1}{r_2 + r_1}, \] with $r_2$ is the largest and 
$r_1$ the smallest distance. Clearly, $e = 0.0$ if $r_2 = r_1$,
which is the case for a circular orbit. $e = 1.0$ is a 
degenerate case (a parabola), which cannot be handled by the program.
'periastron\_length' is the length (in degree) of the periastron,
i.e. the point of closest approach in the orbit. To find out how it is 
counted, you may set the Roche lobe filling factor to 1.0, and e to a high
value, like 0.5, Then, using the animation option (-A), you can identify
the periastron easily, as the star will fill the Roche lobe at closest
approach.

\noindent
The input Roche lobe filling factor is assumed at Periastron.
Due to the variable orbital velocity, 'synchroneous' rotation is not really
synchroneous - rotation will lag behind the orbital motion for part of the
orbit, and advance for the other part of the orbit.
Surface spots (if there are any) will move accordingly.\\


\subsection{Limb Darkening}

\ni
The depth to which you can see into a star's atmosphere (where the visible
light comes from) varies with
the viewing angle. As the temperature (which determines the light flux)
increases with depth, you can see hotter (= brighter) layers
of the atmosphere towards the centre of the star's disk, where you
can look deeper. Towards the limb, you see shallower, cooler, and thus
less bright layers of the atmosphere.
This results in the limb of a star being darker than the
centre of its visible disk, an effect that can be seen readily on good (!)
photographies of the Sun.\\

\ni
Limb darkening, as a function of the cosine of the viewing angle 
towards the stellar surface,
is well aproximated by simple expressions. {\sc nightfall} offers three 
different options, with expressions that are linear or include
additional square or square root terms. The square root law
is probably most accurate, but you will
find that there is not much difference. \\

\ni
The default is the linear law. To change this, use \\

{\bf  -Ln}\\

\ni
with 'n' a number in the range 0-2 (0 = default).\\



\subsection{Surface Spots}

\ni
Cool stars like the sun (i.e. stars with surface temperatures of a 
few thousand Kelvin only) \label{spotted}
often have surface spots, which are regions of somewhat lower temperature
on the surface. Among such stars, some are
known to have surface spots ('starspots') much larger than those 
shown by the Sun. In extreme 
cases, spots may cover a few tenths of the stellar surface. Usually, these
are cool spots (i.e. a few 100 K cooler than the surrounding area), caused
by magnetic activity (like on the Sun). \\

\ni
To include spots, use \\

{\bf  -sP longitude latitude radius dimfactor} or\\

{\bf  -sS longitude latitude radius dimfactor} \\

\ni
(-sP for a spot on the Primary, -sS for a spot on the secondary).
Spots are circular. The arguments are longitude and latitude of the spot's
centre, the radius (all in degree) and the factor, by which the surface
temperature is changed in the spot area. You can have multiple spots on each
star. For overlapping spot areas, 'dimfactor' is averaged.\\

\ni
It is possible, but physically very unrealistic, to set 'dimfactor' to rather
low or high values (0.5 - 2.0). Temperature deviations of more than about
1000 K may be not realistic. Hot spots are seen only in
exceptional cases. 


\subsection{Radial Velocities}

\noindent
Unlike lightcurves, which can be expressed in a relative unit, radial
velocity curves only make sense in absolute units (km/s in {\sc nightfall}). 
Thus, they require absolute dimensions as input for the system.
({\sc nightfall} supplies default values, however, if you don't want to
bother about this.) Use \\

{\bf  -tP period} or \\

{\bf  -tM mass} or \\

{\bf  -tD distance}\\

\ni
('period' in days, 'mass' ( = total mass of both stars) in solar masses,
'distance' in solar radii.) You need to give two of these; the third
can (and will) be calculated from Kepler's third law. \\

\noindent
Radial velocities are computed as the sum of the orbital velocity of a point
mass plus corrctions (flux-weighted contributions from each surface element). 
In animated view, you can see the resulting sum as well as the correction term
(the latter multiplied by 2).

\subsection{Line profiles}

\ni
{\sc nightfall}  can calculate spectral line profiles at each phase
step, which are output to files (one for each phase step). You can
specify the rest wavelength 'lambda\_zero' for the line.
The luminosities (of individual surface elements)
used to compute the profile are those for the passband with the closest 
effective wavelength. To switch on, use \\

{\bf  -Plamda\_zero}\\

\ni
In interactive mode, you have the option to view the line profiles, and
change the phase interactively.\\

\ni
{\it Some numerical artifacts present, probably due to finite surface grid.}


\subsection{Third Light}

\noindent
The presence \label{third} 
of an additional light source in the system (e.g. a third star)
will decrease the contrast between eclipsed and non-eclipsed parts of the
lightcurve. To include this effect, use \\

{\bf  -3filter fraction}\\

\noindent
where 'filter' is one of the supported filters (UBVRIJHKuvby) and
'fraction' is the relative contribution of third light
to the total system luminosity. I.e.: \[ L1 + L2 + L3 = 1.0,\] 
where $L1 + L2$ is the combined light flux from Primary and Secondary,
and $L3$ is 'third light'.\\

\noindent
{\undertext{This option is not tested yet.}}


\newpage
\begin{rawhtml}
<HR>
\end{rawhtml}

\section{Fitting observed data}

\ni
{\sc nightfall} offers \label{fitting} 
the possibility of determining a best-fit model
for observed data. Several datasets can be fit simultaneously. 
Both a local and a global optimization algorithm are available.
{\bf Fit results} are written to a file 'NightfallFitted.dat'.

\subsection{Reading in the data}

\noindent
In order \label{dataread} 
to determine a best-fit model to observed data, you first
have to read them into memory. Use \\

{\bf  -I path/to/data/file}.\\

\ni
Only one file is read. To read more files, prepend each of them with a
{\bf -I}. You can read in (only) one datafile for each filter.\\

\noindent
Each row in the file should consist of two or three numbers. The first
is the date of the observation (as decimal number, in any unit you like),
the second the measurement value (in magnitudes
for brightness, in km/s for radial velocity), and the third (optional) 
the estimated error of the measurement.\\

\ni
Lines starting with a '\#' are ignored, with the following exceptions 
(no blank after '\#' !!):\\

\ni
{\bf \#P period}
gives the orbital period of the system (same unit as dates). 
The program will use this value
to fold the data into orbital phase. The default is 1.0 (thus assuming
that your data are already folded in phase).\\

\ni
{\bf \#Z zeropoint}
gives the zeropoint for orbital phase, i.e. the time of Primary eclipse 
(same unit as dates).
The default is 0.0 (again assuming
that your data are already folded in phase).\\

\ni
{\bf \#B filter}
gives the filter (UBVRIubvyJHK) in which your data have been observed. 
Default is V. For radial velocities, use '1' for Primary, '2' for Secondary.\\

\ni
{\bf \#W error}
gives the average estimated error of measurements (if you do not have 
individual ones). Default is 0.01 (brightness) or 1.0 (radial velocities).
You can mix individual and average error estimates (e.g. if you have
individual error estimates only for some of your data).\\

\ni
{\bf \#V system\_velocity}
For radial velocity curves, use this parameter to set the system velocity.
Radial velocities will be set to $data - system\_velocity$.\\

\ni
{\bf \#N normalisation\_phase}
Use this parameter to set the phase at which to normalize the light curve.
The default is the starting point of the lightcurve.\\

\ni
{\bf \#S shift}
This is a particular important parameter that requires some care. As noted
in 
  \hyperref
    {the info on brightness,}
    {in Section\ } 
    {,\ }
    {norm}
{\sc nightfall} will normalize its lightcurves to light at
the normalisation\_phase (see above), 
which by default is the starting point 
of the lightcurve (the leftmost in the plotted lightcurve).
Thus, at this point, the brightness is zero magnitudes. 
For a meaningful fit, your observed lightcurve must be shifted up/down 
to have the value zero at this point as well (within the measurement
errors). {\sc nightfall} will
try to do it automatically, but some correction may be required. Plot the 
lightcurve (data will be overplotted, if there are any), and check.
Note: incorrect use of this parameter may make a fit look better, but
the fitted parameters might be meaningless. Do not shift to anywhere else
than the starting point of the lightcurve.\\


\noindent
The source code distribution includes example files for the binaries
TY Boo (an overcontact system) and some more. If in doubt, look into them.


\subsection{Finding a local optimum}

\noindent
Determining a best-fit model means to optimize the parameters (like
inclination, temperature, mass ratio, etc.) in such a way that the mismatch
between model and observation is minimized. This mismatch is measured
by a suitable {\bf merit function} 
(sometimes also called {\bf cost function}). {\sc nightfall} uses the
chi-square function as merit function.\\

\noindent
General problems of determining best-fit parameters are:\\

\noindent
(1) uniqueness: there may be several/many (nearly) equally good solutions.
Do a few trials. {\bf Restart} fitting with last best-fit as starting point.\\

\noindent
(2) overfitting: the information content of a lightcurve is limited. Fitting
too many parameters might produce good-looking, but meaningless results.
Use as few free parameters as are sufficient for a good fit.\\

\noindent
(3) local vs. global optimum: just that you find a valley, doesn't mean this is
the deepest valley on Earth. The same applies to optimization problems.
Any local optimization algorithm will only find a local optimum. If
the problem is well-behaved, this will be the one and only, global, optimum.
If the problem is badly-behaved, you might need a few trials with different
starting points to find (hopefully) the global optimum. If the problem
is even worse, you might need an awful lot of computing time to find
the global optimum. Most examples in textbooks are nice. Most real-world 
optimization problems turn out to be bad or even ugly.\\

\noindent
{\sc nightfall} uses the so-called Simplex algorithm for local
optimization. This is a direct search algorithm that is not terribly fast 
(and not terribly slow either),
but very robust. To switch on optimization, use\\

 {\bf  -Xparameters tolerance}\\

\noindent
where 'parameters' is a string of characters indicating the parameters
you want to fit (all others kept fixed), and 'tolerance' is the stopping
criterion (something like 0.1 or less would be appropriate - 0.001 has 
a special meaning, see 
  \hyperref
    {the section on global fitting}
    {Section\ } 
    {}
    {global}).
Use
'nightfall' without options to get the character codes for fit parameters.\\

\noindent
If more than one data file is input (e.g. lightcurves in different filters), 
{\sc nightfall} will fit all data simultaneously. This will probably work
well only if different datasets are properly weighted - i.e. if the 
error estimates (or at least their ratios) are ok.\\

\ni
Have a cup of coffee ready. Use the {\bf  -Db} option (switch on 'Busy' in
interactive mode) to see what is going on meanwhile.\\

\ni
{\bf IMPORTANT:} Restart fit with last best-fit as starting point. 
Continue this until you are sure that the solution has converged and does not
improve anymore, i.e. the value of 'SDV (Chi square)' does not significantly
change anymore. Otherwise, your results may be {\bf completely meaningless}.
(swich on the -Db option to see 'SDV (Chi square)' for each iteration --
see
   \hyperref
    {the info on debug options.}
    {Section\ } 
    {.}
    {debug}\\

\ni
{\it Output is always written to a file 'NightfallFitted.dat'.}

\subsection{Goodness-of-fit}

\ni
To evaluate how good a fit is, {\sc nightfall} offers the following
options:\\

\ni
(1) if you plot the lightcurve, residuals will be plotted as well. Look
at them to check whether there are systematic trends ( = bad fit). \\

\ni
(2) for a good fit, the residuals should scatter randomly around the 
model, with no systematic trends. This can be quantified by computing the
'runs statistic' (the number of runs = occurences of two or more 
{\bf consecutive} residuals above or below the model curve). Obviously,
a large number of  runs would occur for a strictly alternating sequence, 
which is very unlikely for a random sequence. Likewise, only two runs
would occur for the first half of the data below, the second above the 
model curve - also suspiciously non-random. The expected number of runs can
be calculated analytically. {\sc nightfall} will print out the actual number
of runs, and the lower and upper limits for a 90 percent confidence interval.\\

\ni
(3) in theory, the goodness-of-fit can be evaluated from the $\chi^2$ 
(Chi Square) value of the fit (the function actually minimized in 
parameter fitting), which should be close to unity for a good fit. 
However, this only works
if the error estimates for the measurements 
are realistic - neither to high nor to low. This is
very rarely the case in astronomy ...


\subsection{Finding a global optimum}

\noindent
To find a \label{global} global optimum, 
basically a stochastic search strategy is required
(or an exhaustive seach of the complete parameter space ...).
There are different possibilities, ranging from complete random search to
some 'intelligent' variation of random search. {\sc nightfall} offers
'Simulated Annealing', which is a kind of mathematical implementation of
the cooling of matter (leading to crystallization, i.e. an energy optimum,
if cooling is slow enough). Switch on by setting the fit tolerance to 0.001
(in command-line mode).\\

\noindent
Be prepared for a computing time on the order of a day or more (if you have
no other CPU-expensive job running).\\

\noindent
I am not sure whether the algorithm is correctly implemented. In the
present implementation, cooling
might be too fast, or might stop at a too high 'temperature'. However,
my own experiments were rather satisfactory most of the time.\\

\noindent
Apparently, 'Simulated Annealing' does not mathematically 
guarantee that the global optimum is indeed
found, unless 'cooling' proceeds infinetely slow ... 

\subsection{Mapping the Chi-Square function}

This option will create a two-dimensional map of the
merit function (i.e. in the case of {\sc Nightfall} the 
Chi-Square function that measures the
goodness of a fit) with respect to two parameters.
Start values are the current values, step values
can be entered. The gridsize is fixed at compile time
(default 16 x 16, i.e. 256 lightcurves will be evaluated).
To switch on this option, use\\

 {\bf  -Xparameters step1 step2}\\

Parameters are coded like in the fitting option (see above),
but only two parameters should be chosen.


\newpage
\begin{rawhtml}
<HR>
\end{rawhtml}

\section{Miscellaneous}

\subsection{Debug options}

{\bf  -Dcharacterstring}\\

\noindent
Most debug \label{debug} options (selected by 'characterstring') 
are of little use
unless you know the code rather well. Some will produce excessive 
(and excessively messy) output.\\

\ni
Exceptions are:

\begin{itemize}

  \item {\bf b} ('busy'), which keeps your screen somewhat busy
        in case you do something computationally expensive 
        (data fitting, elliptical orbit).

  \item {\bf w} ('warning'), which will print out warnings. Usually,
        these refer to problems that the program can deal with, and
        thus you can ignore them. If you do not get the output you expect,
        you might want to turn them on to see what the program complains
        about.

  \item {\bf v} ('verbose'), which will print out a moderate amount of 
        information (will grow excessive during data fitting ... use 'b' 
        instead if you just want to see what's going on).

\end{itemize}


\subsection{Output of the surface map}

It is possible to obtain the 2D surface map of the stars, as seen by an
observer, i.e. the map displayed in animated mode. 
You have to set the environment variable
NIGHTFALL\_SMAP\_PATH to the path of the map file (the program will
append the index of the phase to this, i.e. you will get a seperate file for
each step in orbital phase). If NIGHTFALL\_SMAP\_PATH is undefined,
no map will be printed.

By default, the map will be output for the V band; you can change that
with the environment variable NIGHTFALL\_SMAP\_BAND (0..11 for UBVRIJHKuvby).

The map includes for each {\it visible} surface element:\\ 
\hs{1cm} (1) the index of the star,\\ 
\hs{1cm} (2) the index of the surface element,\\ 
\hs{1cm} (3, 4) x, y coordinates in the viewing plane of the observer, 
with the star at (0, 0),\\
\hs{1cm} (5, 6) x, y coordinates as above, but with the centre of mass 
at (0, 0),\\
\hs{1cm} (7) $\cos{\gamma}$, the line-of-sight angle,\\ 
\hs{1cm} (8) temperature, \\
\hs{1cm} (9) dimensionless gravity,\\
\hs{1cm} (10) area,\\ 
\hs{1cm} (11) flux.\\ 
The flux is not normalized to the area; it is the flux that this surface
element contributes to the total flux. 


\subsection{User-defined wavelenghts}

It is possible to compute monocromatic fluxes at up to twelve different,
user-defined wavelengths. These wavelengths (unit: micrometer) must be
provided as a comma-seperated list in the environment
variable NIGHTFALL\_MONO\_WAVE. They will replace the wavelenghts used in the
blackbody approximation.

\begin{itemize}

  \item
  If less than twelve wavelengths are given, the remaining ones will be filled
  in with the wavelengths of the corresponding passbands.

  \item
  For each wavelength, 
  {\sc nightfall} will use the limb darkening
  coefficients of the passband whose wavelength matches 
  best the monochromatic one.

  \item
  Blackbody approximation must be selected (i.e. the 'model atmosphere' option
  must be switched off), otherwise these user-defined
  wavelengths do not take effect.

\end{itemize}

\newpage
\begin{rawhtml}
<HR>
\end{rawhtml}

\section{Technical details}

\it
This section is intended as a technical reference for experts who want to
familiarize themself with the nasty details and the algorithms used.

\rm

\subsection{Geometry}

\noindent
The geometric setup is based on a paper \cite{djura92a} 
by Djura\v{s}evi\'{c} (1992a).
In a cartesian coordinate system $(x, y, z)$, the stars are located at
$(0, 0, 0)$ and $(1, 0, 0)$, and the $z$-axis is perpendicular to the orbital
plane.
A normalized, dimensionless Roche potential is used, which at a point
$P(x,y,z)$ is given by the value $C$ as
\[ C = \frac{1}{r_1} + q (\frac{1}{r_2} - x) 
	+ \frac{q + 1}{2} ( x^2 + y^2 )f^2, \]
with $r_1 = x^2+y^2+z^2$, $r_2 = (x-1)^2+y^2+z^2$,
mass ratio $q = m_2/m_1$, and nonsynchronism parameter $f = w/w_k$
(i.e. the ratio of the angular velocity to the Keplarian angular
velocity).\\
For practical purposes, a spherical coordinate system $(r, \eta, \phi)$
is used, which is defined by
\begin{eqnarray*}
   x & = & r\ \cos{\eta},\\
   y & = & r\ \sin{\eta}\ \cos{\phi},\\
   z & = & r\ \sin{\eta}\ \sin{\phi}.\\ 
\end{eqnarray*}
The surface of the star is then divided into elementary areas by a grid
in $(\eta, \phi)$, and for each surface element the gravity
acceleration $g(r, \eta, \phi)$, the area $dS(r, \eta, \phi)$, and the normal
vector $(l, m, n)$ is computed as outlined in \cite{djura92a}.\\

\noindent
{\it Notes}:
{\bf (i)} Equation (1-16) in  \cite{djura92a} has a minor typo 
(wrong sign for $l$).\\
{\bf (ii)} Djura\v{s}evi\'{c} \cite{djura92a} apparently uses 
equidistant steps in $\phi$, thus leading
to very unhomogeneous elementary areas. {\sc nightfall} avoids this
by adjusting the number of steps  $N_{\phi}$ as 
\[ N_{\phi} = 10 + N_{\eta} sin{\eta},\]
with $N_{\eta}$ a (compile-time) constant.

\subsubsection{Accretion disk}
Eclipse testing for the accretion disk is based on the method described in \cite{djura92a} 
by Djura\v{s}evi\'{c} (1992b).


\subsection{Reflection and gravity darkening/brightening}

\noindent
There are two options available for the treatment of reflection.
Both are {\it bolometric} corrections, in the sense that the bolometric
flux of the irradiating component is used to modify the temperature
distribution on the irradiated component. See \cite{wilso90} for a discussion
of this issue.\\

\noindent
The 'simple' option for the treatment of reflection is described 
in \cite{djura92a}. The correction should be 
exact for spherical stars.\\

\noindent
The 'detailed' reflection treatment loops over all pairs of surface
elements $(dS_1,dS_2)$ and sums up, for each surface element $dS_1$,
the irradiation by all visible surface elements $dS_2$ of the other star.
Again, {\it bolometric} irradiation is computed. Of course, the true
temperature of the irradiating surface elements (including reflection)
is not known, thus it is necessary to iterate the algorithm. Convergence
is typically reached after 2-3 iterations.
The algorithm is described in \cite{hendr92}.\\

\noindent
For both treatments, by default for convective stars 
(below 7700 K) an albedo of 0.5, and for
radiative stars an albedo of 1.0 is used. It is possible to 
choose different albedo values at program start using
the command line option(s) {\tt -aP} {\it value} for the primary and
{\tt -aS} {\it value} for the secondary.\\

\noindent
Gravity darkening is computed by
\[ T(r, \eta, \phi) = T_{eff}(\frac{g(r, \eta, \phi)}{g_{eff}})^{\beta}. \]
For the gravity brightening exponent, the results from \cite{claret00a}
(Fig.~1 in the paper) are used, which provide a smooth transition to the
Von Zeipel (1924) exponent of 0.25 for radiative stars.\\

\noindent
{\it Notes}:
{\bf (i)} The 'simple' reflection treatment in \cite{djura92a} 
has been supplemented by a penumbral correction for 
the partial visibily of the other star, if it is at the horizon. 
This penumbral correction assumes that the horizon is flat 
and that the other star
is spherical, i.e. that the visible part is a segment of a circle.\\
{\bf (ii)} For the 'detailed' reflection treatment, instead of 
the quadratic limb darkening law used by
\cite{hendr92}, a square root law (\cite{diaz92}) 
\[ I(\mu) = I(1)[1 - c(1-\mu) - d(1 - \sqrt{\mu})] \]
is used (where $\mu$ is the cosine of the angle subtended by the emergent
radiation and the direction perpendicular to the stellar surface), 
and bolometric 
limb darkening coefficients are taken from \cite{claret00}.
The normalization factor for the square root 
law was calculated as 
\[ \frac{1}{\pi\ (1 - c/3 - d/5)}.\]
{\bf (iii)} The temperature limit of 7700\,K dividing stars with 
convective/radiative envelopes can be changed by the environment
variable NIGHTFALL\_RADIATIVE (within the range 4000 -- 12000\,K).
This changes the albedo only (0.5 below, 1.0 above).


\subsection{Spots}

\noindent
Spots are always circular, and 
characterized by four parameters: longitude $\lambda$, 
latitude $\beta$, radius $r$, and a 'dimming' factor $A_p = T_p/T$,
i.e. the ratio of the (local) temperature $T_p$ with spot to the temperature
$T$ without spot. A detailed discussion of the trigonometric 
expressions used to identify surface elements within the spot area
can be found in \cite{djura92a}, section I-3.
In the 'detailed' reflection treatment, 
reflection is calculated with spots, i.e. the spots are applied first,
then the reflection is calculated. For overlapping spots, in the overlap area
the mean value of their $A_p$ is used.

\subsection{Output flux}

\noindent
In the blackbody approximation, for each stellar component and 
each filter a (temperature-dependent)
effective wavelength is computed, following  Equation 3.30 in
\cite{buddi93}:
\[  {\lambda}_{eff} = {\lambda}_{0} 
      + \frac{ 5 {\mu}_2 ({\lambda}_{p}-{\lambda}_{0}) }{\sqrt{{\lambda}_{0}}},
\]
where ${\lambda}_{0}$ is the filter wavelength, and ${\lambda}_{p}$
the wavelength of the blackbody peak for the effective temperature of the
respective component.
The required second moments ${\mu}_2$ of the filter passbands 
are computed following the prescription by \cite{young92}, Equation 12:
\[ {\mu}_2 \simeq \frac{FW(0.05)}{4.4}, \] where $FW(0.05)$ is
the full width at the 0.05 level.\\


\noindent
For the 'model atmosphere' option, fluxes for temperatures below 9800\,K are
from Hauschildt et al. (private comm., 2006) PHOENIX models, 
otherwise flux tables from Kuruzc models (\cite{kuru98}).
are used. All models are for solar abundances. PHOENIX models below
2000\,K incorporate dust formation, with dust remaining in situ (no settling).
The (originally monochromatic) fluxes have been integrated over
the filter passbands (as given in \cite{lando82}).
Surface gravities $\log{g} = 3.5 - 5.0$ (in steps of 0.5) are available.\\
 
\noindent
Three different limb darkening approximations are available, a {\it linear},
a {\it quadratic}, and a
{\it square root} one, 
which are given by the following expressions, respectively:
\begin{eqnarray*}
I(\mu) & = & I(1)[1 - u(1-\mu)],\\
I(\mu) & = & I(1)[1 - a(1-\mu) - b(1-\mu)^2],\quad {\rm and}\\
I(\mu) & = & I(1)[1 - c(1-\mu) - d(1 - \sqrt{\mu})],\\
\end{eqnarray*}
where $\mu$ is the cosine of the angle subtended by the emergent
radiation and the direction perpendicular to the stellar surface.
Limb darkening coefficients are from \cite{claret00}.   
A discussion of the relative
merits of these three approximations can be found in \cite{diaz92}.

\noindent
{\it Notes}:
{\bf (i)} When tabulated values are used, for temperatures out of 
range (below 2000\,K and above 31000\,K for $\log{g} = 3.5$, 
39000\,K for $\log{g} = 4.0$, 49000\,K for $\log{g} = 4.5$,
50000\,K for $\log{g} = 5.0$) the
lowest/highest value is used (i.e. no extrapolation is attempted).
 

\subsection{Eclipse testing}

\noindent
Eclipse testing follows the method proposed in \cite{djura92a}. First,
the contact angle of the Roche lobes is used to exclude eclipses, if
possible.\\
If an eclipse is possible, 
for each surface element $dS$ the line of sight (LOS) towards $dS$
is tested for intersection with the smallest sphere enclosing the
eclipsing star (no intersection = not eclipsed). Then the LOS is
tested for intersection with the largest sphere within the
eclipsing star (intersection = eclipsed). This procedure takes advantage
of the simplicity of testing the intersection of a line with a sphere.\\
If the LOS intersects the outer, but not the inner sphere, as a last 
(and computationally expensive) resort, the minimum of the Roche potential
along the LOS is searched, and compared against the surface potential
of the eclipsing star.\\

\noindent
{\it Notes}:
{\bf (i)} In \cite{djura92a}, the osculating cone (i.e. the tangent cone
to the Roche surface at the inner Lagrangian point $L_1$) is used as the first
eclipse criterion. According to \cite{chana72}, this can lead to serious
errors for mass ratios very different from unity, as the larger Roche lobe
is concave at the $L_1$. {\sc nightfall} uses tabulated values from
\cite{chana72} (the cone angle $\phi_{\rm max}$ as given in their Table 2).
{\bf (ii)} In \cite{djura92a}, the coordinate frame of the 
eclipsed star is used, for eclipse testing, 
which seems not to work for asynchroneous rotation.
{\sc nightfall} therefore uses the coordinate frame of the eclipsing star, 
following \cite{antok96}.
{\bf (iii)} In \cite{djura92a}, it is proposed to evaluate the potential
along the LOS at six steps only. {\sc nightfall} uses a more rigorous
approach with a minimum finding routine (Brent's algorithm \cite{brent73}).


\subsection{Fractional visibility}

\noindent
The eclipse testing routine assigns to each surface element a visibility
of 0 (eclipsed) or 1 (visible). However, the visibility is only
evaluated for the centre of the element. This can lead to 'spikes' in the
light curve, if large numbers of surface element centres become visible
at once. Therefore, an option is provided to compute a {\it fractional}
visibility for surface elements on the shadow limb.\\

\noindent
The algorithm first searches all pairs of elements on the shadow limb 
(i.e. pairs with
one element eclipsed, the adjacent element uneclipsed), and 
determines the potential minimum along the LOS towards them (which is typically
already available from the eclipse test). 
Then, a linear approximation is made:
for each pair, the 
distances $d_i$ to the shadow limb are taken as proportional 
to the differences
between  the minimum Roche potential $p_{i}^{LOS}$ along the LOS 
and the surface potential $p_{*}$
of the eclipsing star:
\[ f = \frac{d_1}{d_2} = \frac{p_{1}^{LOS} - p_{*}}{p_{2}^{LOS} - p_{*}}.\]
The surface element with the larger distance is assumed to be
completely eclipsed or visible, and the other one of the pair is assigned
a fractional visibility $(1/2 + |f|)$ based on the above approximation.
This is not exact for individual surface elements,
as the dividing line between them may not be parallel to the shadow limb.
However, averaged over all surface elements on the limb, the error
should be negligeable.


\subsection{Eccentric orbits}

\noindent
In an eccentric orbit, the complete geometry and temperature distribution
is re-calculated at each step ( = step in mean anomaly). As the Roche
potential is used in a dimensionless form, the change in distance
is equivalent to a change in the Roche volume filling factor 
( = surface potential) with an unchanged unit distance.\\

\noindent
This implies that the correct new surface potential must be found as
a function of the stellar volume, which is scaled up/down with the
distance. To avoid an iterative numerical integration of the stellar volume
(i.e. varying the surface potential until the correct volume is found),
which would be prohibitively expensive, the algorithm uses analytical
approximations from \cite{kopal} to derive the new surface potential.\\ 

\noindent
The following procedure is used:
\begin{enumerate}
\item Solve the Kepler equation to determine the distance of the stars 
	(and their position in the orbit).
\item Re-scale the distance to unity.
\item Scale the stellar volume by the the cube of the distance scale factor.
\item Find the 'mean radius' as the root of an analytical 
      expression for the stellar volume (of 11th order in this 'mean radius').
\item Compute the new surface potential as a function of the 'mean radius'.
\end{enumerate}

\noindent
Numerical details, including the definition of the 'mean radius', can 
be found in \cite{kopal}.

\subsection{Optimization}

\noindent
For local optimization, the Simplex algorithm is used. This is a
direct search algorithm that does not require derivatives. 
For $N$ free parameters,
the simplex is a polyhedron with $(N + 1)$ vertices (or points) in the
$N$-dimensional parameter space. At each step, the simplex moves
through this parameter space according to some rules, basically
moving away from its worst point.  
Details of the algorithm can be found in \cite{kallr87,nelder65}.\\

\noindent
For global optimization, an implementation of the 'simulated annealing'
method is provided. 
Basically, 'simulated annealing' does a stochastic search of 
the parameter space. Replacing the current best point with a better
point (i.e. a downhill step) is always allowed, 
replacing it with a worse point (an uphill step) is allowed with some
probability depending on the (steadily decreasing) 'temperature' of the
system.\\ 
The implementation is based on the 'Very Fast Simulated Re-Annealing' 
algorithm
\cite{ingber}, however, the 're-annealing' part is not included.
For random number generation, the
'Mersenne Twister' random number generator (period length $2^{19937} - 1$)
by Makoto Matsumoto and Takuji Nishimura \cite{mersenne} is used.
It has a Mersenne prime period of $2^{19937} - 1$ (about $10^{6000}$) 
and is equi-distributed in 623
dimensions. 
Mainly for debugging purposes, the seed is fixed, thus the 
generated sequence is always the same, and the results are reproducible.


\newpage
\begin{rawhtml}
<HR>
\end{rawhtml}

\addtocontents{toc}{\protect\contentsline{section}{\numberline {}References}{34}}

\begin{thebibliography}{99}

\bibitem{alenc97}
Alencar S.H.P., Vaz L.P.R. (1997), A\&A 326, 257 

\bibitem{antok96}
Antokhina E.A. (1996), ARep 40, 483

\bibitem{brent73}
Brent R. (1973), Algorithms for minimization without derivatives, 
Prentice-Hall

\bibitem{buddi93}
Budding E. (1993), 
An Introduction to Astronomic Photometry, 
Cambridge University Press

\bibitem{chana72}
Chanan G. A., Middleditch J., Nelson J.E.  (1972), ApJ 208, 512

\bibitem{claret00a}
Claret A. (2000), A\&A 359, 289

\bibitem{claret00}
Claret A. (2000), A\&A 363, 1081

\bibitem{diaz95a}
Diaz-Cordov\'{e}s J., Claret A., Gim\'{e}nez A. (1995), A\&ASS 110, 329
 
\bibitem{diaz95b} 
Claret A., Diaz-Cordov\'{e}s J., Gim\'{e}nez A. (1995), A\&ASS 114, 247

\bibitem{diaz92}
Diaz-Cordov\'{e}s J., Gim\'{e}nez A. (1992), A\&A 259, 227

\bibitem{djura92a}
Djura\v{s}evi\'{c} G. (1992a), Ap\&SS 196, 241

\bibitem{djura92b}
Djura\v{s}evi\'{c} G. (1992b), Ap\&SS 196, 267

\bibitem{hendr92}
Hendry, P. D., Mochnacki, S. W. (1992), ApJ 388, 603

\bibitem{peter99a}
Hauschildt P.H., Allard F., Baron E. (1999), ApJ 512, 377

\bibitem{peter99b}
Hauschildt P.H., Allard F., Ferguson J., Baron E., Alexander D.R. (1999), 
ApJ 525, 871

\bibitem{ingber}
Ingber L. (1989), J.Math.Comput.Modelling 12, 967

\bibitem{kallr87}
Kallrath J., Linnel A.P. (1987), ApJ  313, 346


\bibitem{kopal}
Kopal Z. (1989), The Roche Problem,
Kluwer Academic Publishers

\bibitem{kuru98}
Kurucz R. L. 1998, http://kurucz.harvard.edu/grids/gridp00/ip00k2.pck19,
accessed 2006-04-12

\bibitem{lando82}
Landolt-Boernstein (1982),
Numerical Data and functional Relationships in Science and Technology. 
New Series, Berlin: Springer 

\bibitem{mersenne}
Matsumoto M. \& Nishimura T., 
ACM Transactions on Modeling and Computer Simulation, Vol. 8, No. 1, p. 3

\bibitem{nelder65}
Nelder J.A., Mead R. (1965), Comput. J. 7, 308

\bibitem{vanha93}
Van Hamme W. (1993), AJ 106, 2096

\bibitem{wilso90}
Wilson R.E. (1990), ApJ 356, 613

\bibitem{young92}
Young A.T. 1992, A\&A 257, 366

\end{thebibliography}



\newpage
\begin{rawhtml}
<HR>
\end{rawhtml}

\begin{appendix}

\section{Command line Options}

\begin{tabular}{ll}
\hline
                      &                                              \\
{\bf Mandatory:}      &                                              \\
           (q)        &  mass(Secondary)/mass(Primary)               \\
           (i)        &  inclination angle (degree)                  \\
           (rf1)      &  Primary Roche fill factor                   \\
           (rf2)      &  Secondary Roche fill factor                 \\
           (t1)       &  Primary  temperature                        \\
           (t2)       &  Secondary temperature                       \\
\hline
                      &                                              \\
{\bf Interactive:}    &                                              \\
          -U          &  Interactive mode                            \\
\hline
                      &                                              \\
{\bf Graphic Output:} &                                              \\
          -A          & Animated view                                \\
          -V[v,i,c,a] & Visualize geometry (default: v)              \\
                      &  v: view of stars                            \\
                      &  i: image of potential                       \\
                      &  c: contourmap of potential                  \\
                      &  a: all of the above                         \\
          -G[P,S,1,2] &  Graph of lightcurve (default: 1)            \\
                      &    P,S: close-up of Primary/Secondary eclipse\\
                      &    1,2: display 1/2 orbital cycles           \\
          -B[U/B/V...]& Bandpass to display in graph (default: V)    \\
          -H          & Hardcopy (postscript plot)                   \\
\hline
                      &                                              \\
{\bf Files:}          &                                              \\
          -I datafile & Read in a data file containing observed data \\
          -C cfgfile  & Read in a configuration file                 \\
\hline
                      &                                              \\
{\bf Advanced System Parameters:} &                                  \\
          -f[P/S] F    & 
			asynchroneous rotation ratio (Period/Period\_Orbit)  \\
          -s[P/S]  longitude latitude radius dimfactor &
                   	Spot on Primary/Secondary                            \\
           -e e w      & 
                  eccentric orbit, e = eccentricity, w = periastron length   \\
          -t[P/M/D] value & period/total mass/separation 
                      	in days/solar masses/solar radii                     \\
\hline
                      &                                              \\
{\bf  Debugging Options:} &                                          \\
          -D[vwb]         & Debug [verbose,warn,busy]                \\
\hline
                      &                                              \\
{\bf Computation Options:}&                                          \\
          -Plamda\_zero   & Profile of absorption line at
                                 rest wavelength lamda\_zero (nm)    \\
          -Nnn            & nn steps for lightcurve (default 80)     \\
          -M              & use Model atmosphere                     \\
	  -O[P/S] value   & $\log{g}$ (surface gravity) Primary/Secondary\\
          -F              & compute Fractional visibility            \\
          -L[0-2]         & Limb darkening method (default: linear = 0)\\
                          & 0: linear                                 \\
                          & 1: quadratic                              \\
                          & 2: square root                            \\
          -R[1-9]         & Reflection treatment                      \\
                          & 0: Point source                           \\
                          & 1-9: iterations for mutual reflection     \\
          -a[P/S] value   & Albedo of Primary/Secondary \\
                          & (default: 0.5 for T $<=$ 7700, 1.0 otherwise)\\
          -3CM            & Third light, C: colour code, M: magnitude \\
\hline

\end{tabular}
\newpage
\begin{tabular}{ll}
\hline
                      &                                              \\
{\bf Data Fitting:}   &                                              \\
          -X[..] Tolerance& Fit the parameters coded in string [..]  \\
                          & 012345: q, i, rf1, rf2, t1, t2           \\
                          & 67: e, w   (eccentric orbit)             \\
                          & 89: F(Primary),F(Secondary) (asynchroneous rotation) \\
                          & A-H:     2 Spots (Primary)               \\ 
                          & I-P:     2 Spots (Secondary)             \\
                          & QR:      Mass, Separation\\
                          & a-l:     Third Light (UBVRIJHKuvby)      \\
                          & (Tolerance = 0.001 to use Simulated Annealing)\\
          -Y[as above] Step1 Step2 & Chi Square Map (2 Parameters)   \\
\hline
\end{tabular}

\end{appendix}


  
\end{document}





