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 ---------------------- 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 /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