1 2\documentclass[a4]{article} 3\usepackage{mathrsfs} 4\usepackage{html} 5\pagestyle{empty} 6% DIN A4 7\setlength{\topmargin}{0.46cm} 8\setlength{\oddsidemargin}{0.46cm} 9\setlength{\textwidth}{15cm} 10\setlength{\textheight}{22cm} 11 12\def\undertext#1{$\underline{\smash{\hbox{#1}}}$} 13 14\def\ni{\noindent} 15\def\sk{\smallskip} 16\def\ms{\medskip} 17\def\bs{\bigskip} 18\def\vs{\vspace*} 19\def\hs{\hspace*} 20 21\bodytext{<BODY text="#000000" bgcolor="#ffffff">} 22 23\begin{document} 24 25\vspace*{4cm} 26 27\begin{center} 28 29\huge{\bf Nightfall User Manual} 30\end{center} 31 32\vspace*{2cm} 33 34\begin{center} 35\large{\bf 36 by R. Wichmann\\ 37 (rwichman@lsw.uni-heidelberg.de) 38} 39\end{center} 40 41\newpage 42 43\tableofcontents 44 45\newpage 46\begin{rawhtml} 47<HR> 48\end{rawhtml} 49 50\section{Introduction} 51 52\noindent 53{\sc nightfall} is an interactive application that introduces into 54the fascinating realm of eclipsing binary stars. Apart from their light 55variations that make them interesting objects for observations, 56eclipsing binaries are of fundamental importance for astrophysics, e.g. 57for measuring the mass of stars. 58{\sc nightfall} is capable of producing: 59 60\begin{itemize} 61 \item animated views of eclipsing binary 62 stars, 63 \item lightcurves and radial 64 velocity curves, 65 \item best-fit binary star parameters for a given set of observational data. 66\end{itemize} 67It is, however, not able to fry your breakfast 68egg on your harddisk.\\ 69 70 71\noindent 72Eclipsing binary stars are most often very close systems. In such systems, 73owing to tidal forces, the shapes of both stars can be highly nonspherical, 74up to the possible formation of an 'overcontact' system, where both stars 75form a single, dumbbell-shaped object.\\ 76 77 78\noindent 79{\sc nightfall} is a mildly ultramundane program of baroque complexity 80(I like Verdi and H\"andel on lazy sunday mornings - friday evenings are 81better with Iron Maiden and a good whisky). 82{\sc nightfall} is based on a physical model that 83takes into account the nonspherical 84shape of stars in close binary systems, as well as mutual irradiance 85of both stars, and a number of additional physical effects.\\ 86 87\noindent 88{\sc nightfall} can handle a large range of configurations, including 89overcontact systems, 90eccentric (non-circular) orbits, 91surface spots and asynchroneous rotations (stars rotating 92slower or faster than the orbital period), and the possible presence of a 93third star in the system.\\ 94 95\noindent 96{\sc nightfall} supports OpenGL (or MesaGL) for an animated display of 97binary systems. Individual frames of the animation can be saved as JPEGs 98to create am MPEG movie.\\ 99 100\noindent 101{\sc nightfall} can be build in a parallelized version, if your compiler 102supports the OpenMP standard (e.g. sufficiently recent versions of gcc do).\\ 103 104\noindent 105{\sc nightfall} supports the GNOME desktop (if installed), but does 106{\it not} require it.\\ 107Also, {\sc nightfall} supports {\it internationalization}. Currently, 108besides the default language (english), only german is supported. The 109language is selected by the environment variable LANG (must be set 110before starting the program, 111in sh, bash: {\tt LANG=de; export LANG}\\ 112in csh, tcsh: {\tt setenv LANG de}). 113 114\subsection{Remarks} 115 116\noindent 117{\sc nightfall} is not part of my 118research work - rather it is the result of a recreational activity aimed 119at distracting myself 120from daily research work.\\ 121 122\ni 123I have tested {\sc nightfall} with published data on several binary stars. 124Data for these systems are included in the source code 125distribution. As no two light curve programs use exactly the same 126algorithms, results are never identical; however, results from 127 {\sc nightfall} appear to be within the range of similar 128light curve programs used in the literature. I hope 129that I have found most flaws in the logic of the code, at least in the 130'scientific' part. If you want to use 131{\sc nightfall} for a publication, you may want to evaluate its 132performance by yourself. 133{\sc nightfall} comes WITHOUT ANY WARRANTY 134(see also 135\hyperref 136 {the copyright statement} 137 {Section } 138 {\ } 139 {copyright} 140for more information). 141 142\subsection{Bugs} 143 144\ni 145Several, probably. 146If you find a bug and can eliminate it, send me a diff. If you find a bug 147and can't cope with it, send me a report, and wait for the next version. 148If you would like a feature, tell me. 149 150\subsection{Copyright} 151 152\noindent 153{\sc nightfall} is copyright (c) 1998-2008 Rainer Wichmann, (c) 2001-2002 154Markus Kuster, (c) 2001-2002 Patrick Risse 155\label{copyright} 156\\ 157 158\ni 159{\sc nightfall} is free software; you can redistribute it 160and/or modify 161it under the terms of the GNU General Public License as 162published by 163the Free Software Foundation; either version 2 of the License, or 164(at your option) any later version.\\ 165 166\ni 167{\sc nightfall} is distributed in the hope that it will be useful, 168but WITHOUT ANY WARRANTY; without even the implied warranty of 169MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 170GNU General Public License for more details.\\ 171 172\ni 173You should have received a copy of the GNU General Public License 174along with this program; if not, write to the Free Software 175Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. 176 177\ni 178This document is considered part of the {\sc nightfall} program. 179 180\newpage 181\begin{rawhtml} 182<HR> 183\end{rawhtml} 184 185\section{Requirements and Installation} 186 187\subsection{Requirements} 188 189\ni 190{\sc nightfall} has been developed with the aim of being able 191to compile and run the program on a typical Linux system without 192any need of downloading/installing additional libraries or programs. 193Although I have not tested this, {\sc nightfall} should compile 194on other Unix systems as well.\\ 195 196\ni 197For command line use/file output, all you need is a C compiler (e.g. gcc). 198For interactive use and plotting, {\sc nightfall} requires additional 199libraries/programs. {\bf Note:} for compiling a program (e.g. for compiling 200{\sc nightfall}), you need so-called 'development' packages of the required 201libraries. These 'development' packages are usually not 202installed by default.\\ 203 204\begin{itemize} 205 206 \item 207 {\bf For interactive use} of {\sc nightfall}, a GUI is provided, 208 which is based 209 on the GTK library (available at http://www.gtk.org, GNU Library General 210 Public License). GTK should compile on most Unix systems. 211 If you have a recent Linux distribution, GTK should 212 already be included (Ubuntu: libgtk2.0-0, libgtk2.0-dev). 213 To see whether GTK is installed, try to run 214 215 \$ gtk-config --libs 216 217 which should yield something like: '-L/usr/lib -L/usr/X11R6/lib -lgtk 218 -lgdk -lglib -lXext -lX11 -lm' (might be different for your system). 219 If you get a message like 'sh: gtk-config: not found', you might 220 need to install GTK. (On most Linux distributions, 221 GTK is split in two packages. 222 For running GTK applications, you need only the 'gtk' package. For compiling 223 applications (like {\sc nightfall}), you also need the 'gtk-dev' package. 224 Ubuntu package name: libgtk2.0-dev) 225 226 \item 227 {\bf For plots and graphs}, {\sc nightfall} requires either 228 229 \begin{itemize} 230 231 \item 232 {\sc GNUPLOT}, version 3.5 (pre 3.6) patchlevel beta 347, or higher 233 (Debian: gnuplot). 234 Earlier versions may or may not work. You need a version with 'multiplot' 235 support. To verify this, try: 236 237 \$ gnuplot\\ 238 gnuplot\$ set multiplot 239 240 If you get an error message, you have to update your GNUPLOT.\\ 241 You also need write permission to the directory '/tmp' on your system. 242 To test this, try: 243 244 \$ touch /tmp/foo 245 246 \item 247 or the {\sc PGPLOT} Fortran graphics subroutine library 248 (Debian: pgplot5, also available at: 249 250 http://astro.caltech.edu/~tjp/pgplot 251 252 free for non-commercial use). You need a Fortran compiler 253 (g77 is fine) to compile it. You have to compile it with 254 the Xserver and postscript drivers, and also have to compile 255 the C wrapper library that comes with {\sc PGPLOT}. 256 257 \end{itemize} 258 259 \item 260 {\bf For OpenGL support}, {\sc nightfall} requires 261 262 \begin{itemize} 263 264 \item 265 {\sc OpenGL} or {\sc MesaGL} (Ubuntu: libgl1-mesa-dev), 266 267 \item 268 {\sc GLUT}, the OpenGL Utility Toolkit 269 (Ubuntu: freeglut-dev), 270 271 \item 272 {\sc gtkglarea} (Ubuntu: libgtkgl2.0-dev), and 273 274 \item 275 {\sc libjpeg} (Ubuntu: libjpeg62-dev). 276 277 \end{itemize} 278 279 \item 280 For building a {\bf parallelized version}, {\sc nightfall} requires 281 a compiler which supports the {\bf OpenMP} standard. 282 OpenMP parallelization has been tested with gcc 4.4.5 on Ubuntu 10.10. 283 Only the mutual reflection is parallelized (it will consume most of the 284 CPU time).\\ 285 286 287 \item 288 If you have installed the Gnome Desktop on your system, {\sc nightfall} 289 will build with support for it. However, Gnome is {\it not} required 290 for {\sc nightfall} - it compiles just as well without Gnome. 291 292 293\end{itemize} 294 295\ni 296{\bf Note}: With GNUPLOT, plots are not that nice sometimes, but 297animated mode runs much smoother with GNUPLOT than with PGPLOT. 298GNUPLOT does not support 299incremental plotting and display of images, thus a few options are 300only available with PGPLOT. 301 302\newpage 303 304\subsection{Installation} 305 306\ni 307After downloading the source code, do:\\ 308 309\ni 310\$ gunzip -c nightfall-{\it (version number)}.tar.gz $|$ tar -xvf -\\ 311\$ cd nightfall-{\it (version number)}\\ 312\$ ./DoInstall.sh\\ 313 314\ni 315The 'DoInstall.sh' script will query you for some information (e.g. where 316to install the program), 317and then (optionally) build, test, and install the application. 318If you want to do it by hand, instead of './DoInstall.sh' run the following 319sequence of commands:\\ 320 321\ni 322\$ ./configure\\ 323\$ make\\ 324\$ make install\\ 325 326\ni 327If you want to use {\sc PGPLOT}, 'configure' might find it by itself; 328otherwise 329you might need the 'configure' option\\ 330'--with-pgplot-include=PFX' (where PFX should be the directory where 331the PGPLOT header file cpgplot.h is installed), and 332'--with-pgplot-lib=PFX' (where PFX should be the directory where the 333PGPLOT library files libpgplot.a, libcpgplot.a are installed).\\ 334 335\ni 336If you want to build a {\bf parallelized version}, you need 337the 'configure' option '--enable-openmp'.\\ 338 339\subsubsection{Install locations} 340 341By default, the binary is installed to /usr/local/bin, the 342data/help/configuration files to \\ 343/usr/local/share/nightfall. If you don't 344like this, use the 'configure' option 345'--prefix=/where/to/install', where '/where/to/install' will 346replace '/usr/local'. 347 348\subsection{Compile/configure problems} 349 350 If you want to use a different compiler, you can supply the 351 option CC=myCCompiler to {\tt configure} (and also F77=myFortranCompiler, 352 if you compile with PGPLOT). 353 354\begin{itemize} 355 356 \item Have gnuplot, but configure does not find it 357 358 \begin{itemize} 359 \item is gnuplot in your path ? 360 if no, update your PATH environment variable 361 362 \item does it support 'set multiplot' ? 363 ( start interactively by typing 'gnuplot', 364 then type 'set multiplot' to test) 365 if no, update your gnuplot 366 367 \item does 'gnuplot\_x11 -persist' work, or does it 368 give an error message like: 369 gnuplot: bad option: -persist ? 370 if error, update your gnuplot 371 372 \item There was at least one gnuplot version that 373 supports the required 'multiplot' option, but does not 374 list it as supported. 375 In this case, enforce gnuplot support with:\\ 376 {\tt ./configure --with-gnuplot} 377 \end{itemize} 378 379 380 \item Have gnuplot and pgplot, want gnuplot support 381 382 \begin{itemize} 383 \item use:\\ 384 {\tt ./configure --with-gnuplot} 385 \end{itemize} 386 387 \item Have pgplot, but configure does not find it 388 389 \begin{itemize} 390 \item do you have a fortran compiler (required) ? 391 392 \item the following files are required: 393 cpgplot.h, libcpgplot.a, libpgplot.a\\ 394 Use {\tt ./configure --with-pgplot-include=/my/pgplot/include/dir 395 --with-pgplot-lib=/my/pgplot/lib/dir}, \\ 396 where '/my/pgplot/include/dir' is the directory where 397 cpgplot.h is located, and '/my/pgplot/lib/dir' is the directory 398 where libcpgplot.a, libpgplot.a are located. 399 \end{itemize} 400 401 \item Have pgplot, get compile error 402 403 \begin{itemize} 404 \item maybe your fortran compiler does not understand the 405 link options required by Gtk. 406 upgrade to a recent version of g77. 407 408 \item maybe pgplot was compiled with a different fortran compiler. 409 Recompile it with the fortran compiler found by configure, or 410 convince configure to use a different compiler (use the 411 configure option F77=myFortranCompiler and/or CC=myCCompiler). 412 \end{itemize} 413 414 \item Other compile errors 415 416 \begin{itemize} 417 \item There might be problems related to internationalization, 418 that may be caused by a broken installation of a respective 419 utility on your system. 420 For solving this, you should choose one of the 421 following switches for the 'configure' script:\\ 422 {\tt --disable-nls}\\ 423 {\tt --with-included-gettext}\\ 424 like, e.g.: {\tt ./configure --with-included-gettext}\\ 425 The first switch will completely disable internationalization, 426 i.e. only the english version will be available. 427 The second switch will use the internationalization 428 program that is included in this source code distribution, 429 thus bypassing any preinstalled, maybe broken, utility on 430 your system. 431 \end{itemize} 432 433 434\end{itemize} 435 436 437\subsection{Compile-time configuration} 438 439\ni 440{\bf This section is targeted at researchers wanting to adjust 441{\sc nightfall} to their needs.} 442Several aspects/limits of {\sc nightfall} can be configured at 443compile time. Mostly, these are related to fixed array sizes. 444For most users, the defaults should be sufficient.\\ 445 446\ni 447To configure, edit the file 'Light.h' and change the default value(s) of 448the '\#define ITEM' statement(s) in the first section of this file 449(where 'ITEM' stands for any of the bold words on the list below). 450Configuration options include (but are not limited to): 451\begin{itemize} 452 453 \item NIGHTFALL\_PLOTFILE -- the name of the output plot file 454 (default is 'Nightfall.ps'). 455 456 \item STEPS\_PER\_PI, MAXELEMENTS -- the number of surface elements 457 for stars. This number cannot be set 458 exactly, as the algorithm determines it at run time, trying to 459 achieve a more or less constant area per surface element (for the 460 lightcurve computation, of course the exact surface area is taken 461 into account). You can, however, set the number of steps per 462 one Pi (= 180 degree) on the equator, which is 463 STEPS\_PER\_PI. 464 You also have to adjust 465 the size of the array holding the surface, which is 466 MAXELEMENTS. 467 468 \item MAXOBS -- the maximum number of observational data per filter 469 470 \item PHASESTEPS -- the maximum number of steps for a full orbit 471 472 \item N\_SPOT -- the maximum number of spots per star 473 474 \item GNU\_GEOMETRY -- the plot window geometry, if you use {\sc GNUPLOT} 475 as plotting program\\ 476 Please note: it is not possible to fully 477 specify the {\sc PGPLOT} plot window 478 geometry from within the program. 479 It can be defined (in pixels) by:\\ 480 X resource: pgxwin.Win.geometry: WIDTHxHEIGHT+X+Y\\ 481 or environment variable: PGPLOT\_XW\_WIDTH 482 [fractional display width].\\ 483 PGPLOTS's default is width=867, height=669 and aspect=8.5/11.\\ 484 If PGPLOT\_XW\_WIDTH is undefined, {\sc nightfall} will set 485 it to scale down the window width to the GNU\_GEOMETRY width.\\ 486 Set PGPLOT\_XW\_WIDTH to 1.0, if you don't like this\\ 487 (bash, ksh: 'PGPLOT\_XW\_WIDTH=1.0; export PGPLOT\_XW\_WIDTH' \\ 488 csh, tcsh: 'setenv PGPLOT\_XW\_WIDTH 1.0'). 489 490 \item OUT\_FILE, OUT\_SIMPLEX -- the names of output files for the 491 lightcurve (OUT\_FILE) 492 and eventual fit results (OUT\_SIMPLEX). 493 494 \item PROFILE\_ARRAY, PROFILE\_RES -- the size of the array for 495 line profile computation 496 (PROFILE\_ARRAY) and the default resolution 497 (PROFILE\_RES). 498 499\end{itemize} 500 501\newpage 502\begin{rawhtml} 503<HR> 504\end{rawhtml} 505 506\section{Usage} 507 508\subsection{Simplified 'educational' mode} 509 510\ni 511As of version 1.64, {\sc nightfall} supports a simplified 'educational' mode 512that is targeted at undergraduate lab settings. In this mode, {\sc nightfall} 513always starts in interactive mode, with a much simpler GUI stripped of 514almost all more or less advanced options. In additions, the sizes of the 515stars have to be specified in units of solar radii instead of fractions 516of the critical Roche volume (which allows to use {\sc nightfall} without 517having to explain the concept of the Roche volume).\\ 518 519\ni 520To start {\sc nightfall} in this mode, use the command line 521parameter '--edu', like:\\ 522 523\ni 524\$ nightfall --edu 525 526 527\subsection{General} 528 529\ni 530If used in interactive mode, only the command line parameter '-U' is 531required: 532 533\ni 534\$ nightfall -U\\ 535 536\ni 537If used in non-interactive mode, unless a configuration file is 538read in at startup 539(see 540\hyperref 541 {info on configuration files} 542 {Section\ } 543 {} 544 {config}), 545{\sc nightfall} requires at least the following six numerical arguments on the 546command line (in that order): 547 548\begin{itemize} 549 550 \item 551 (1) the mass ratio of both stars 552 (mass(Secondary)/mass(Primary), allowed range 0.0001 -- 10000.0. 553 For Roche lobe fill 554 factors (see below) above one, the mass ratio is restricted to 555 0.003 - 50. 556 557 558 559 \item 560 (2) orbital inclination ( = viewing angle of orbital plane, 561 range 0 -- 90 degree), where 0 deg corresponds to face-on view (no eclipse 562 possible), and 90 deg to edge-on view (eclipse guaranteed). For 563 angles in between, the occurence of an eclipse depends on the mass 564 ratio and the Roche fill factors (see below). 565 566 \item 567 (3,4) Roche lobe fill factors. The {\it Roche lobe} is the maximum 568 volume a star can fill in a binary system. Its size is, in general, 569 different for the two stars, and depends on the mass ratio (see 570 \hyperref 571 {details on 'Roche lobe'} 572 {Section\ } 573 {} 574 {roche} 575 for an explanation). The Roche lobe fill factor 576 is in units of the polar radius of the {\it Roche lobe}. 577 The allowed range is 0.001 -- 1.3. For values above 1.0, both stars 578 merge into a {\it common envelope/overcontact} system. 579 580 \item 581 (5,6) surface temperatures of both stars 582 (in Kelvin, range 350 -- 350000; Kelvin = degree Celsius + 273.15). 583 Just for comparison, the surface temperature of the sun is 5780 K. 584 If you use the 'model atmosphere' option, the minimum temperature is 585 2000\,K, the maximum temperature is 31000\,K 586 (for surface gravity $\log{g} = 3.5$), 39000\,K ($\log{g} = 4.0$), and 587 49000\,K ($\log{g} = 4.5, 5.0$) 588 589 590\end{itemize} 591 592\ni 593{\bf These six numerical arguments are always required, if 594{\sc nightfall} is used in command-line (i.e. non-interactive) mode 595without reading in a configuration file} (see below)\\ 596 597 598\ni 599\$ nightfall -U -C ty\_boo.cfg\\ 600 601\ni 602will read parameters from a configuration file and start {\sc nightfall} 603in interactive mode. The configuration file is a simple text file 604that can be edited by hand. In interactive mode, you can also 605write out the current parameters to a configuration file.\\ 606 607\noindent 608\$ nightfall (without arguments) will produce a full list of options (many).\\ 609 610\ni 611{\bf By default, {\sc nightfall} will do nothing more than 612 run in non-interactive mode, compute 613 the lightcurve, write it to an output file 'NightfallCurve.dat', 614 and exit silently. If you want more (nifty plots, etc.), read on.} 615 616\subsection{Plotting, Graphics} 617 618\ni 619requires that {\sc nightfall} has been 620compiled with support for PGPLOT or Gnuplot. 621 622\ni 623In interactive mode, there are several menu options available to produce plots. 624In non-interactive (command-line) mode, you can choose from the following: 625 626\begin{itemize} 627 628\item For a real-time animation of the two stars orbiting each other, use 629 {\bf -A} 630 631\item To select plotting of the output light curve, use {\bf -G} 632 633\item To select the filter for the plottted lightcurve, use {\bf -Bfilter} 634 where 'filter'is one of UBVRIJHKuvby (see 635 \hyperref 636 {details on filters} 637 {Section\ } 638 {} 639 {filter}) 640 641\item To visualize the geometry, use {\bf -V}.\\ 642 There are four sub-options (-Va, -Vi, -Vc, -Vv): 643 \begin{itemize} 644 \item -Vc for a contour plot of the potential, 645 \item -Vi for an image of the potential, 646 \item -Vv for viewing the stars, 647 \item -Va for all in one plot. 648 \end{itemize} 649 The default is 'c'. Only 650 'c' and 'v' are supported by {\sc GNUPLOT} 651 ({\sc GNUPLOT} cannot display images). 652 653\item To obtain a hardcopy, use {\bf -H}. 654\end{itemize} 655 656\ni 657{\it Detailed output is always written to a file 'NightfallCurve.dat'.} 658 659 660\subsection{Interactive usage - the graphical user interface (GUI)} 661 662\ni 663Use command line option {\bf -U} to choose this option. 664A GUI will (hopefully) come up.\\ 665 666\ni 667In the menu bar, there is a {\bf File} menu for 668reading data/configuration files. 669Please note that you need to reset the data memory {\bf [Reset Memory]} 670before reading in data for another binary, otherwise you will end up 671in a mess ...\\ 672The {\bf Output} menu allows to choose between several facilities for 673viewing the output of a computation and visualizing the binary system. 674Some of them allow interactive change of parameters like viewing angle etc. 675Please read the online help for more details.\\ 676 677\noindent 678In the toolbar below, 679there are buttons for computing a lightcurve {\bf [Compute]}, 680toggling animated view of the binary {\bf [Animate]} while computing, 681writing out the current binary configuration {\bf [Write]}, 682and getting help on the currently active notebook page {\bf [Context]}.\\ 683 684\noindent 685The rest of the GUI is layed out as a 'notebook' with several 686different pages for setting options: 687 688\begin{itemize} 689 690 \item 691 {\bf Basic} Here you can define the basic configuration of the 692 binary - mass ratio, inclination, fill-out ratios and temperatures. 693 I know, reading manuals is not much fun, but you should read at least 694 \hyperref 695 {the basic introduction} 696 {Section\ } 697 {} 698 {basic} 699 to know what's going on. Use animated mode 700 for 'learning by doing'. 701 702 \item 703 {\bf Disk} For defining the parameters of an optional accretion disk. See 704 See 705 \hyperref 706 {'Disk'.} 707 {Section\ } 708 {.} 709 {disk} 710 711 \item 712 {\bf Advanced} For advanced options like asyncroneous rotation, 713 non-circular orbit, etc. See 714 \hyperref 715 {'Advanced Options'.} 716 {Section\ } 717 {.} 718 {advanced} 719 720 \item 721 {\bf Plot Options} for the selection of output filter 722 (see 723 \hyperref 724 {details on filters} 725 {Section\ } 726 {} 727 {filter}), 728 and plot window for lightcurve, as well 729 as options for geometry visualization.\\ 730 If compiled with OpenGL support, you can also switch on/off 731 OpenGL viewing mode here. 732 733 \item 734 {\bf Data Fitting} Computation of best-fit parameters. 735 Also: definition of absolute system parameters (for radial velocity). 736 See 737 \hyperref 738 {details on data fitting.} 739 {Section\ } 740 {.} 741 {fitting} 742 743 \item 744 {\bf Spots} Here you can interactively define up to two spots per star 745 (additional spots can be defined on the command line or in a 746 configuration file). Both spots can be switched on/off independently. 747 See 748 \hyperref 749 {details on surface spots.} 750 {Section\ } 751 {.} 752 {spotted} 753 754 \item 755 {\bf Third Light} For definition of the brightness of an (eventual) 756 third star in the system. Third Light is just added to 757 the total brightness, 758 never eclipsed, i.e. it only has an effect on the relative depth 759 of the eclipses. See 760 \hyperref 761 {the section on third light.} 762 {Section\ } 763 {.} 764 {third} 765 766\end{itemize} 767 768\ni 769On the bottom of the GUI, there is a status/progress bar. 770 771\subsection{OpenGL} 772 773\ni 774{\bf Note} that OpenGL can lead to program crashes with some graphic cards. 775 776\ni 777If compiled with OpenGL support, the animated display will by default 778run in OpenGL mode. You can switch to {\sc GNUPLOT}/{\sc PGPLOT} mode 779in the PlotOptions page in the GUI. In OpenGL 780mode, you have the following options: 781 782\begin{itemize} 783 \item {\bf Zoom} by clicking into the display area and drag with the 784 middle mouse button. 785 786 \item {\bf Change viewpoint} by clicking into the display area 787 and drag with the 788 left mouse button. 789 790 \item {\bf Reset} with the space bar. 791 792 \item {\bf Save animation} as JPEG images with File->Save animation 793 794 \item {\bf Edit preferences} with Edit->Preferences. 795 \begin{itemize} 796 \item You can switch 797 between wireframe, solid, and points display. 798 \item For solid mode, you 799 can switch on textures, and choose different texture types. 800 \item You can switch on/off the display of labels and axes. 801 \end{itemize} 802 803 \item The following keybindings are available in the OpenGL window:\\ 804 \begin{tabbing} 805 right arrow \= zoom out\\ 806 left arrow \> zoom in\\ 807 space \> reset to real observer viewpoint\\ 808 f \> switch to 'points' display mode\\ 809 l \> switch to 'wireframe' display mode\\ 810 o \> switch to 'opaque' display mode\\ 811 t \> toggle textures on/off\\ 812 w \> cycle through texture type \\ 813 \> (image/temperature/gravity/flux/velocity)\\ 814 p \> toggle primary texture on/off\\ 815 s \> toggle secondary texture on/off\\ 816 a \> toggle axes on/off\\ 817 m \> toggle movie mode on/off\\ 818 \end{tabbing} 819 820\end{itemize} 821 822\ni 823With textures enabled, the default is to use a pixmap as texture. All 824other textures display the variation of physical quantities 825(caused by the non-spherical shape and/or limb darkening) 826across the stellar surface. Available choices are: surface temperature, 827surface gravity, flux {\it towards the observer}, and the velocity of surface 828elements {\it towards the observer} relative to the star's centre of mass. 829 830\subsection{Parallelization} 831 832\ni 833Internally, if compiled with {\bf --enable-openmp}, nightfall will run the 834computation of mutual reflection in parallel, using as many threads as there 835are cores on the host unless the environment variable OMP\_NUM\_THREADS 836is set.\\ 837 838\ni 839In addition, it is possible to distribute the workload of an optimization 840run across several hosts. This requires that you can login via ssh to 841those hosts, without using a password (e.g. by using a RSA/DSA key and 842ssh-agent).\\ 843 844\ni 845In order to make use of the latter option, you need to have a file 846{\tt parallel.cfg} in your current working directory (the one from which 847you are starting {\sc nightfall}, with one line per host. The format 848of valid lines is:\\ 849HOST hostname maximum\_number\_of\_instances\\ 850 851\ni 852I.e. the line starts with the keyword HOST, followed by the hostname, followed 853by a number which is the maximum 854number of {\sc nightfall} instances to run on that host. E.g.:\\ 855 856\ni {\tt 857HOST host1 5\\ 858HOST host2 5\\ 859HOST host3 2\\ 860}\\ 861 862\ni 863Furthermore, 864\begin{itemize} 865 \item you {\bf must} invoke {\sc nightfall} with an absolute path (i.e. 866 starting with an '/'), 867 \item and this will be the pathname used to invoke {\sc nightfall} on 868 the remote machines, so it must be identical there, 869 \item the path to the data file(s) holding observed light and/or radial 870 velocity curves must be an absolute path that is identical on all hosts, 871 \item any file used (data or configuration file) must be specified with 872 an absolute path, and 873 \item no whitespace is allowed in those paths (or in the pathname of the 874 {\sc nightfall} executable. 875\end{itemize} 876So basically, you need to make sure that {\tt /path/to/nightfall [options]} will 877work if executed in your home directory when you ssh into the remote machine.\\ 878 879\ni 880Note that for the simplex fitting routine, the maximum number of instances 881spawned is equal to the number of free parameters (this would happen when 882the simplex shrinks towards the best solution and all vertices except the best 883are recomputed). For the simulated annealing global optimization, the 884first sweep will spawn at most 100 instances, while all subsequent sweeps 885will spawn 5 instances. 886 887\subsection{Problems} 888 889\begin{itemize} 890 891 \item OpenGL can lead to program crashes with some graphic cards. 892 893 \item Overcontact systems are not displayed correctly with OpenGL. 894 895 \item The {\sc Gnuplot} PS-driver apparently does not support 896 the 'multiplot' option. 897 898 \item For eccentric (non-circular) orbits, very small fill factors 899 produce strong numerical artifacts in the light curve. 900 901 \item There seem to be some numerical artifacts also in the line 902 profiles sometimes, preferentially at quadrature. 903 904\end{itemize} 905 906 907\newpage 908\begin{rawhtml} 909<HR> 910\end{rawhtml} 911 912 913 914\subsection{Configuration File} 915 916\ni 917{\sc nightfall} comes with a set of configuration files, each of which 918will set the system parameters for a particular (real) binary system, 919and automatically load some data files with observed data for 920this particular binary star (see next section).\label{config}\\ 921 922\ni 923For the file format, see the commented example file 'ty\_boo.cfg' 924in the source code distribution. To read in such a file, on the 925command line use:\\ 926 927{\bf -C path/to/config/file}\\ 928 929\ni 930If you don't give the full path, 931{\sc Nightfall} will search (in this order of priority) the present working 932directory, an eventual subdirectory './cfg', and the default 933data directory set at compile time. If the configuration file is in one 934of these, only the name, not the full path is required.\\ 935 936 937\subsection{Data files} 938 939\ni 940{\sc nightfall} comes with a set of sample observational data for several 941different eclipsing binaries. For each included binary system, the data 942comprise lightcurves in several filters, as well as radial velocity curves. 943Also, for each of these systems there is a configuration file 944(see 945 \hyperref 946 {details on configuration files} 947 {Section\ } 948 {} 949 {config}). 950Loading this configuration file will set the 951appropriate parameters for that particular system, and also read in the data. 952You can then compute the lightcurve and visualize the binary, with the 953observed data overlayed on the lightcurve. \\ 954 955\ni 956E.g. you might call {\sc nightfall} 957as 'nightfall -U -C data/ty\_boo.cfg', then press 'ANIMATE' to switch 958on the real-time animation, and press 'COMPUTE' to compute the 959lightcurve. With 'PlotCurve' you can then get a plot of the final lightcurve, 960with the data overlayed.\\ 961 962\ni 963Of course, you can also experiment by yourself and try to fit the 964lightcurve by varying the system parameters, or use the automatic 965fitting option.\\ 966 967\ni 968To read in a single data file, use\\ 969 970{\bf -I path/to/data/file}.\\ 971 972\ni 973If you don't give the full path, 974{\sc Nightfall} will search (in this order) the present working 975directory, an eventual subdirectory './data', and the default 976data directory set at compile time. If the data file is in one 977of these, only the name, not the full path is required. 978For details on the format of the files, see 979 \hyperref 980 {here.} 981 {Section\ } 982 {.} 983 {dataread} 984 985\ni 986Data are available for the following systems: 987 988\begin{itemize} 989 990 \item 991 {\bf TY Boo:} a 'common-envelope' ('overcontact') system with two 992 cool stars. This is a so-called 'shallow' overcontact system, as 993 the stars are only slightly overfilling their Roche lobes (for the 994 explanation of the term 'Roche lobe' see 995 \hyperref 996 {here.} 997 {Section\ } 998 {).} 999 {roche} 1000 The two 1001 stars have slightly different temperatures. 1002 1003 \item 1004 {\bf MR Cyg:} a semi-detached system (the cooler fills its Roche lobe) 1005 with two stars of very different temperature (but both much hotter 1006 than the Sun). Lightcurve should be 1007 computed with some advanved options: model atmosphere fluxes, 1008 detailed reflection (2-3 iterations), quadratic limb darkening. 1009 1010 \item 1011 {\bf DD Mon:} another semi-detached system (the cooler star fills its 1012 Roche lobe). The cooler star is slightly cooler than the Sun, the other one 1013 slightly hotter than the Sun. The total mass is very low -- both stars 1014 together have only about 0.6 solar masses. It seems difficult to 1015 fit the lightcurve without spots (did not try as yet). 1016 1017 \item 1018 {\bf BH Vir:} a detached system with two stars, one slightly hotter, 1019 the other slightly cooler than the Sun. At least one of the stars 1020 has surface spots, which cause a slight, but noticeable distotion 1021 of the lightcurve. The config file includes two spots on the cooler star. 1022 The BV lightcurves and the uvby lightcurves are 1023 from different years. As the stars exhibit some variability, you might want 1024 to use either the BV or the uvby lightcurves, 1025 but not all six simultaneously. 1026 1027 \item 1028 {\bf LZ Cen:} a detached, but near-contact system with two rather 1029 similar stars, both very hot. The stars are rotating very slightly faster 1030 than synchroneously. Lightcurve should be 1031 computed with some advanved options: model atmosphere fluxes, 1032 detailed reflection (2-3 iterations), quadratic limb darkening. 1033 1034 \item 1035 {\bf ER Vul:} a detached system of two stars that are both slightly 1036 hotter than the sun, and also have masses only slightly higher than 1037 the sun. The stars show strong and variable activity, i.e. 1038 large starspots that are varying with time. Thus the derived parameters 1039 of the spots can vary a lot from one observation to the next. 1040 1041 \item 1042 {\bf V541 Cyg:} a well-detached (i.e. wide) binary system with an 1043 eccentric (i.e. non-circular) orbit. As the binary is very wide, the 1044 eclipses are narrow, and it is {\bf important} to set the number of 1045 steps for the lightcurve to a high value (say, 600, instead of the 1046 default of 80) in order to resolve the eclipses. 1047 1048 \item 1049 {\bf 51 Peg:} an extrasolar planetary system. Only the radial velocity 1050 curve of the primary is known, thus for the planet only the product 1051 $m \times \sin(i)$ is known (0.45 Jupiter masses). Depending on the 1052 unknown inclination angle, the mass may be as high as 15 Jupiter masses, 1053 while higher masses are probably ruled out, because a higher-mass 1054 companion would have synchronized the primary, which is not the case 1055 (the rotation period of 51 Peg is 29-37 days, while the 1056 orbital period of the planet is 4.23 days). The model assumes an inclination 1057 angle of 25 deg, and a density similar to Jupiter's for the planet. The 1058 parameters of the star (mass, radius, temperature) are well known; the 1059 temperature of the planet can be calculated from its distance to the star. 1060 No eclipses (by the planet) have been observed, but the amplitude would be 1061 at the limit of even the most sensitive measurements. 1062 1063\end{itemize} 1064 1065 1066\subsection{Environment variables} 1067 1068\noindent 1069The run-time behaviour of the program can be modified by the value of 1070some {\it environment variables}. To set an {\it environment variable} 1071to some value, depending on your shell the following command is required:\\ 1072 1073in csh, tcsh: {\tt setenv VARIABLE=value}\\ 1074 1075in sh, bash: {\tt VARIABLE=value; export VARIABLE}\\ 1076 1077 1078\begin{itemize} 1079 1080 \item 1081 {\bf HOME} your home directory, usually automatically set by your shell 1082 1083 \item 1084 {\bf TEMPDIR or TMPDIR} location for temporary files 1085 (should not be on NFS mounted filesystem). If these variables are not set, 1086 {\sc nightfall} will use /tmp as default. 1087 1088 \item 1089 {\bf LANGUAGE or LC\_ALL or LC\_MESSAGES or LANG} (in this order of priority) 1090 will be used to determine your language. The default is English. At the 1091 time of this writing, the only other supported language is German 1092 (LANG=de). 1093 1094 \item 1095 {\bf NIGHTFALL\_DATAROOT} the root directory to search for the data/, cfg/, 1096 and doc/ subdirectories (containing data, config, and help files, 1097 respectively). Only needed if this directory has been moved after 1098 installation. 1099 1100 \item 1101 {\bf NIGHTFALL\_DATA\_DIR} the directory where data are located. Only needed 1102 if these have been moved after installation, and {\bf NIGHTFALL\_DATAROOT} 1103 is not set or data are not in {\bf \$NIGHTFALL\_DATAROOT}/data. 1104 1105 \item 1106 {\bf NIGHTFALL\_CFG\_DIR} for location of config files. 1107 See {\bf NIGHTFALL\_DATA\_DIR}. 1108 1109 \item 1110 {\bf NIGHTFALL\_DOC\_DIR} for location of help files. 1111 See {\bf NIGHTFALL\_DATA\_DIR}. 1112 1113 \item 1114 {\bf NIGHTFALL\_LOCALE\_DIR} for location of data for 1115 localization. Only important if you use internationalization to 1116 support your language. See {\bf NIGHTFALL\_DATA\_DIR}. 1117 1118 \item 1119 {\bf NIGHTFALL\_PLOTFILE} the name of the output file for plots. Default 1120 is nightfall.ps. 1121 1122 \item {\bf GNUPLOT\_GEOMETRY} the window size for gnuplot. Default is 1123 550x424+300+20. 1124 1125 \item {\bf PGPLOT\_XW\_WIDTH} fractional display width for PGPLOT X window. 1126 1127 \item {\bf NIGHTFALL\_RADIATIVE} limiting upper temperature for stars with 1128 convective envelope (default is 7700; unit is Kelvin). Above 1129 that temperature the envelope will be considered radiative. The only 1130 effect this has to to switch the albedo from 0.5 (below) to 1.0 (above). 1131 1132 \item {\bf NIGHTFALL\_SMAP\_PATH} base path to the surface map. To this, 1133 the index for the bandpass and the 1134 current phase will be appended. No surface map 1135 will be output if this environment variable is not set. 1136 1137 \item {\bf NIGHTFALL\_SMAP\_BAND} bandpass (0..11 for UBVRIJHKuvby) for 1138 which surface map is output. 1139 1140 \item {\bf NIGHTFALL\_MONO\_WAVE} a comma-delimited list of up to twelve 1141 monochromatic wavelengths (unit: micrometer) 1142 to replace the effective wavelengths for the 1143 blackbody approximation. 1144 1145\end{itemize} 1146 1147\newpage 1148\begin{rawhtml} 1149<HR> 1150\end{rawhtml} 1151 1152\section{Introduction to Binary Stars} 1153 1154\noindent 1155This section (and the next) provide(s) an introduction 1156to the problem (at a popular science \label{basic} 1157level, hopefully), the options, and the algorithm(s) used. More technical 1158aspects are in italics. If you find the less technical part too arcane, 1159feel free to supply (constructive) suggestions. 1160 1161 1162\subsection{The Roche Geometry} 1163 1164\noindent 1165Imagine two lakes, seperated by a ridge. There are about three possible 1166configurations: \label{roche} 1167 1168\begin{itemize} 1169 \item In both lakes, the water level is well below the level of the ridge. 1170 This is a {\bf detached system}. 1171 1172 \item One of the lakes reaches up to the lowest point of the ridge, and water 1173 may spill over to the other lake. 1174 This is a {\bf semi-detached system}. 1175 1176 \item Both lakes overflow the ridge and form one single lake. 1177 This is a {\bf contact\,/\,overcontact system}. 1178 1179\end{itemize} 1180 1181\ni 1182Replace 'water' by 'gas', 'lake' by 'star', and you have the possible 1183configurations of a close binary star system.\\ 1184 1185\noindent 1186The stellar shapes in such a system are given by the sum of the 1187gravitational forces, and the centrifugal force due to the orbital motion. 1188Instead of using the forces, it is easier to use a {\bf potential} (forces 1189can then be expressed as the derivative of the potential, if needed). 1190In the case of binary stars, this potential is called 1191the {\bf Roche potential}, named after the French mathematician 1192Edouard Albert Roche (1820-1883). 1193The stellar surface is then given by an {\bf equipotential surface} 1194(a surface, on which the potential is constant). 1195Thus, the introduction of the potential makes 1196the computation of any forces superfluous in this particular application.\\ 1197 1198\noindent 1199The largest size a single star can have in a binary system is given by the 1200{\bf Roche lobe} - a teardrop-shaped equipotential surface, 1201whose cusp touches the cusp of the 1202Roche lobe of the other star at a point called {\bf Lagrange 1 (L1)} 1203(there are four more Lagrange points, which are of less interest here). 1204L1 is located between both stars, on the line connecting their centres. 1205At L1, the sum the forces is zero, thus, if a star fills its Roche lobe, at L1 1206matter can flow into the Roche lobe of the other star (provided it is not 1207filled as well). \\ 1208 1209\noindent 1210Thus, L1 would correspond to 'lowest point of the ridge' in the two-lake 1211example above, and the Roche lobes would correspond to the two valleys below 1212that point, that potentially can be filled by the two lakes. But just as 1213the two lakes in the example above may be smaller than their 1214maximum size (before flowing together), also the stars in a binary system 1215may be smaller than their respective Roche lobes. 1216A star that completely fills its Roche lobe will assume 1217its teardrop-like shape. A star filling only a small fraction of its Roche lobe 1218will be more spherical - distortion increases with the {\bf Roche lobe filling 1219factor}.\\ 1220 1221\ni 1222Note that the {\it relative} size of the Roche lobe of the two stars 1223in the system depends on their mass ratio. The {\it absolute} size of the 1224Roche lobe also scales with the separation of the two stars. 1225Thus, with a fixed mass ratio and fixed absolute sizes of the stars (e.g. 1226in kilometers), a star may fill its Roche lobe (and have a highly distorted 1227figure), if the stars are rather close, 1228but the same star might fill just a tiny fraction of its Roche lobe 1229(and thus would be nearly spherical) if the binary separation 1230would be rather large. \\ 1231 1232\ni 1233To define the sizes of stars in {\sc nightfall}, you have to 1234give the 'Roche lobe filling factor', which is defined in units of the 1235Roche lobe (actually, its polar radius). 1236{\sc nightfall} uses a dimensionless potential, i.e. the distance between 1237both stars is arbitrarily set to unity. 1238Thus, for a fixed absolute size of the stars, decreasing the 1239'Roche lobe filling factor' would be equivalent to increasing the 1240distance. 1241 1242\subsection{Shape of the lightcurve} 1243 1244The shape of the lightcurve depends mainly on three factors: 1245\begin{itemize} 1246 1247 \item temperatures - as the eclipsed areas are equal for the eclipse of 1248 the Primary and the eclipse of the Secondary, the depths of the 1249 eclipses are only different if the temperatures of both stars 1250 differ. See 1251 \hyperref 1252 {here} 1253 {Section\ } 1254 {} 1255 {norm} 1256 for details on temperature and 1257 brightness. 1258 1259 \item relative sizes and shapes of the stars, which are determined 1260 by the mass ratio (that determines the relative sizes of both 1261 Roche lobes) and the Roche lobe filling factors 1262 (see 1263 \hyperref 1264 {the info on 'Roche lobe'} 1265 {Section\ } 1266 {} 1267 {roche}). 1268 1269 \item temperature distribution on the stellar surface. If the Roche lobe 1270 filling factor is large, the star is very nonspherical, and its 1271 temperature can vary significantly over its surface. This effect 1272 is known as gravity brightening (see 1273 \hyperref 1274 {details on gravity brightening} 1275 {Section\ } 1276 {} 1277 {gravbright}). 1278 The result is that the lightcurve varies strongly, even if there 1279 is no eclipse. 1280 1281 \item mutual irradiation of both stars (see 1282 \hyperref 1283 {details on reflection treatment} 1284 {Section\ } 1285 {} 1286 {reflect}). 1287 1288 \item cool/hot surface spots (like sunspots, but can be much larger 1289 in some stars, see 1290 \hyperref 1291 {details on surface spots} 1292 {Section\ } 1293 {).} 1294 {spotted} 1295 1296\end{itemize} 1297 1298\subsection{Suggested experiments} 1299 1300\begin{itemize} 1301 1302 \item to begin, set the mass ratio to 1.0, 1303 both stars to equal fill factor and 1304 both temperatures to equal values. You will find that 1305 both eclipses have the same depth, as the eclipsed areas 1306 are equal (and have the same limb darkening). 1307 1308 \item as soon as one star is hotter than the other, the depth of 1309 the eclipses will become different. 1310 1311 \item the width of the eclipses depends on the sizes of the stars 1312 1313 \item the 'textbook' case of a flat lightcurve between eclipses 1314 is very rare. The reason is that due to the aspherical shape of 1315 stars in close binary systems, the visible surface area 1316 of the star varies during the orbit. Also, this aspherical shape 1317 causes strong temperature 1318 (= brightness) variations over the surface of the star 1319 an effect called 'gravity brightening' (or 'gravity darkening'). 1320 For more details, see 1321 \hyperref 1322 {here} 1323 {Section\ } 1324 {.} 1325 {gravbright} 1326 You will see that the lightcurve only becomes flat between 1327 eclipses if the Roche lobe fill factors (and thus the 1328 aspherical distortions) of the stars are very small. Which 1329 means that the distance of the two stars is large compared 1330 to their sizes, and 1331 an eclipse con only be observed if the orbital inclination 1332 is very close to 90 degrees - a rather rare case. 1333 1334 \item on the other hand, the aspherical shape of the stars 1335 can cause deep throughs in the lightcurve 1336 even if there is no eclipse at all ! To see this, 1337 set the mass ratio to 0.9, the Primary fill factor to 1.0, 1338 the Secondary fill factor to 0.1, and the inclination to 1339 40 degree (just as an example). 1340 In animated mode, you can verify that there is 1341 no eclipse at all, but still you see 1342 deep throughs in the light curve. 1343 1344 \item the 'bottom' of an eclipse only becomes (more or less) flat 1345 if the star is eclipsed for a prolonged time, i.e. if it is 1346 significantly smaller than the other, eclipsing star. 1347 1348 \item in an eccentric (non-circular) orbit, the velocity of the stars 1349 is not constant. Thus, also the width of both eclipses may be 1350 different, and the times between them as well 1351 (see 1352 \hyperref 1353 {details on eccentric orbits} 1354 {Section\ } 1355 {).} 1356 {eccentric} 1357 There is a config file 1358 'v541\_cyg.cfg' for the binary system V541 Cygni, which 1359 shows both effects. 1360 1361 \item the shape of the stars can vary a lot in an eccentric orbit, 1362 because the varying distance is equivalent to a varying Roche 1363 lobe filling factor. To demonstrate this, set the mass ratio 1364 to 1.0, and both Roche lobe filling factors to 1.0. Set 1365 the eccentricity to a large value (say, 0.6), and the orbital 1366 inclination to 0.0, to see what's going on (don't forget to 1367 switch on 'eccentric orbit', if you are in interactive mode). 1368 Use animated mode and enjoy. 1369 1370\end{itemize} 1371 1372\newpage 1373\begin{rawhtml} 1374<HR> 1375\end{rawhtml} 1376 1377\section{More details} 1378 1379\subsection{Which star is which ?} 1380 1381\noindent 1382Stars in binary systems are labelled 'Primary' and 'Secondary'. 1383In {\sc nightfall}, the star called 'Primary' is the star which 1384is {\it eclipsing} first, i.e. 1385the star that passes {\it in front} of the other one at 1386orbital phase zero (orbital phase indicates the position of the stars 1387in the orbit on a scale from zero to one). The secondary is the star that 1388is {\it eclipsed} first. In animated view, at start the Primary is left, 1389the Secondary right. Note that this labelling of 'Primary' and 'Secondary' 1390is inverse to the usual 1391convention ... mea culpa. Maybe I fix it sometime.\\ 1392 1393\noindent 1394To exchange the stars (if needed), you can either (i) swap the eclipses 1395in your data, or (ii) swap the stars themselves.\\ 1396For (i), add half an orbital period to the phase zeropoint in your datafile 1397(for a circular orbit), or the time lag of the second eclipse (for an eccentric 1398orbit).\\ 1399For (ii), swap temperatures and Roche lobe fill factors, and replace the 1400mass ratio q by 1/q. Don't forget to swap spots, if you have. For an 1401eccentric orbit, add or subtract 180 deg to/from the Periastron length.\\ 1402 1403\noindent 1404For a circular orbit, {\sc nightfall} 1405starts at orbital phase -0.25 -- which is identical to +0.75 --, 1406and calculates up to +0.75. 1407In a circular orbit, eclipses are at orbital phase 0.0 and 0.5.).\\ 1408 1409\noindent 1410{\sc nightfall} uses a dimensionless potential, i.e. the distance between 1411both stars is arbitrarily set to unity. 1412The relative size of both Roche lobes then depends 1413only on the mass ratio of both stars. The size of both stars has to be 1414given as a fraction of the Roche lobe (actually, its polar radius). 1415This fraction might be larger than one, if you want to specify an overcontact 1416system. To specify a semi-detached system, set the Roche lobe filling fraction 1417to 1.0 for one star, less for the other.\\ 1418 1419 1420\subsection{How is eclipse testing done ?} 1421 1422\noindent 1423{\sc nightfall} divides each stellar surface into a grid of a few thousand 1424elements. Eclipse testing is done by checking - for each surface element 1425individually- whether the line of sight towards that surface element 1426intersects the other star. For overcontact systems, a star might eclipse 1427its own throat region 1428(the region connecting both stars). This condition is tested as well. 1429 1430\noindent 1431Although simple tests based on orbital phase or intersection of sperical 1432regions suffice in most cases, still sometimes a rigorous and expensive 1433test is needed. \\ 1434 1435 1436\subsection{Temperature and Brightness} 1437 1438\noindent 1439Stellar \label{norm} surface temperatures can range from a 1440few 1000 Kelvin to several 144110000 Kelvin. The respective brightness can be calculated 1442from the so-called blackbody law (a blackbody is an idealized thermal 1443radiation source). The blackbody law is applicable to thermal radiation, 1444such as infrared radiation of your own body, or radiation by stars; it is 1445not applicable to non-thermal radiation sources like lasers.\\ 1446 1447\noindent 1448By default, {\sc nightfall} uses the blackbody law, which is neither terribly 1449good nor terribly bad. It is possible to use, instead, light fluxes 1450from detailed numerical computations of stellar atmospheres. Contrary 1451to blackbody fluxes, these model atmosphere fluxes (like real stellar fluxes) 1452depend not only on temperature, but also (mildly) 1453on surface gravity, and on the chemical composition of the stellar atmosphere. 1454As actual atmosphere calculations 1455would be prohibitively expensive, model atmosphere fluxes are taken from 1456tables that cover only a limited range in temperature (3000 K to 35000 K). 1457Tables are hardcoded, and only available for one surface gravity value 1458(a compromise value that should be ok for most cases), and solar 1459chemical composition. \\ 1460 1461\ni 1462To switch on model atmosphere fluxes, use \\ 1463 1464{\bf -M} 1465 1466\subsection{Output Lightcurves} 1467 1468\noindent 1469Lightcurves are \label{filter} output in eight commonly 1470used broad-band filters (UBVRIJHK from 1471near-UV to near-infrared), 1472and four narrow-band filters (Stroemgren uvby). The shape of the lightcurve 1473depends on the filter passband. \\ 1474 1475\noindent 1476The human eye itself also is not equally sensitive to all wavelengths 1477of light -- it also is a kind of 'filter' for light. To create a lightcurve 1478that looks like the human eye would see it, you have to choose an output 1479filter that matches as close as possible the sensitivity of the human 1480eye. For broadband filters, the V filter gives the best match to the human 1481eye. In the Stroemgren filter system, you might want to choose Stroemgren v.\\ 1482 1483 1484\noindent 1485Lightcurves are output in {\bf magnitudes}. 1486This is a relative unit commonly used in astronomy, 1487and defined as \[ m_1 - m_2 = -2.5 \times \log{\frac{flux_1}{flux_2}}. \] 1488(For magnitude differences smaller than about 0.4, the difference 1489in magnitude times 100 is nearly equal to the percentage difference in flux, 1490i.e. 0.1 mag is about 10 per cent difference.) 1491The brighter an object, the smaller its magnitude (Sun is -26.7 in the 1492V filter, while the faintest stars visible by naked eye are about +6). 1493{\sc nightfall} uses the brightness at quadrature (phase -0.25 in a circular 1494orbit, both stars fully visible) as 1495normalization (i.e. as $flux_2$ in the equation above).\\ 1496 1497\noindent 1498{\bf Output} goes to a file 'NightfallCurve.dat'. 1499To select plotting of output light curve, use \\ 1500 1501{\bf -G}\\ 1502 1503\noindent 1504To select the filter for the plotted lightcurve, use\\ 1505 1506{\bf -Bfilter},\\ 1507 1508\ni 1509where {\bf filter} should be one of UBVRIJHKuvby. The default for plotting 1510is the V filter, which is the best match to the human eye. If you read in 1511data files with observed lightcurves (see 1512 \hyperref 1513 {here for more info} 1514 {Section\ } 1515 {\ for more info} 1516 {dataread} 1517), the default 1518will be the filter of the first lightcurve read in. 1519 1520\noindent 1521To obtain a hardcopy (i.e. PS file), use \\ 1522 1523{\bf -H}\\ 1524 1525 1526\subsection{Gravity Brightening} 1527 1528 1529\ni 1530The nonspherical shape \label{gravbright} 1531of both stars causes a non-constant surface gravity. 1532This, in term, causes brightness variations, with regions of higher 1533surface gravity having higher brightness. This effect is called gravity 1534brightening or gravity darkening (depending on which article you read). 1535Gravity brightening can produce deep minima in the lightcurve, 1536even if there is no eclipse at all !! 1537{\sc nightfall} always takes care of this effect - there is no option to 1538switch it off. \\ 1539 1540\newpage 1541\begin{rawhtml} 1542<HR> 1543\end{rawhtml} 1544 1545\section{Disk} 1546\label{disk} 1547 1548\ni 1549In a binary system where one star fills its Roche lobe, there may be mass transfer via 1550Roche lobe overflow. I.e. at the L1 point between the two stars, matter from the 1551Roche-lobe filling star can flow into the Roche lobe of the other star. For physical 1552reasons (conservation of angular momentum), this matter will not just fall onto the 1553other star, but rather form a so-called {\bf accretion disk}.\\ 1554 1555\ni 1556Within this disk, the 1557gas orbits the star and loses angular momentum by friction, thus slowly moving towards 1558the stellar surface. If the star has a strong magnetic field, this field may disrupt 1559the disk close to the star. I.e. the disk will not reach all the way to the stellar surface, 1560but rather there will be a gap between the inner edge and the star, and the gas will take 1561the last part of its journey along the magnetic field lines.\\ 1562 1563\ni 1564The disk is characterized by inner and outer radius, temperature, height, and the {\bf disk model}. 1565Furthermore, optionally a {\bf hot spot} may be included in the model.\\ 1566 1567\ni 1568The outer and inner edge of the disk are modelled as vertical ``walls''. 1569 1570\subsection{Disk model} 1571 1572\ni 1573For all models, the height of the disk at radius {\bf r} is computed as 1574\[ a + b * r^c. \] 1575 1576\subsubsection{Simple disk} 1577 1578\ni 1579For a {\bf simple disk}, $c = 1$, $a$ is set equal to half of the {\bf thickness} parameter, and 1580$b$ is set equal to the {\bf H/R} parameter. Setting H/R to zero results in a flat disk. 1581The {\bf temperature} is constant and equal to the respective input parameter. 1582 1583\subsubsection{Isothermal disk} 1584 1585\ni 1586While the {\bf simple} disk model is isothermal, it's run of the height with radius is not 1587physically correct for an isothermal disk. In the {\bf isothermal disk}, the exponent $c$ 1588is set to $c = 1.5$, which is the correct value for an isothermal disk. Furthermore, 1589the {\bf H/R} parameter is ignored, the constant $a$ is set to $a = 0.0$, and the factor 1590$b$ is chosen such that at the inner disk radius, the disk thickness equals the 1591{\bf thickness} input parameter. 1592 1593\subsubsection{Reprocessing disk} 1594 1595\ni 1596The {\bf reprocessing disk} is the model for a disk that is reprocessing (absobing/re-radiating) the 1597radiation from the central star. The exponent $c$ 1598is set to $c = 9/8$, which is the correct value for a reprocessing disk. Furthermore, 1599the {\bf H/R} parameter is ignored, the constant $a$ is set to $a = 0.0$, and the factor 1600$b$ is chosen such that at the inner disk radius, the disk thickness equals the 1601{\bf thickness} input parameter. Lastly, the {\bf temperature} falls off with radius 1602as $r^{-frac{3}{4}}$. 1603 1604\subsection{Disk parameters} 1605 1606\begin{itemize} 1607 1608 \item 1609 (1, 2) inner and outer radius, 1610 1611 \item 1612 (3) thickness at inner edge, 1613 1614 \item 1615 (4) H/R (height/radius), only used in {\bf simple disk} model, 1616 1617 \item 1618 (5) temperature at inner edge, constant throughout the disk for 1619 {\bf simple disk} model and {\bf isothermal disk} model. 1620 1621\end{itemize} 1622 1623\subsection{Hot spot parameters} 1624 1625\ni 1626The disk may have a hot spot (where the accretion stream from the donor star 1627hits the outer edge of the disk). The hot spot is assumed to have constant 1628temperature and constant depth (as measured from the outer edge of the disk). 1629 1630\ni 1631To {\bf switch off} the hot spot, set the extent in longitude to zero. 1632 1633\begin{itemize} 1634 1635 \item 1636 (1) T(hot spot) the temperature of the hot spot (assumed constant), 1637 1638 \item 1639 (2) Longitude(hot spot) the longitude where the hot spot centre is located 1640 on the disk rim. 1641 1642 \item 1643 (3) Extent(hot spot) the extent in longitude, and 1644 1645 \item 1646 (4) Depth(hot spot) the depth, as measured from the outer disk edge, to 1647 which the hot spot extends into the disk. 1648 1649 \item 1650 (5) Puff(yness): the extent to which the hot spot region is ``puffed up''. 1651 This is modelled with a cosine law in longitude and a quadratic law in radial 1652 direction, with the maximum attained at the hot spot centre at the outer edge 1653 of the disk. The ``Puff'' value is relative to the disk size and is {\it added} 1654 to the disk height. 1655 1656\end{itemize} 1657 1658 1659 1660\section{Advanced Options} 1661\label{advanced} 1662 1663\subsection{Fractional Visibility} 1664 1665As eclipse testing is only done for the centres of surface elements, 1666the coarse surface grid introduces numerical artifacts that are readily 1667visible sometimes. To fix this problem, it is possible to compute 1668{\bf fractional visibilities} for the surface elements (i.e. compute what 1669fraction of a surface element is eclipsed). To switch on, use \\ 1670 1671{\bf -F}\\ 1672 1673Note: this option is not available if {\sc nightfall} is compiled 1674in high precision mode (--enable-high-precision), since flux is 1675not sufficiently accurate conserved.\\ 1676 1677 1678\subsection{Reflection} 1679 1680\ni 1681Due to the mutual \label{reflect} 1682irradiance of both stars, in addition to its own light, 1683each star will also reflect light of its companion. This can be a very 1684important effect, especially if the two stars are close (large Roche fill 1685factor) or the temperature difference is large. 1686{\sc nightfall} offers two options:\\ 1687 (1) by default, the irradiating 1688star is treated as a point source. This is ok for low Roche lobe 1689filling factors, but not very accurate for stars filling a large fraction of 1690the Roche lobe. It is rather fast, however.\\ 1691 (2) it is possible to compute the mutual irradiance of all pairs of surface 1692elements, with up to nine iterations (usually, two to three are sufficient). 1693This is an $N^2$ algorithm (N the number of surface elements), and thus 1694computationally very expensive. To switch on, use \\ 1695 1696{\bf -Rn}\\ 1697 1698\ni 1699where 'n' is the number of iterations. 1700 1701 1702\subsection{Overcontact systems} 1703 1704\noindent 1705For overcontact systems, the second Lagrange point (L2) comes into play. 1706It is located behind the less massive star (as seen from the more massive), 1707and has the same property as L1, i.e. the force vanishes there, and matter 1708might flow out of the common envelope of an overcontact system (I suppose, 1709by now you know where L3 is. L4 and L5 are in the orbital plane, left and 1710right of the line connecting the centres of both stars. L3-5 are not 1711terribly important for binary stars.)\\ 1712 1713\noindent 1714Thus, the surface of the common envelope of an overcontact system has to be 1715between the two equipotential surfaces given by the potentials of L1 and L2 1716(remember, the force is the derivative of the potential, thus if the net force 1717is zero, the potential can still have a non-zero value - it just has to be 1718'flat' locally).\\ 1719 1720\noindent 1721To have an overcontact system, set the Roche lobe filling factor of one star 1722larger than 1.0 (as there is only one surface now, the smaller Roche lobe 1723filling factor will be ignored). 1724If you choose a too large value, {\sc nightfall} will adjust it. (The largest 1725possible value depends on the mass ratio. Anything 1726larger than about 1.3 is rather unreasonable for any mass ratio.)\\ 1727 1728\noindent 1729The combination of overcontact and non-circular orbit or 1730asynchroneous rotation (see below) 1731is not supported. It would be rather unphysical anyway, 1732as the strong interaction (tidal forces and friction) would 1733circularize and synchronize the system 1734extremely rapidly. 1735 1736\subsection{Asynchroneous Rotation} 1737 1738\noindent 1739Tidal forces in close binaries will tend to enforce synchroneous rotation 1740(both stars rotating with the orbital period, thus showing each other 1741always the same side) on a timescale usually shorter than stellar lifetimes.\\ 1742 1743\ni 1744There are, however, occasions when stars might rotate asynchroneously, e.g. 1745young stars that are not yet rotating synchroneously, 1746or massive stars that have short livetimes anyway, too short for 1747synchronization to occur during their lifetime. Also, tidal forces 1748fall off very rapidly with increasing distance, thus wide binaries 1749are likely candidates for asynchroneous rotation 1750(the tidal force is inverse proportional to 1751the cube of the distance - unlike e.g. gravity, which is inverse proportional 1752to the square of the distance and thus falls off much less rapidly).\\ 1753 1754\ni 1755A (nonstellar) example for synchronization is the Earth-Moon system, 1756where Moon's rotation has been synchronized already, while Earth's rotation 1757is known to slow down gradually. This would eventually lead to Earth's 1758synchronization as well, but I suspect it might take longer than the lifetime 1759of our solar system ...\\ 1760 1761\ni 1762To switch on asynchroneous rotation, 1763use \\ 1764 1765{\bf -fP fratio} or {\bf -fS fratio}\\ 1766 1767\ni 1768[-fP for Primary, -fS for Secondary). 'fratio' is the ratio between 1769stellar rotation period and orbital 1770period. \\ 1771 1772\noindent 1773Asynchroneous rotation modifies the Roche potential (see 1774 \hyperref 1775 {the info on 'Roche lobe'} 1776 {Section\ } 1777 {} 1778 {roche}), 1779and hence 1780the equipotential surface which defines the stellar shape. One effect 1781is a 'flattening' of the star for faster rotation. 1782Another effect is that the 'critical lobe', 1783i.e. the largest possible surface, is modified. For faster rotation, it 1784becomes smaller than the Roche lobe (which is the 'critical lobe' for 1785a synchroneously rotating star, as discussed 1786 \hyperref 1787 {here} 1788 {in Section\ } 1789 {} 1790 {roche}). 1791In this situation, you might have two binary component, both filling 1792their 'critical lobes', but well separated from each other.\\ 1793 1794\ni 1795For slower rotation, the 'critical lobe' can become larger than the Roche 1796lobe... {\sc nightfall} will check (and complain), if both stars intersect. 1797(While an overcontact system with synchroneous rotation is no problem, 1798asynchroneous rotation, with contact, will cause heavy friction, I would 1799think, presumably leading to rapid synchronization. Thus a contact 1800system with asynchroneous rotation probably is unrealistic.)\\ 1801 1802\ni 1803Surface spots (if there are any) 1804will move with the stellar rotation rate (just as they should). 1805 1806\subsection{Eccentric Orbit} 1807 1808\noindent 1809According to Keplers \label{eccentric} laws, the shape of the orbit is 1810an ellipse. Often, it is close to a special case of an ellipse - a circle. 1811However, sometimes binary orbits are markedly eccentric, i.e. non-circular. 1812In an eccentric orbit, 1813the distance and the orbital velocity is not constant. The stars will 1814gain velocity, as they fall toward each other, and 1815move fastest at Periastron (closest approach). They will lose 1816velocity again as they move away from each other, and move slowest at Apastron 1817(largest distance). Thus the time between first and second 1818eclipse in general is different from the time between second and first. 1819Also, the width of the eclipses may be different, as in general 1820the stars will move with different velocities during the two eclipses. 1821{\sc nightfall} comes with sample data for the star 'V541 Cygni', an eccentric 1822binary system where you can observe both effects.\\ 1823 1824\ni 1825Similar to asynchroneous rotation, the comment applies that tidal forces 1826will act towards circularization of the orbit. Eccentric orbits are more 1827likely in wide binaries than in close ones. \\ 1828 1829\ni 1830The problem is, that in an eccentric orbit the changing distance 1831is equivalent to a changing Roche lobe filling factor, 1832and thus a changing shape of the star 1833(remember, the larger the Roche lobe filling factor, the 1834larger also is the nonspherical distortion of a star's shape). 1835While in a circular orbit the stellar surface is calculated only once, 1836and then just rotated in space, in an eccentric orbit the stellar surface 1837must be re-calculated at each step in orbital phase, thus causing substantial 1838computational overhead. \\ 1839 1840\ni 1841To switch on this option, use \\ 1842 1843{\bf -e eccentricity periastron\_length}\\ 1844 1845\ni 1846where 'eccentricity' (range 0-1, 0 is circular orbit) is defined as 1847\[ e = \frac{r_2 - r_1}{r_2 + r_1}, \] with $r_2$ is the largest and 1848$r_1$ the smallest distance. Clearly, $e = 0.0$ if $r_2 = r_1$, 1849which is the case for a circular orbit. $e = 1.0$ is a 1850degenerate case (a parabola), which cannot be handled by the program. 1851'periastron\_length' is the length (in degree) of the periastron, 1852i.e. the point of closest approach in the orbit. To find out how it is 1853counted, you may set the Roche lobe filling factor to 1.0, and e to a high 1854value, like 0.5, Then, using the animation option (-A), you can identify 1855the periastron easily, as the star will fill the Roche lobe at closest 1856approach. 1857 1858\noindent 1859The input Roche lobe filling factor is assumed at Periastron. 1860Due to the variable orbital velocity, 'synchroneous' rotation is not really 1861synchroneous - rotation will lag behind the orbital motion for part of the 1862orbit, and advance for the other part of the orbit. 1863Surface spots (if there are any) will move accordingly.\\ 1864 1865 1866\subsection{Limb Darkening} 1867 1868\ni 1869The depth to which you can see into a star's atmosphere (where the visible 1870light comes from) varies with 1871the viewing angle. As the temperature (which determines the light flux) 1872increases with depth, you can see hotter (= brighter) layers 1873of the atmosphere towards the centre of the star's disk, where you 1874can look deeper. Towards the limb, you see shallower, cooler, and thus 1875less bright layers of the atmosphere. 1876This results in the limb of a star being darker than the 1877centre of its visible disk, an effect that can be seen readily on good (!) 1878photographies of the Sun.\\ 1879 1880\ni 1881Limb darkening, as a function of the cosine of the viewing angle 1882towards the stellar surface, 1883is well aproximated by simple expressions. {\sc nightfall} offers three 1884different options, with expressions that are linear or include 1885additional square or square root terms. The square root law 1886is probably most accurate, but you will 1887find that there is not much difference. \\ 1888 1889\ni 1890The default is the linear law. To change this, use \\ 1891 1892{\bf -Ln}\\ 1893 1894\ni 1895with 'n' a number in the range 0-2 (0 = default).\\ 1896 1897\ni 1898To set the limb darkening coefficients explicitely (e.g. for fitting, if 1899you use an external fitting routine), use \\ 1900 1901{\bf -l[P/S] lc\_1\_a,lc\_1\_b,..,lc\_12\_b}\\ 1902 1903\ni 1904where 1..12 refers to the passbands in the order UBVRIJHK,Str\"omgren uvby. 1905 1906\subsection{Surface Spots} 1907 1908\ni 1909Cool stars like the sun (i.e. stars with surface temperatures of a 1910few thousand Kelvin only) \label{spotted} 1911often have surface spots, which are regions of somewhat lower temperature 1912on the surface. Among such stars, some are 1913known to have surface spots ('starspots') much larger than those 1914shown by the Sun. In extreme 1915cases, spots may cover a few tenths of the stellar surface. Usually, these 1916are cool spots (i.e. a few 100 K cooler than the surrounding area), caused 1917by magnetic activity (like on the Sun). \\ 1918 1919\ni 1920To include spots, use \\ 1921 1922{\bf -sP longitude latitude radius dimfactor} or\\ 1923 1924{\bf -sS longitude latitude radius dimfactor} \\ 1925 1926\ni 1927(-sP for a spot on the Primary, -sS for a spot on the secondary). 1928Spots are circular. The arguments are longitude and latitude of the spot's 1929centre, the radius (all in degree) and the factor, by which the surface 1930temperature is changed in the spot area. You can have multiple spots on each 1931star. For overlapping spot areas, 'dimfactor' is averaged.\\ 1932 1933\ni 1934It is possible, but physically very unrealistic, to set 'dimfactor' to rather 1935low or high values (0.5 - 2.0). Temperature deviations of more than about 19361000 K may be not realistic. Hot spots are seen only in 1937exceptional cases. 1938 1939 1940\subsection{Radial Velocities} 1941 1942\noindent 1943Unlike lightcurves, which can be expressed in a relative unit, radial 1944velocity curves only make sense in absolute units (km/s in {\sc nightfall}). 1945Thus, they require absolute dimensions as input for the system. 1946({\sc nightfall} supplies default values, however, if you don't want to 1947bother about this.) Use \\ 1948 1949{\bf -tP period} or \\ 1950 1951{\bf -tM mass} or \\ 1952 1953{\bf -tD distance}\\ 1954 1955\ni 1956('period' in days, 'mass' ( = total mass of both stars) in solar masses, 1957'distance' in solar radii.) You need to give two of these; the third 1958can (and will) be calculated from Kepler's third law. \\ 1959 1960\noindent 1961Radial velocities are computed as the sum of the orbital velocity of a point 1962mass plus corrctions (flux-weighted contributions from each surface element). 1963In animated view, you can see the resulting sum as well as the correction term 1964(the latter multiplied by 2). 1965 1966\subsection{Line profiles} 1967 1968\ni 1969{\sc nightfall} can calculate spectral line profiles at each phase 1970step, which are output to files (one for each phase step). You can 1971specify the rest wavelength 'lambda\_zero' for the line. 1972The luminosities (of individual surface elements) 1973used to compute the profile are those for the passband with the closest 1974effective wavelength. To switch on, use \\ 1975 1976{\bf -Plamda\_zero}\\ 1977 1978\ni 1979In interactive mode, you have the option to view the line profiles, and 1980change the phase interactively.\\ 1981 1982\ni 1983{\it Some numerical artifacts present, probably due to finite surface grid.} 1984 1985 1986\subsection{Third Light} 1987 1988\noindent 1989The presence \label{third} 1990of an additional light source in the system (e.g. a third star) 1991will decrease the contrast between eclipsed and non-eclipsed parts of the 1992lightcurve. To include this effect, use \\ 1993 1994{\bf -3filter fraction}\\ 1995 1996\noindent 1997where 'filter' is one of the supported filters (UBVRIJHKuvby) and 1998'fraction' is the relative contribution of third light 1999to the total system luminosity. I.e.: \[ L1 + L2 + L3 = 1.0,\] 2000where $L1 + L2$ is the combined light flux from Primary and Secondary, 2001and $L3$ is 'third light'.\\ 2002 2003\noindent 2004{\undertext{This option is not tested yet.}} 2005 2006\subsection{Replacing the built-in filter set} 2007 2008\noindent 2009It is possible to replace any or all of the built-in filters 2010with (a) different one(s). The command line option to replace 2011a filter is:\\ 2012 2013{\bf -r X:path}\\ 2014 2015\noindent 2016where {\bf X} is one of the built-in filters (UBVRIJHKuvby), and {\bf path} 2017is the path to a file containing the data for the replacement filter. The 2018format of the file is as follows (also see the example 2019{\tt Filter\_OM\_UVM2.txt} in the data/ subdirectory):\\ 2020 2021\noindent 2022The filter definition file is a text file, containing certain {\bf keywords} 2023and {\it data}. Comments start with '\#', empty lines are 2024ignored. {\it In flux/LDC tables, values are separated by whitespace.} 2025The keywords are:\\ 2026 2027\noindent 2028{\bf NAME} {\it filter\_name}\\ 2029 2030\noindent 2031{\bf WAVELENGTH} {\it filter\_central\_wavelength\_in\_mu}\\ 2032 2033\noindent 2034\# (second moment of passbands)$^2$ / FWHM\\ 2035\# may be approximated following the prescription by\\ 2036\# Young A.T. 1992, Astronomy and Astrophysics 257, 366; Equation 12:\\ 2037\# m2 = FullWidth(0.05 of peak)/4.4\\ 2038\# $=>$ (m2)$^2$/FWHM \\ 2039{\bf CORR\_FACTOR} {\it numerical\_value}\\ 2040 2041\noindent 2042\# Limb Darkening Coefficients. Argument is the LD law the coefficients are for.\\ 2043{\bf LDC\_START} {\it linear} OR {\it sqrt} OR {\it quadratic} OR {\it four}\\ 2044\# followed by a table of coefficients, sorted by $\log{g}$,\\ 2045\# and then $T_{eff}$ (ascending)\\ 2046$T_{eff}$ $\log{g}$ $coeff_1$ $coeff_2$ ...\\ 2047 2048\noindent 2049\# Model flux tables (optional). Arguments are $\log{g}$, lower and upper\\ 2050\# limits for $T_{eff}$. Data sorted by $T_{eff}$ (ascending)\\ 2051{\bf FLUX\_START} {\it $\log{g}$ $T_{eff}$\_lower $T_{eff}$\_upper\\ 2052$T_{eff}$ $flux(T_{eff})$\\ 2053 2054 2055\newpage 2056\begin{rawhtml} 2057<HR> 2058\end{rawhtml} 2059 2060\section{Fitting observed data} 2061 2062\ni 2063{\sc nightfall} offers \label{fitting} 2064the possibility of determining a best-fit model 2065for observed data. Several datasets can be fit simultaneously. 2066Both a local and a global optimization algorithm are available. 2067{\bf Fit results} are written to a file 'NightfallFitted.dat'. 2068 2069\subsection{Important notes} 2070 2071\begin{itemize} 2072\item Optimization can be quite time consuming. {\sc nightfall} is able 2073to distribute the workload across several hosts, if so desired. Read 2074Sect. 3.6 (Parallelization) for details. 2075 2076\item If you require (sub-)millimagnitude accuracy, such as e.g. for 2077modelling exoplanet transits, you {\bf must} compile 2078{\sc nightfall} in high precision mode (--enable-high-precision).\\ 2079 2080{\sc nightfall} has been tested with data for the exoplanet TrES-2, 2081and is able to fit the transit and recover the parameters 2082cited by Holman et al (2007), ApJ 664, 1185. Note however that 2083planetary transits can be computed analytically, which is 2084faster than a full-fledged binary star model as done by 2085{\sc nightfall}. 2086\end{itemize} 2087 2088\subsection{Reading in the data} 2089 2090\noindent 2091In order \label{dataread} 2092to determine a best-fit model to observed data, you first 2093have to read them into memory. Use \\ 2094 2095{\bf -I path/to/data/file}.\\ 2096 2097\ni 2098Only one file is read. To read more files, prepend each of them with a 2099{\bf -I}. You can read in (only) one datafile for each filter.\\ 2100 2101\noindent 2102Each row in the file should consist of two or three numbers. The first 2103is the date of the observation (as decimal number, in any unit you like), 2104the second the measurement value (in magnitudes 2105for brightness, in km/s for radial velocity), and the third (optional) 2106the estimated error of the measurement.\\ 2107 2108\ni 2109Lines starting with a '\#' are ignored, with the following exceptions 2110(no blank after '\#' !!):\\ 2111 2112\ni 2113{\bf \#P period} 2114gives the orbital period of the system (same unit as dates). 2115The program will use this value 2116to fold the data into orbital phase. The default is 1.0 (thus assuming 2117that your data are already folded in phase).\\ 2118 2119\ni 2120{\bf \#C} 2121is a flag that tells the program to {\bf not} fold the data into orbital 2122phase. Instead, the program will synthesize a lightcurve covering the full 2123timespan of the data. 2124 2125\ni 2126{\bf \#Z zeropoint} 2127gives the zeropoint for orbital phase, i.e. the time of Primary eclipse 2128(same unit as dates). 2129The default is 0.0 (again assuming 2130that your data are already folded in phase).\\ 2131 2132\ni 2133{\bf \#B filter} 2134gives the filter (UBVRIubvyJHK) in which your data have been observed. 2135Default is V. For radial velocities, use '1' for Primary, '2' for Secondary.\\ 2136 2137\ni 2138{\bf \#W error} 2139gives the average estimated error of measurements (if you do not have 2140individual ones). Default is 0.01 (brightness) or 1.0 (radial velocities). 2141You can mix individual and average error estimates (e.g. if you have 2142individual error estimates only for some of your data).\\ 2143 2144\ni 2145{\bf \#V system\_velocity} 2146For radial velocity curves, use this parameter to set the system velocity. 2147Radial velocities will be set to $data - system\_velocity$.\\ 2148 2149\ni 2150{\bf \#N normalisation\_phase} 2151Use this parameter to set the phase at which to normalize the light curve. 2152The default is the starting point of the lightcurve.\\ 2153 2154\ni 2155{\bf \#S shift} 2156This is a particular important parameter that requires some care. As noted 2157in 2158 \hyperref 2159 {the info on brightness,} 2160 {in Section\ } 2161 {,\ } 2162 {norm} 2163{\sc nightfall} will normalize its lightcurves to light at 2164the normalisation\_phase (see above), 2165which by default is the starting point 2166of the lightcurve (the leftmost in the plotted lightcurve). 2167Thus, at this point, the brightness is zero magnitudes. 2168For a meaningful fit, your observed lightcurve must be shifted up/down 2169to have the value zero at this point as well (within the measurement 2170errors). {\sc nightfall} will 2171try to do it automatically, but some correction may be required. Plot the 2172lightcurve (data will be overplotted, if there are any), and check. 2173Note: incorrect use of this parameter may make a fit look better, but 2174the fitted parameters might be meaningless. Do not shift to anywhere else 2175than the starting point of the lightcurve.\\ 2176 2177 2178\noindent 2179The source code distribution includes example files for the binaries 2180TY Boo (an overcontact system) and some more. If in doubt, look into them. 2181 2182 2183\subsection{Finding a local optimum} 2184 2185\noindent 2186Determining a best-fit model means to optimize the parameters (like 2187inclination, temperature, mass ratio, etc.) in such a way that the mismatch 2188between model and observation is minimized. This mismatch is measured 2189by a suitable {\bf merit function} 2190(sometimes also called {\bf cost function}). {\sc nightfall} uses the 2191chi-square function as merit function.\\ 2192 2193\noindent 2194General problems of determining best-fit parameters are:\\ 2195 2196\noindent 2197(1) uniqueness: there may be several/many (nearly) equally good solutions. 2198Do a few trials. {\bf Restart} fitting with last best-fit as starting point.\\ 2199 2200\noindent 2201(2) overfitting: the information content of a lightcurve is limited. Fitting 2202too many parameters might produce good-looking, but meaningless results. 2203Use as few free parameters as are sufficient for a good fit.\\ 2204 2205\noindent 2206(3) local vs. global optimum: just that you find a valley, doesn't mean this is 2207the deepest valley on Earth. The same applies to optimization problems. 2208Any local optimization algorithm will only find a local optimum. If 2209the problem is well-behaved, this will be the one and only, global, optimum. 2210If the problem is badly-behaved, you might need a few trials with different 2211starting points to find (hopefully) the global optimum. If the problem 2212is even worse, you might need an awful lot of computing time to find 2213the global optimum. Most examples in textbooks are nice. Most real-world 2214optimization problems turn out to be bad or even ugly.\\ 2215 2216\noindent 2217{\sc nightfall} uses the so-called Simplex algorithm for local 2218optimization. This is a direct search algorithm that is not terribly fast 2219(and not terribly slow either), 2220but very robust. To switch on optimization, use\\ 2221 2222 {\bf -Xparameters tolerance}\\ 2223 2224\noindent 2225where 'parameters' is a string of characters indicating the parameters 2226you want to fit (all others kept fixed), and 'tolerance' is the stopping 2227criterion (something like 0.1 or less would be appropriate - 0.001 has 2228a special meaning, see 2229 \hyperref 2230 {the section on global fitting} 2231 {Section\ } 2232 {} 2233 {global}). 2234Use 2235'nightfall' without options to get the character codes for fit parameters.\\ 2236 2237\noindent 2238If more than one data file is input (e.g. lightcurves in different filters), 2239{\sc nightfall} will fit all data simultaneously. This will probably work 2240well only if different datasets are properly weighted - i.e. if the 2241error estimates (or at least their ratios) are ok.\\ 2242 2243\ni 2244Have a cup of coffee ready. Use the {\bf -Db} option (switch on 'Busy' in 2245interactive mode) to see what is going on meanwhile.\\ 2246 2247\ni 2248{\bf IMPORTANT:} Restart fit with last best-fit as starting point. 2249Continue this until you are sure that the solution has converged and does not 2250improve anymore, i.e. the value of 'SDV (Chi square)' does not significantly 2251change anymore. Otherwise, your results may be {\bf completely meaningless}. 2252(swich on the -Db option to see 'SDV (Chi square)' for each iteration -- 2253see 2254 \hyperref 2255 {the info on debug options.} 2256 {Section\ } 2257 {.} 2258 {debug}\\ 2259 2260\ni 2261{\it Output is always written to a file 'NightfallFitted.dat'.} 2262 2263\subsection{Goodness-of-fit} 2264 2265\ni 2266To evaluate how good a fit is, {\sc nightfall} offers the following 2267options:\\ 2268 2269\ni 2270(1) if you plot the lightcurve, residuals will be plotted as well. Look 2271at them to check whether there are systematic trends ( = bad fit). \\ 2272 2273\ni 2274(2) for a good fit, the residuals should scatter randomly around the 2275model, with no systematic trends. This can be quantified by computing the 2276{\bf 'runs statistic'} (the number of runs = occurences of two or more 2277{\bf consecutive} residuals above or below the model curve). Obviously, 2278a large number of runs would occur for a strictly alternating sequence, 2279which is very unlikely for a random sequence. Likewise, only two runs 2280would occur for the first half of the data below, the second above the 2281model curve - also suspiciously non-random. 2282{\sc nightfall} will print out the actual number of runs, and 2283the lower and upper limits for a 90 percent confidence interval.\\ 2284 2285 2286\ni 2287(3) in theory, the goodness-of-fit can be evaluated from the $\chi^2$ 2288(Chi Square) value of the fit (the function actually minimized in 2289parameter fitting), which should be close to unity for a good fit. 2290However, this only works 2291if the error estimates for the measurements 2292are realistic - neither to high nor to low. This is 2293very rarely the case in astronomy ... 2294 2295 2296\subsection{Finding a global optimum} 2297 2298\noindent 2299To find a \label{global} global optimum, 2300basically a stochastic search strategy is required 2301(or an exhaustive seach of the complete parameter space ...). 2302There are different possibilities, ranging from complete random search to 2303some 'intelligent' variation of random search. {\sc nightfall} offers 2304'Simulated Annealing', which is a kind of mathematical implementation of 2305the cooling of matter (leading to crystallization, i.e. an energy optimum, 2306if cooling is slow enough). Switch on by setting the fit tolerance to 0.001 2307(in command-line mode).\\ 2308 2309\noindent 2310Be prepared for a computing time on the order of a day or more (if you have 2311no other CPU-expensive job running).\\ 2312 2313\noindent 2314I am not sure whether the algorithm is correctly implemented. In the 2315present implementation, cooling 2316might be too fast, or might stop at a too high 'temperature'. However, 2317my own experiments were rather satisfactory most of the time.\\ 2318 2319\noindent 2320Apparently, 'Simulated Annealing' does not mathematically 2321guarantee that the global optimum is indeed 2322found, unless 'cooling' proceeds infinetely slow ... 2323 2324\subsection{Mapping the Chi-Square function} 2325 2326This option will create a two-dimensional map of the 2327merit function (i.e. in the case of {\sc Nightfall} the 2328Chi-Square function that measures the 2329goodness of a fit) with respect to two parameters. 2330Start values are the current values, step values 2331can be entered. The gridsize is fixed at compile time 2332(default 16 x 16, i.e. 256 lightcurves will be evaluated). 2333To switch on this option, use\\ 2334 2335 {\bf -Xparameters step1 step2}\\ 2336 2337Parameters are coded like in the fitting option (see above), 2338but only two parameters should be chosen. 2339 2340 2341\newpage 2342\begin{rawhtml} 2343<HR> 2344\end{rawhtml} 2345 2346\section{Miscellaneous} 2347 2348\subsection{Debug options} 2349 2350{\bf -Dcharacterstring}\\ 2351 2352\noindent 2353Most debug \label{debug} options (selected by 'characterstring') 2354are of little use 2355unless you know the code rather well. Some will produce excessive 2356(and excessively messy) output.\\ 2357 2358\ni 2359Exceptions are: 2360 2361\begin{itemize} 2362 2363 \item {\bf t} ('terse'), which will just print the chi square value 2364 of a fit after completion. 2365 2366 \item {\bf b} ('busy'), which keeps your screen somewhat busy 2367 in case you do something computationally expensive 2368 (data fitting, elliptical orbit). 2369 2370 \item {\bf w} ('warning'), which will print out warnings. Usually, 2371 these refer to problems that the program can deal with, and 2372 thus you can ignore them. If you do not get the output you expect, 2373 you might want to turn them on to see what the program complains 2374 about. 2375 2376 \item {\bf v} ('verbose'), which will print out a moderate amount of 2377 information (will grow excessive during data fitting ... use 'b' 2378 instead if you just want to see what's going on). 2379 2380\end{itemize} 2381 2382 2383\subsection{Output of the surface map} 2384 2385It is possible to obtain the 2D surface map of the stars, as seen by an 2386observer, i.e. the map displayed in animated mode. 2387You have to set the environment variable 2388NIGHTFALL\_SMAP\_PATH to the path of the map file (the program will 2389append the index of the phase to this, i.e. you will get a seperate file for 2390each step in orbital phase). If NIGHTFALL\_SMAP\_PATH is undefined, 2391no map will be printed. 2392 2393By default, the map will be output for the V band; you can change that 2394with the environment variable NIGHTFALL\_SMAP\_BAND (0..11 for UBVRIJHKuvby). 2395 2396The map includes for each {\it visible} surface element:\\ 2397\hs{1cm} (1) the index of the star,\\ 2398\hs{1cm} (2) the index of the surface element,\\ 2399\hs{1cm} (3, 4) x, y coordinates in the viewing plane of the observer, 2400with the star at (0, 0),\\ 2401\hs{1cm} (5, 6) x, y coordinates as above, but with the centre of mass 2402at (0, 0),\\ 2403\hs{1cm} (7) $\cos{\gamma}$, the line-of-sight angle,\\ 2404\hs{1cm} (8) temperature, \\ 2405\hs{1cm} (9) dimensionless gravity,\\ 2406\hs{1cm} (10) area,\\ 2407\hs{1cm} (11) flux.\\ 2408The flux is not normalized to the area; it is the flux that this surface 2409element contributes to the total flux. 2410 2411 2412\subsection{User-defined wavelenghts} 2413 2414It is possible to compute monocromatic fluxes at up to twelve different, 2415user-defined wavelengths. These wavelengths (unit: micrometer) must be 2416provided as a comma-seperated list in the environment 2417variable NIGHTFALL\_MONO\_WAVE. They will replace the wavelenghts used in the 2418blackbody approximation. 2419 2420\begin{itemize} 2421 2422 \item 2423 If less than twelve wavelengths are given, the remaining ones will be filled 2424 in with the wavelengths of the corresponding passbands. 2425 2426 \item 2427 For each wavelength, 2428 {\sc nightfall} will use the limb darkening 2429 coefficients of the passband whose wavelength matches 2430 best the monochromatic one. 2431 2432 \item 2433 Blackbody approximation must be selected (i.e. the 'model atmosphere' option 2434 must be switched off), otherwise these user-defined 2435 wavelengths do not take effect. 2436 2437\end{itemize} 2438 2439\newpage 2440\begin{rawhtml} 2441<HR> 2442\end{rawhtml} 2443 2444\section{Technical details} 2445 2446\it 2447This section is intended as a technical reference for experts who want to 2448familiarize themself with the nasty details and the algorithms used. 2449 2450\rm 2451 2452\subsection{Geometry} 2453 2454\noindent 2455The geometric setup is based on a paper \cite{djura92a} 2456by Djura\v{s}evi\'{c} (1992a). 2457In a cartesian coordinate system $(x, y, z)$, the stars are located at 2458$(0, 0, 0)$ and $(1, 0, 0)$, and the $z$-axis is perpendicular to the orbital 2459plane. 2460A normalized, dimensionless Roche potential is used, which at a point 2461$P(x,y,z)$ is given by the value $C$ as 2462\[ C = \frac{1}{r_1} + q (\frac{1}{r_2} - x) 2463 + \frac{q + 1}{2} ( x^2 + y^2 )f^2, \] 2464with $r_1 = x^2+y^2+z^2$, $r_2 = (x-1)^2+y^2+z^2$, 2465mass ratio $q = m_2/m_1$, and nonsynchronism parameter $f = w/w_k$ 2466(i.e. the ratio of the angular velocity to the Keplarian angular 2467velocity).\\ 2468For practical purposes, a spherical coordinate system $(r, \eta, \phi)$ 2469is used, which is defined by 2470\begin{eqnarray*} 2471 x & = & r\ \cos{\eta},\\ 2472 y & = & r\ \sin{\eta}\ \cos{\phi},\\ 2473 z & = & r\ \sin{\eta}\ \sin{\phi}.\\ 2474\end{eqnarray*} 2475The surface of the star is then divided into elementary areas by a grid 2476in $(\eta, \phi)$, and for each surface element the gravity 2477acceleration $g(r, \eta, \phi)$, the area $dS(r, \eta, \phi)$, and the normal 2478vector $(l, m, n)$ is computed as outlined in \cite{djura92a}.\\ 2479 2480\noindent 2481{\it Notes}: 2482{\bf (i)} Equation (1-16) in \cite{djura92a} has a minor typo 2483(wrong sign for $l$).\\ 2484{\bf (ii)} Djura\v{s}evi\'{c} \cite{djura92a} apparently uses 2485equidistant steps in $\phi$, thus leading 2486to very unhomogeneous elementary areas. {\sc nightfall} avoids this 2487by adjusting the number of steps $N_{\phi}$ as 2488\[ N_{\phi} = 10 + N_{\eta} sin{\eta},\] 2489with $N_{\eta}$ a (compile-time) constant. 2490 2491\subsubsection{Accretion disk} 2492Eclipse testing for the accretion disk is based on the method described in \cite{djura92a} 2493by Djura\v{s}evi\'{c} (1992b). 2494 2495 2496\subsection{Reflection and gravity darkening/brightening} 2497 2498\noindent 2499There are two options available for the treatment of reflection. 2500Both are {\it bolometric} corrections, in the sense that the bolometric 2501flux of the irradiating component is used to modify the temperature 2502distribution on the irradiated component. See \cite{wilso90} for a discussion 2503of this issue.\\ 2504 2505\noindent 2506The 'simple' option for the treatment of reflection is described 2507in \cite{djura92a}. The correction should be 2508exact for spherical stars.\\ 2509 2510\noindent 2511The 'detailed' reflection treatment loops over all pairs of surface 2512elements $(dS_1,dS_2)$ and sums up, for each surface element $dS_1$, 2513the irradiation by all visible surface elements $dS_2$ of the other star. 2514Again, {\it bolometric} irradiation is computed. Of course, the true 2515temperature of the irradiating surface elements (including reflection) 2516is not known, thus it is necessary to iterate the algorithm. Convergence 2517is typically reached after 2-3 iterations. 2518The algorithm is described in \cite{hendr92}.\\ 2519 2520\noindent 2521For both treatments, by default for convective stars 2522(below 7700 K) an albedo of 0.5, and for 2523radiative stars an albedo of 1.0 is used. It is possible to 2524choose different albedo values at program start using 2525the command line option(s) {\tt -aP} {\it value} for the primary and 2526{\tt -aS} {\it value} for the secondary.\\ 2527 2528\noindent 2529Gravity darkening is computed by 2530\[ T(r, \eta, \phi) = T_{eff}(\frac{g(r, \eta, \phi)}{g_{eff}})^{\beta}. \] 2531For the gravity brightening exponent, the results from \cite{claret00a} 2532(Fig.~1 in the paper) are used, which provide a smooth transition to the 2533Von Zeipel (1924) exponent of 0.25 for radiative stars.\\ 2534 2535\noindent 2536{\it Notes}: 2537{\bf (i)} The 'simple' reflection treatment in \cite{djura92a} 2538has been supplemented by a penumbral correction for 2539the partial visibily of the other star, if it is at the horizon. 2540This penumbral correction assumes that the horizon is flat 2541and that the other star 2542is spherical, i.e. that the visible part is a segment of a circle.\\ 2543{\bf (ii)} For the 'detailed' reflection treatment, instead of 2544the quadratic limb darkening law used by 2545\cite{hendr92}, a square root law (\cite{diaz92}) 2546\[ I(\mu) = I(1)[1 - c(1-\mu) - d(1 - \sqrt{\mu})] \] 2547is used (where $\mu$ is the cosine of the angle subtended by the emergent 2548radiation and the direction perpendicular to the stellar surface), 2549and bolometric 2550limb darkening coefficients are taken from \cite{claret00}. 2551The normalization factor for the square root 2552law was calculated as 2553\[ \frac{1}{\pi\ (1 - c/3 - d/5)}.\] 2554{\bf (iii)} The temperature limit of 7700\,K dividing stars with 2555convective/radiative envelopes can be changed by the environment 2556variable NIGHTFALL\_RADIATIVE (within the range 4000 -- 12000\,K). 2557This changes the albedo only (0.5 below, 1.0 above). 2558 2559\subsection{Doppler boost} 2560Since version 1.88, the computed flux includes a correction for the Doppler 2561boost caused by the radial velocity of the components relative to the 2562observer. This correction is computed following Eq. (3) 2563in \cite{vanke10} van Kerkwijk et al. 2010, using the effective wavelength 2564of the filter passbands for $\lambda$. 2565 2566\subsection{Spots} 2567 2568\noindent 2569Spots are always circular, and 2570characterized by four parameters: longitude $\lambda$, 2571latitude $\beta$, radius $r$, and a 'dimming' factor $A_p = T_p/T$, 2572i.e. the ratio of the (local) temperature $T_p$ with spot to the temperature 2573$T$ without spot. A detailed discussion of the trigonometric 2574expressions used to identify surface elements within the spot area 2575can be found in \cite{djura92a}, section I-3. 2576In the 'detailed' reflection treatment, 2577reflection is calculated with spots, i.e. the spots are applied first, 2578then the reflection is calculated. For overlapping spots, in the overlap area 2579the mean value of their $A_p$ is used. 2580 2581\subsection{Output flux} 2582 2583\noindent 2584In the blackbody approximation, for each stellar component and 2585each filter a (temperature-dependent) 2586effective wavelength is computed, following Equation 3.30 in 2587\cite{buddi93}: 2588\[ {\lambda}_{eff} = {\lambda}_{0} 2589 + \frac{ 5 {\mu}_2 ({\lambda}_{p}-{\lambda}_{0}) }{\sqrt{{\lambda}_{0}}}, 2590\] 2591where ${\lambda}_{0}$ is the filter wavelength, and ${\lambda}_{p}$ 2592the wavelength of the blackbody peak for the effective temperature of the 2593respective component. 2594The required second moments ${\mu}_2$ of the filter passbands 2595are computed following the prescription by \cite{young92}, Equation 12: 2596\[ {\mu}_2 \simeq \frac{FW(0.05)}{4.4}, \] where $FW(0.05)$ is 2597the full width at the 0.05 level.\\ 2598 2599 2600\noindent 2601For the 'model atmosphere' option, fluxes for temperatures below 9800\,K are 2602from Hauschildt et al. (private comm., 2006) PHOENIX models, 2603otherwise flux tables from Kuruzc models (\cite{kuru98}). 2604are used. All models are for solar abundances. PHOENIX models below 26052000\,K incorporate dust formation, with dust remaining in situ (no settling). 2606The (originally monochromatic) fluxes have been integrated over 2607the filter passbands (as given in \cite{lando82}). 2608Surface gravities $\log{g} = 3.5 - 5.0$ (in steps of 0.5) are available.\\ 2609 2610\noindent 2611Three different limb darkening approximations are available, a {\it linear}, 2612a {\it quadratic}, and a 2613{\it square root} one, 2614which are given by the following expressions, respectively: 2615\begin{eqnarray*} 2616I(\mu) & = & I(1)[1 - u(1-\mu)],\\ 2617I(\mu) & = & I(1)[1 - a(1-\mu) - b(1-\mu)^2],\quad {\rm and}\\ 2618I(\mu) & = & I(1)[1 - c(1-\mu) - d(1 - \sqrt{\mu})],\\ 2619\end{eqnarray*} 2620where $\mu$ is the cosine of the angle subtended by the emergent 2621radiation and the direction perpendicular to the stellar surface. 2622Limb darkening coefficients are from \cite{claret00}. 2623A discussion of the relative 2624merits of these three approximations can be found in \cite{diaz92}. 2625 2626\noindent 2627{\it Notes}: 2628{\bf (i)} When tabulated values are used, for temperatures out of 2629range (below 2000\,K and above 31000\,K for $\log{g} = 3.5$, 263039000\,K for $\log{g} = 4.0$, 49000\,K for $\log{g} = 4.5$, 263150000\,K for $\log{g} = 5.0$) the 2632lowest/highest value is used (i.e. no extrapolation is attempted). 2633{\bf (ii)} It is possible to set the limb darkening coefficients on the 2634command line, with the option {\tt -l[P/S] lc\_1\_a,lc\_1\_b,..,lc\_12\_b}, 2635where 1..12 refers to the passbands in the order UBVRIJHK,Str\"omgren uvby. 2636This can be used for fitting the coefficient when an external fit routine 2637is used. 2638 2639\subsection{Eclipse testing} 2640 2641\noindent 2642Eclipse testing follows the method proposed in \cite{djura92a}. First, 2643the contact angle of the Roche lobes is used to exclude eclipses, if 2644possible.\\ 2645If an eclipse is possible, 2646for each surface element $dS$ the line of sight (LOS) towards $dS$ 2647is tested for intersection with the smallest sphere enclosing the 2648eclipsing star (no intersection = not eclipsed). Then the LOS is 2649tested for intersection with the largest sphere within the 2650eclipsing star (intersection = eclipsed). This procedure takes advantage 2651of the simplicity of testing the intersection of a line with a sphere.\\ 2652If the LOS intersects the outer, but not the inner sphere, as a last 2653(and computationally expensive) resort, the minimum of the Roche potential 2654along the LOS is searched, and compared against the surface potential 2655of the eclipsing star.\\ 2656 2657\noindent 2658{\it Notes}: 2659{\bf (i)} In \cite{djura92a}, the osculating cone (i.e. the tangent cone 2660to the Roche surface at the inner Lagrangian point $L_1$) is used as the first 2661eclipse criterion. According to \cite{chana72}, this can lead to serious 2662errors for mass ratios very different from unity, as the larger Roche lobe 2663is concave at the $L_1$. {\sc nightfall} uses tabulated values from 2664\cite{chana72} (the cone angle $\phi_{\rm max}$ as given in their Table 2). 2665{\bf (ii)} In \cite{djura92a}, the coordinate frame of the 2666eclipsed star is used, for eclipse testing, 2667which seems not to work for asynchroneous rotation. 2668{\sc nightfall} therefore uses the coordinate frame of the eclipsing star, 2669following \cite{antok96}. 2670{\bf (iii)} In \cite{djura92a}, it is proposed to evaluate the potential 2671along the LOS at six steps only. {\sc nightfall} uses a more rigorous 2672approach with a minimum finding routine (Brent's algorithm \cite{brent73}). 2673 2674 2675\subsection{Fractional visibility} 2676 2677\noindent 2678The eclipse testing routine assigns to each surface element a visibility 2679of 0 (eclipsed) or 1 (visible). However, the visibility is only 2680evaluated for the centre of the element. This can lead to 'spikes' in the 2681light curve, if large numbers of surface element centres become visible 2682at once. Therefore, an option is provided to compute a {\it fractional} 2683visibility for surface elements on the shadow limb.\\ 2684 2685\noindent 2686The algorithm first searches all pairs of elements on the shadow limb 2687(i.e. pairs with 2688one element eclipsed, the adjacent element uneclipsed), and 2689determines the potential minimum along the LOS towards them (which is typically 2690already available from the eclipse test). 2691Then, a linear approximation is made: 2692for each pair, the 2693distances $d_i$ to the shadow limb are taken as proportional 2694to the differences 2695between the minimum Roche potential $p_{i}^{LOS}$ along the LOS 2696and the surface potential $p_{*}$ 2697of the eclipsing star: 2698\[ f = \frac{d_1}{d_2} = \frac{p_{1}^{LOS} - p_{*}}{p_{2}^{LOS} - p_{*}}.\] 2699The surface element with the larger distance is assumed to be 2700completely eclipsed or visible, and the other one of the pair is assigned 2701a fractional visibility $(1/2 + |f|)$ based on the above approximation. 2702This is not exact for individual surface elements, 2703as the dividing line between them may not be parallel to the shadow limb. 2704However, averaged over all surface elements on the limb, the error 2705should be negligeable. 2706 2707 2708\subsection{Eccentric orbits} 2709 2710\noindent 2711In an eccentric orbit, the complete geometry and temperature distribution 2712is re-calculated at each step ( = step in mean anomaly). As the Roche 2713potential is used in a dimensionless form, the change in distance 2714is equivalent to a change in the Roche volume filling factor 2715( = surface potential) with an unchanged unit distance.\\ 2716 2717\noindent 2718This implies that the correct new surface potential must be found as 2719a function of the stellar volume, which is scaled up/down with the 2720distance. To avoid an iterative numerical integration of the stellar volume 2721(i.e. varying the surface potential until the correct volume is found), 2722which would be prohibitively expensive, the algorithm uses analytical 2723approximations from \cite{kopal} to derive the new surface potential.\\ 2724 2725\noindent 2726The following procedure is used: 2727\begin{enumerate} 2728\item Solve the Kepler equation to determine the distance of the stars 2729 (and their position in the orbit). 2730\item Re-scale the distance to unity. 2731\item Scale the stellar volume by the the cube of the distance scale factor. 2732\item Find the 'mean radius' as the root of an analytical 2733 expression for the stellar volume (of 11th order in this 'mean radius'). 2734\item Compute the new surface potential as a function of the 'mean radius'. 2735\end{enumerate} 2736 2737\noindent 2738Numerical details, including the definition of the 'mean radius', can 2739be found in \cite{kopal}. 2740 2741\subsection{Optimization} 2742 2743\noindent 2744For local optimization, the Simplex algorithm is used. This is a 2745direct search algorithm that does not require derivatives. 2746For $N$ free parameters, 2747the simplex is a polyhedron with $(N + 1)$ vertices (or points) in the 2748$N$-dimensional parameter space. At each step, the simplex moves 2749through this parameter space according to some rules, basically 2750moving away from its worst point. 2751Details of the algorithm can be found in \cite{kallr87,nelder65}.\\ 2752 2753\noindent 2754For global optimization, an implementation of the 'simulated annealing' 2755method is provided. 2756Basically, 'simulated annealing' does a stochastic search of 2757the parameter space. Replacing the current best point with a better 2758point (i.e. a downhill step) is always allowed, 2759replacing it with a worse point (an uphill step) is allowed with some 2760probability depending on the (steadily decreasing) 'temperature' of the 2761system.\\ 2762The implementation is based on the 'Very Fast Simulated Re-Annealing' 2763algorithm 2764\cite{ingber}, however, the 're-annealing' part is not included. 2765For random number generation, the 2766'Mersenne Twister' random number generator (period length $2^{19937} - 1$) 2767by Makoto Matsumoto and Takuji Nishimura \cite{mersenne} is used. 2768It has a Mersenne prime period of $2^{19937} - 1$ (about $10^{6000}$) 2769and is equi-distributed in 623 2770dimensions. 2771 2772 2773\subsection{Runs Test} 2774 2775\ni 2776The nonparametric {\bf runs test} is computed to provide an estimate 2777of the goodness-of-fit that (unlike chi-square) is independent of the 2778correctness of the measurement error estimates. In an ordered sequence of 2779two different symbols (here: positive and negative fit residuals, ordered 2780by phase), a {\it run} is a succession of one or more identical symbols, 2781preceded and followed by the other symbol.\\ 2782 2783\ni 2784The expected number R of runs can be calculated analytically. 2785If $m$ and $n$ are the number of negative and positive residuals, respectively, 2786then the expectation value for the number of runs R, and its variance, 2787are (\cite{rohatgi84}): 2788 2789\[ \mathscr{E}_{\mathrm{(R)}} = 1 + \frac{2mn}{(m + n)} \] 2790 2791and 2792 2793\[ \mathrm{var(R)} = \frac{2mn(2mn - m - n)}{(m + n - 1)(m + n)^2} \] 2794 2795 2796\newpage 2797\begin{rawhtml} 2798<HR> 2799\end{rawhtml} 2800 2801\addtocontents{toc}{\protect\contentsline{section}{\numberline {}References}{34}} 2802 2803\begin{thebibliography}{99} 2804 2805\bibitem{alenc97} 2806Alencar S.H.P., Vaz L.P.R. (1997), A\&A 326, 257 2807 2808\bibitem{antok96} 2809Antokhina E.A. (1996), ARep 40, 483 2810 2811\bibitem{brent73} 2812Brent R. (1973), Algorithms for minimization without derivatives, 2813Prentice-Hall 2814 2815\bibitem{buddi93} 2816Budding E. (1993), 2817An Introduction to Astronomic Photometry, 2818Cambridge University Press 2819 2820\bibitem{chana72} 2821Chanan G. A., Middleditch J., Nelson J.E. (1972), ApJ 208, 512 2822 2823\bibitem{claret00a} 2824Claret A. (2000), A\&A 359, 289 2825 2826\bibitem{claret00} 2827Claret A. (2000), A\&A 363, 1081 2828 2829\bibitem{diaz95a} 2830Diaz-Cordov\'{e}s J., Claret A., Gim\'{e}nez A. (1995), A\&ASS 110, 329 2831 2832\bibitem{diaz95b} 2833Claret A., Diaz-Cordov\'{e}s J., Gim\'{e}nez A. (1995), A\&ASS 114, 247 2834 2835\bibitem{diaz92} 2836Diaz-Cordov\'{e}s J., Gim\'{e}nez A. (1992), A\&A 259, 227 2837 2838\bibitem{djura92a} 2839Djura\v{s}evi\'{c} G. (1992a), Ap\&SS 196, 241 2840 2841\bibitem{djura92b} 2842Djura\v{s}evi\'{c} G. (1992b), Ap\&SS 196, 267 2843 2844\bibitem{hendr92} 2845Hendry, P. D., Mochnacki, S. W. (1992), ApJ 388, 603 2846 2847\bibitem{peter99a} 2848Hauschildt P.H., Allard F., Baron E. (1999), ApJ 512, 377 2849 2850\bibitem{peter99b} 2851Hauschildt P.H., Allard F., Ferguson J., Baron E., Alexander D.R. (1999), 2852ApJ 525, 871 2853 2854\bibitem{ingber} 2855Ingber L. (1989), J.Math.Comput.Modelling 12, 967 2856 2857\bibitem{kallr87} 2858Kallrath J., Linnel A.P. (1987), ApJ 313, 346 2859 2860 2861\bibitem{kopal} 2862Kopal Z. (1989), The Roche Problem, 2863Kluwer Academic Publishers 2864 2865\bibitem{kuru98} 2866Kurucz R. L. 1998, http://kurucz.harvard.edu/grids/gridp00/ip00k2.pck19, 2867accessed 2006-04-12 2868 2869\bibitem{lando82} 2870Landolt-Boernstein (1982), 2871Numerical Data and functional Relationships in Science and Technology. 2872New Series, Berlin: Springer 2873 2874\bibitem{mersenne} 2875Matsumoto M. \& Nishimura T., 2876ACM Transactions on Modeling and Computer Simulation, Vol. 8, No. 1, p. 3 2877 2878\bibitem{nelder65} 2879Nelder J.A., Mead R. (1965), Comput. J. 7, 308 2880 2881\bibitem{rohatgi84} 2882Rohatgi, Vijay K. (1984), Statistical Inference, John Wiley \& Sons, Inc. 2883 2884\bibitem{vanha93} 2885Van Hamme W. (1993), AJ 106, 2096 2886 2887\bibitem{vanke10} 2888van Kerkwijk, M. H. et al. 2010, ApJ 715, 51 2889 2890\bibitem{wilso90} 2891Wilson R.E. (1990), ApJ 356, 613 2892 2893\bibitem{young92} 2894Young A.T. 1992, A\&A 257, 366 2895 2896\end{thebibliography} 2897 2898 2899 2900\newpage 2901\begin{rawhtml} 2902<HR> 2903\end{rawhtml} 2904 2905\begin{appendix} 2906 2907\section{Command line Options} 2908 2909\begin{tabular}{ll} 2910\hline 2911 & \\ 2912{\bf 'Educational':} & \\ 2913 --edu & switch on highly simplified 'educational' mode \\ 2914{\bf Mandatory:} & \\ 2915 (q) & mass(Secondary)/mass(Primary) \\ 2916 (i) & inclination angle (degree) \\ 2917 (rf1) & Primary Roche fill factor \\ 2918 (rf2) & Secondary Roche fill factor \\ 2919 (t1) & Primary temperature \\ 2920 (t2) & Secondary temperature \\ 2921\hline 2922 & \\ 2923{\bf Interactive:} & \\ 2924 -U & Interactive mode \\ 2925\hline 2926 & \\ 2927{\bf Graphic Output:} & \\ 2928 -A & Animated view \\ 2929 -V[v,i,c,a] & Visualize geometry (default: v) \\ 2930 & v: view of stars \\ 2931 & i: image of potential \\ 2932 & c: contourmap of potential \\ 2933 & a: all of the above \\ 2934 -G[P,S,1,2] & Graph of lightcurve (default: 1) \\ 2935 & P,S: close-up of Primary/Secondary eclipse\\ 2936 & 1,2: display 1/2 orbital cycles \\ 2937 -B[U/B/V...]& Bandpass to display in graph (default: V) \\ 2938 -H & Hardcopy (postscript plot) \\ 2939\hline 2940 & \\ 2941{\bf Files:} & \\ 2942 -I datafile & Read in a data file containing observed data \\ 2943 -C cfgfile & Read in a configuration file \\ 2944\hline 2945 & \\ 2946{\bf Advanced System Parameters:} & \\ 2947 -f[P/S] F & 2948 asynchroneous rotation ratio (Period/Period\_Orbit) \\ 2949 -s[P/S] longitude latitude radius dimfactor & 2950 Spot on Primary/Secondary \\ 2951 -e e w & 2952 eccentric orbit, e = eccentricity, w = periastron length \\ 2953 -t[P/M/D] value & period/total mass/separation 2954 in days/solar masses/solar radii \\ 2955\hline 2956 & \\ 2957{\bf Debugging Options:} & \\ 2958 -D[vwb] & Debug [verbose,warn,busy] \\ 2959\hline 2960 & \\ 2961{\bf Computation Options:}& \\ 2962 -Plamda\_zero & Profile of absorption line at 2963 rest wavelength lamda\_zero (nm) \\ 2964 -Nnn & nn steps for lightcurve (default 80) \\ 2965 -M & use Model atmosphere \\ 2966 -O[P/S] value & $\log{g}$ (surface gravity) Primary/Secondary\\ 2967 -F & compute Fractional visibility \\ 2968 -L[0-2] & Limb darkening method (default: linear = 0)\\ 2969 & 0: linear \\ 2970 & 1: quadratic \\ 2971 & 2: square root \\ 2972 -R[1-9] & Reflection treatment \\ 2973 & 0: Point source \\ 2974 & 1-9: iterations for mutual reflection \\ 2975 -a[P/S] value & Albedo of Primary/Secondary \\ 2976 & (default: 0.5 for T $<=$ 7700, 1.0 otherwise)\\ 2977 -3CM & Third light, C: colour code, M: magnitude \\ 2978\hline 2979 2980\end{tabular} 2981\newpage 2982\begin{tabular}{ll} 2983\hline 2984 & \\ 2985{\bf Data Fitting:} & \\ 2986 -X[..] Tolerance& Fit the parameters coded in string [..] \\ 2987 & 012345: q, i, rf1, rf2, t1, t2 \\ 2988 & 67: e, w (eccentric orbit) \\ 2989 & 89: F(Primary),F(Secondary) (asynchroneous rotation) \\ 2990 & A-H: 2 Spots (Primary) \\ 2991 & I-P: 2 Spots (Secondary) \\ 2992 & QR: Mass, Separation\\ 2993 & a-l: Third Light (UBVRIJHKuvby) \\ 2994 & (Tolerance = 0.001 to use Simulated Annealing)\\ 2995 -Y[as above] Step1 Step2 & Chi Square Map (2 Parameters) \\ 2996\hline 2997\end{tabular} 2998 2999\end{appendix} 3000 3001 3002 3003\end{document} 3004 3005 3006 3007 3008 3009