HTTPS SSH
BinSim 0.8.1, Robert I. Hynes, 21 May 2002
============================================

This program is designed to produce pretty pictures of interacting
binaries (cataclysmic variables, X-ray binaries, etc).  In many places
the science has been fudged or ignored, so it is not suitable for
modelling light curves or spectra.  The code uses the OpenGL API to do
the 3D rendering.  As such there are some limitations since this
approach is better suited to rendering polygons (eg surface elements
of a star or disc) than to volumetric rendering (eg an accretion
stream or disc wind).  Consequently the treatment of optically thin
objects is rather poor.  At present the code will render the mass
donor star, an axisymmetric disc (no superhumps, warps or spirals
yet), the accretion stream and hotspot and a 'corona', which may
represent an accretion disc corona, a disc wind, some other kind of
uncollimated outflow or even a white dwarf!

USAGE
=====

To run the program you need a parameter file.  A sample is included in
this distribution.  Just type: 

% ./binsim sample.par

or 

% ./osbinsim sample.par

All options are controlled from the parameter file.

OUTPUT FORMATS
==============

BinSim can produce either JPEG or PPM images.  The type produced is
determined by the extension of the Image_File parameter: for JPEG
images, .jpg, .JPG, .jpeg and .JPEG are recognised.  For PPM then
either .ppm or .PPM are fine.  Any other extensions will be treated as
an error.  If Anim is turned on then only PPM mode as used as JPEG
does not work well with mpeg_encode.

If you do not have the libjpeg library then you can compile with the
-DNOJPEG option and remove the -ljpeg from the Makefile.  Then all
JPEG support is disabled.  This is the default for Windows as JPEG
writing does not work there.

OFF-SCREEN RENDERING
====================

BinSim can also be built to render off-screen, so that it can be run
from a remote telnet session to produce an image, etc.  This takes
advantage of Mesa's off-screen option (OSMesa) so will probably not
work with a commercial OpenGL library.  Consequently, this is not
built by default.  If you are using Mesa and want to do this then you
can do 'make osbinsim' to make the off-screen binary (osbinsim).  The
usage is the same as for binsim.

16 bits per channel
-------------------

BinSim can also take advantage of the new 16 bits per channel (64bpp)
OSMesa mode in Mesa 3.5.  This is not built by default and offers
little if any benefit in the current version of BinSim.  Getting it to
work is rather awkward, so there really isn't much point at present.
It does make it possible to build up an image of an optically thin
region by accumulating a lot more elements.  This means it will now be
possible to implement a high-quality voxel based model of optically
thin objects.  These voxel objects will require completely new code so
will take a while to introduce, but they should appear soon as I'm
looking forward to trying this.  See the INSTALL file for details of
how to get this working.

ANIMATION
=========

If the Anim keyword is true then a series of images will be generated
from Low_Phase to High_Phase with steps of Delta_Phase.  If Save is
also true then each image will be saved to Anim_Rootdir (which should
have a lot a free space) and an MPEG movie will also be created.  This
depends on having mpeg_encode installed.  See the INSTALL file for how
to get this.  If Save is not defined then the sequence will only be
rendered to the screen.  Unless you have a very fast machine or
hardware accelerated graphics, you will probably find this is too
slow, but I have found it works quite nicely (with High_Quality turned
off!) in full screen mode with a 3Dfx Voodoo3 card, and more recent
cards such as the various GeForce models should give even better
results.  Be warned that to obtain the fastest rendering speed, a lot
of things are pre-calculated and stored, so the memory requirements
can become quite large if too many frames are specified.

TIPS
====

As well as lobe overflowing stars, by setting Lobe_Fill to less than
1.0, Disc_Eff_Thick negative and turning off the stream and disc it is
possible to produce a detached system containing a distorted,
irradiated star.  A white dwarf + M dwarf detached binary can be
produced by doing this and making one of the coronae very small with a
very high opacity to represent the white dwarf.

PARAMETERS
==========

New parameters in v0.8.1
------------------------

None

New parameters in v0.8
----------------------

Disc_R_in, Show_Stellar_Wind, Stellar_Wind_Rad, Stellar_Wind_Red, 
Stellar_Wind_Green, Stellar_Wind_Blue, Stellar_Wind_Opacity, 
Stellar_Wind_Exponent, Show_Thin_Disc, Thin_Disc_Nsteps, Thin_Disc_Rad,
Thin_Disc_R_in, Thin_Disc_Geom_Thick, Thin_Disc_Beta, Thin_Disc_Red, 
Thin_Disc_Green, Thin_Disc_Blue, Thin_Disc_Opacity, Thin_Disc_N_Flare, 
Thin_Disc_Flare_Length, Show_Jet, Jet_Opening_Angle, Jet_Upper_Red, 
Jet_Upper_Green, Jet_Upper_Blue, Jet_Lower_Red, Jet_Lower_Green, 
Jet_Lower_Blue, Jet_Opacity, Jet_Exponent, Jet_Inclination, Jet_Rotation,
Vertex_Log 

New parameters in v0.7.3
------------------------

HighQuality_AA

New parameters in v0.7.2
------------------------

None

New parameters in v0.7.1
------------------------

None

New parameters in v0.7
----------------------

Anim, Low_Phase, High_Phase, Delta_Phase, Anim_Root, MPEG_File, 
MPEG_Pattern, MPEG_IQScale, MPEG_PQScale, MPEG_BQScale, 
Lobe_Granulation_Period, Hot_Spot_Timescale

New parameters in v0.6.1
------------------------

Image_File

Parameter             Definition                                Allowed values
---------             ----------                                --------------
Anim                  Animate the binary?                       True/False

Width		      Width of image in pixels		        Integer
Height		      Height of image in pixels		        Integer
Save		      Save an image file?		        True/False
Image_File            Name of output image file                 String
JPEG_Quality	      Output image quality		        Integer, 0-100
HighQuality	      Use high quality output?	                True/False
HighQuality_AA        Use antialiasing in high quality mode     True/False
Samples		      2x2 or 4x4 samples for antialiasing?      2 or 4
Brightness            Brightness of optically thick objects     Float
Contrast	      Contrast of optically thick objects       Float
Scale		      Scale of objects			        Float
XOffset               Shift of objects to right                 Float
YOffset               Shift of objects upwards                  Float
Vertex_Log            Produce logfile of all vertices           True/False

Anim_Root             Directory and rootname for animation      String
MPEG_File	      Name of output MPEG movie file            String
MPEG_Pattern          IPB Pattern for MPEG encoding             String
MPEG_IQScale          Quality of I frames                       Integer, 1-31
MPEG_PQScale          Quality of P frames                       Integer, 1-31
MPEG_BQScale          Quality of B frames                       Integer, 1-31

Show_Stars	      Include starfield background?	        True/False
N_Stars		      Number of stars to use		        Integer
Star_Colours          Range of colours to use for stars         Float
Star_Size             Size of stars in high quality mode        Float

Period		      Binary period in hours		        Float
q		      Mass ratio (donor/accretor)	        Float
M1		      Accretor mass in Msun		        Float
Luminosity	      Accretor luminosity (erg/s) for heating	Float
Inclination	      Binary inclination in degrees	        Float, 0-90
Phase		      Orbital phase to view (eclipse=0.0)       Float
Low_Phase             Starting phase in animations              Float
High_Phase            Final phase in animations                 Float
Delta_Phase           Phase step in animations                  Float

Show_Lobe	      Show the donor star?			True/False
Lobe_Nsteps           Donor star grid sampling                  Integer
Lobe_Fill             Lobe filling factor                       Float, 0-1
Lobe_T_Pole	      Polar temperature of donor		Float
Lobe_T_Min	      Minimum temperature / T_Pole		Float, 0-1
Lobe_Granulation      Amount of convective granulation on donor Float
Lobe_Granulation_Period Period of convection bubbling as        Float
                        fraction of orbital period 

Show_Disc	      Show the accretion disc?			True/False
Disc_Nsteps           Disc grid sampling                        Integer
Disc_Rad	      Disc radius / effective lobe radius	Float, 0-1
Disc_R_in	      Disc inner radius / effective lobe radius	Float, 0-1
Disc_Geom_Thick	      Thickness of disc (H/R)			Float
Disc_Eff_Thick	      Thickness of disc (H/R) for shielding	Float
Disc_Tout	      Temperature of disc edge			Float
Disc_Temp_Grad	      Temperature exponent of disc		Float
Disc_Beta	      Flaring exponent of disc			Float
Disc_N_Flare	      Number of flares to place on disc		Integer
Disc_Flare_Length     Length of disc flares in surface elements	Integer

Show_Thin_Disc        Show an optically thin accretion disc?	True/False
Thin_Disc_Nsteps      Disc grid sampling                        Integer
Thin_Disc_Rad         Disc radius / effective lobe radius	Float, 0-1
Thin_Disc_R_in        Disc inner radius / effective lobe radius	Float, 0-1
Thin_Disc_Geom_Thick  Thickness of disc (H/R)			Float
Thin_Disc_Beta        Flaring exponent of disc			Float
Thin_Disc_Red         Red component of RGB disc colour		Float, 0-1
Thin_Disc_Green       Green component of RGB disc colour	Float, 0-1
Thin_Disc_Blue        Blue component of RGB disc colour		Float, 0-1
Thin_Disc_Opacity     Optical thickness of disc			Float
Thin_Disc_N_Flare     Number of flares to place on disc		Integer
Thin_Disc_Flare_Length Length of disc flares in surface elementsInteger

Show_Stream	      Show the accretion stream?		True/False
Stream_Max_Thick      Maximum stream thickness / separation	Float
Stream_Open_Angle     Angular radius of stream origin           Float, 0-45
Stream_Red	      Red component of RGB stream colour	Float, 0-1
Stream_Green	      Green component of RGB stream colour	Float, 0-1
Stream_Blue	      Blue component of RGB stream colour	Float, 0-1
Stream_Opacity	      Optical thickness of stream		Float

Show_Hot_Spot	      Show the stream impact point?		True/False
Hot_Spot_Size	      Radius of hot spot / binary separation	Float
Hot_Spot_Red	      Red component of RGB hot spot colour	Float, 0-1
Hot_Spot_Green	      Green component of RGB hot spot colour	Float, 0-1
Hot_Spot_Blue	      Blue component of RGB hot spot colour	Float, 0-1
Hot_Spot_Opacity      Optical thickness of hot spot		Float
Hot_Spot_Timescale    Timescale for flickering of hotspot as    Float 
                      fraction of orbital period
Hot_Temp	      Temperature of hot-spot *on disc*		Float

Show_Corona1	      Show a disc wind or corona?		True/False
Corona1_Rad	      Radius of corona / binary separation	Float
Corona1_Red	      Red component of RGB corona colour	Float, 0-1
Corona1_Green	      Green component of RGB corona colour	Float, 0-1
Corona1_Blue	      Blue component of RGB corona colour	Float, 0-1
Corona1_Opacity	      Optical thickness of corona		Float
Corona1_Exponent      Radial density exponent of corona         Float

Show_Corona2	      Show a disc wind or corona?		True/False
Corona2_Rad	      Radius of corona / binary separation	Float
Corona2_Red	      Red component of RGB corona colour	Float, 0-1
Corona2_Green	      Green component of RGB corona colour	Float, 0-1
Corona2_Blue	      Blue component of RGB corona colour	Float, 0-1
Corona2_Opacity	      Optical thickness of corona		Float
Corona2_Exponent      Radial density exponent of corona         Float

Show_Stellar_Wind     Show a stellar wind from companion?	True/False
Stellar_Wind_Rad      Radius of wind / binary separation	Float
Stellar_Wind_Red      Red component of RGB wind colour		Float, 0-1
Stellar_Wind_Green    Green component of RGB wind colour	Float, 0-1
Stellar_Wind_Blue     Blue component of RGB wind colour	   	Float, 0-1
Stellar_Wind_Opacity  Optical thickness of wind			Float
Stellar_Wind_Exponent Radial density exponent of wind           Float

Show_Jet              Show a jet?				True/False
Jet_Opening_Angle     Opening angle of the jet                  Float, 0-90
Jet_Upper_Red         Red component of upper jet colour		Float, 0-1
Jet_Upper_Green       Green component of upper jet colour	Float, 0-1
Jet_Upper_Blue        Blue component of upper jet colour	Float, 0-1
Jet_Lower_Red         Red component of lower jet colour		Float, 0-1
Jet_Lower_Green       Green component of lower jet colour	Float, 0-1
Jet_Lower_Blue        Blue component of lower jet colour	Float, 0-1
Jet_Opacity           Optical thickness of jet			Float
Jet_Exponent          Radial density exponent of jet	        Float
Jet_Inclination       Angle between jet and orbital axis        Float, 0-90
Jet_Rotation          Angle of rotation of jet with respect     Float, 0-360
                      to the observer

Notes
-----

All boolean (True/False) parameters can also take values of On/Off or
Yes/No.

The HighQuality flag turns on high quality output (antialiasing and
nicer stars).  If the antialiasing causes problems (apparently it does
on Mac OS X) then it can be disabled by setting HighQuality_AA =
False.  If this parameter is not given it defaults to true.

If Vertex_Log is true then a file called vertices.log will be created
containing the coordinates and colours of every vertex in the model.
This will be very large, 30Mb or more is likely!  This is intended
only for debugging and should normally be disabled.  If it is not
specified it will silently default to false.  Don't enable this is
Anim is true - the log file will be HUGE!

Anim_Root should specify the directory (no trailing /) for animation
images.  This should be a directory with a lot of free space.  The
full filename will be <Anim_Root>/binsim_tmp.0001.jpg and so on.

The MPEG parameters sound rather obscure.  You can read about them in
the mpeg_encode manual that should have come with your distribution of
the encoder.  For an easy life, try two options:
  1) Best quality, large files:  Use Pattern = I and IQScale = 1
  2) Compression at the cost of quality: Pattern = IBBPBBPBBPBBPBBPB 
     (please don't ask why; the manual recommends it!) and increase
     IQScale, PQScale and BQScale until you get a satisfactory compromise.

Brightness and Contrast only effect optically thick surfaces (the disc
and companion star).  This is a limitation of the code; optically thin
materials are poorly modelled.  Future voxel based optically thin
components will improve on this situation.

Star_Colours determines the range of colours present in a background
starfield.  Setting it to 0.0 will make all stars white (ie shades of
gray according to brightness).  1.0 or more will give a very
colourful, if unrealistic background.  I find 0.5 gives some range
without being overstated.

Lobe_Fill can control how much of the Roche lobe is filled by the
companion star.  1.0 is lobe filling; lower values can give distorted
stars that do not fill their lobes.

T_Min can be used to prevent black L1 points.  Formally, the usual
gravity darkening formulae results in the temperature tending to zero
at the L1 point, which then appears black.  I'm sure this is not
physical.  Setting T_Min to some sensible value, e.g. 0.85, prevents
this.

Granulation_Amplitude should be set to zero for hot stars with
radiative envelopes.

Granulation_Period controls the time taken (as a fraction of the
orbital period) for each point on the companion to complete one minmax
cycle.  This is to create a convective bubbling effect.  If you don't
like the effect set this very large.

Disc_Eff_Thick and Disc_Geom_Thick can be set to different values to
allow more shielding of the mass donor than the disc rim alone could
produce.  This could model absorption of X-rays by the disc atmosphere
or a bulge in the inner disc.

Disc_Rad is definined as the fraction of Eggleton's effective lobe
radius, defined in Eggleton, P. P., 1983, ApJ, 268, 368.  If this is
set too small the stream may not behave well, as it is programmed to
continue until it reaches the disc rim; for small disc radii this will
never happen!

Disc_Temp_Grad is defined by T propto R^grad.  Standard values
are -3/4 for a Shakura-Sunyaev viscously heated disc, -3/7 for an
irradiated disc.

Disc_Beta is the flaring exponent of the disc defined by H/R propto
R^beta.  Standard values are 9/8 for a viscously heated disc or 9/7
for an irradiated disc, although how physical these are is debatable!

Stream_Max_Thick defines a maximum stream thickness.  This prevents
odd looking thick streams for long period systems.

Stream_Open_Angle sets the apparent opening angle of the stream as
seen from the centre of the companion star, in degrees. 10 degrees
looks okay for a typical mass ratio of 0.3.  This needs to be
decreased for large mass ratios (>1) and maybe increased for very
small ones.

Stream_Opacity, Hot_Spot_Opacity and Corona_Opacity are not defined on
any absolute scale, they just give some control over the optical
thicknesses.

Hot_Spot_Timescale controls the timescale (as a fraction of the
orbital period) of flickering at the stream impact point.

Hot_Temp controls the temperature of a heated area of the disc
downstream of the stream impact point.  Set this low to turn this
effect off.

Corona1_Exponent and Corona2_Exponent control the radial density
opacity of the coronae - 0.0 gives a uniformly shaded circle, without
even fading at the edges due to lower optical depths.  Positive values
will give a centrally condensed corona.  Negative values can produce a
shell-like effect.  This was not a designed effect, and isn't very
satisfactory.

The Stellar_Wind component is identical to a Corona except it is
centred on the companion star.

BUGS AND 'ISSUES'
=================

Small triangles
---------------

If the grid sizes (N_STEPS parameters) are too fine, or the scale is
too small, or the image size is too small, then triangles can occupy a
tiny fraction of a pixel.  Mesa 3.4.2 or earlier software rendering
does not always handle this case well and stars or discs may have
holes or black spots sprinkled over them, generally at the star poles
or disc centre.  This problem was fixed by Brian Paul on 12/06/01 and
incorporated into Mesa from version 3.5 onwards.  If you encounter
this problem either decrease the grid size, increase the image size or
update Mesa to version 3.5 or later.

Saving only works with software rendering
-----------------------------------------

The code to save an image does not work with Glide fullscreen mode -
the image is blank.  This problem may be common to all hardware
implementations but I have not been able to test any others.

Crash while encoding MPEGs
--------------------------

In theory mpeg_encode can work with JPEG images, but it often crashes
with segmentation faults.  If I find a solution to this I'll implement
it, otherwise MPEGs are constructed via (large) PPM files.

Problems with antialiasing on Mac OS X (and others???)
------------------------------------------------------

Antialiasing does not work properly under Mac OS X.  The problem may
occur on other platforms as well.  The effect is that colours become
banded, as if the image is produced with a 16 bit color display, or
less.  I don't know what causes it but it may be a rounding problem in
accumulating multiple samples.  From 0.7.3 it is possible to turn off
antialising without disabling high quality stars.  This is done by
setting HighQuality_AA = False in the parameter file.  

Saving images under Windows
---------------------------

I have major problems with saving images when running on Windows.
This is not fully functional in this version.  PPM output does work, I
think, although it required a kludge which may have other side effects
to get the colours right.  JPEG output crashes.  I don't know why, but
the crash appears to occur within a library call rather than in BinSim
proper, and even a simple image writing application reproduces it, so
it seems to be a libjpeg bug.  For this release, JPEG output has been
disabled on Windows, so PPM is the only option.

Generation of NaNs
------------------

On some platforms (Mac OS X, but not Unix/Linux or Windows?) BinSim
can try to pass NaNs as part of vertex values.  The effect of this is
undefined; you may get corrupted images, you may have the program (or
the X Server!)  crash.  This is being investigated.  If you get odd
looking features in the image, or a crash then turn on vertex logging
(Vertex_Log = True) and look at the resulting vertices.log.  There
should be no NaN or Inf values here.  If there are this is a serious
bug; please tell me.  Ideally send me the parameter file, the
offending lines grepped from vertices.log (not the whole file!) and
let me know what operating system and compiler you have.

FINALLY...
==========

Thanks to many people who have provided me with encouragement to
develop this code.  Also to Brian Paul and other contributors to Mesa,
which is so central to this program, both for writing the code and
responding to problems so efficiently.  Libjpeg is produced by the
Independent JPEG Group.  Thanks to Paul Ray and Torrey Lyons for
testing on Mac OS X.

This is still a beta release code and there are probably some bugs.
If you find something that doesn't work the way it should, or looks
odd then let me know.  Equally, if you modify the code and you think
others would benefit from the improvements I'll consider merging the
changes into the main code, with suitable acknowledgements.

At present the released code is also incomplete, in the sense that
there are many features that I've implemented in development code, and
produced images from, which are not available.  These will be merged
back into future releases gradually.

Finally, it is also subject to major changes if I think of a better
way to do things.  This will mean that new versions may not be
backwards compatible with old parameter files, although I'll try to
include some notes with each new version on the changes, as well as an
updated sample file.

Whatever, if you find the code useful or interesting please let me
know so I know how widely it is being used and can keep you informed
of developments.  I'd also like to hear from people who have success
(or failure) getting the program to work on other systems (currently I
use Redhat Linux 7.2 with Mesa 3.4.2 or Mesa 3.5 software rendering)
and/or can suggest any makefile changes needed.

--
Rob Hynes, University of Southampton, rih@astro.soton.ac.uk