diff --git a/doc/QUICKSTART b/doc/QUICKSTART deleted file mode 100644 index 431422c6c7757779d6f99869faf6a100a0e555f3..0000000000000000000000000000000000000000 --- a/doc/QUICKSTART +++ /dev/null @@ -1,52 +0,0 @@ -This is a guide to getting binary_c working as soon as possible. -Lines starting in $ are supposed to be run in a terminal using a bash shell. - -I assume you have the following installed on your system: - -* subversion -* a C compiler (e.g. gcc or clang) -* Perl and CPANM installed with perlbrew: you can install these through system packages, but Perlbrew is better -* You need various Perl modules, such as Inline::C. You can install these with cpanm, e.g. - -More information on software requirements is in: -doc/binary_c-software.pdf -doc/binary_c-installation.pdf - ------- - -$ cpanm Inline::C - ------- - -Now, run: - ------- - -$ ./configure -$ ./make cleanall -$ ./configure -$ ./make -$ ./make libbinary_c.so -$ cd src/perl/modules_targz -$ cpanm ./Histogram-0.01.tar.gz -$ ./install_all.gz -$ cpanm ./binary_grid-2.00.tar.gz --force -$ cd ../../.. - ------- - -Now open the "tbse" file. -Change the parameters to whatever you'd like them to be, e.g. M1, M2. -Then run the star: - ------- - -$ ./tbse - ------- - -The output to the screen is set in src/logging/log_every_timestep.c -By default there is minimal output to the screen. -A log file is available at /tmp/c_log2.dat - this may be sufficent for you. - -For more information, see the documentation in the doc directory. diff --git a/doc/README b/doc/README index 914efa077b0b0cc3862fb058ef8b029760ea2d61..c4e5d71aef59ab49e3215447094b7369fce775c5 100644 --- a/doc/README +++ b/doc/README @@ -1,8 +1,8 @@ Welcome to binary_c's documentation repository -* Instructions for getting binary_c are in getting_binary_c.pdf - -* To learn about everything, look at binary_c2.pdf +* The main manual is at binary_c2.pdf +There is an online version at +http://personal.ph.surrey.ac.uk/~ri0005/doc/binary_c/binary_c.html * A flow chart describing binary_c is at "Binary_c Flowchart.pdf" diff --git a/doc/binary_c2.lyx b/doc/binary_c2.lyx index 8ab48be0abf40421948bcf628e2fa3fa181ddac9..f82efdb1e941eae31cd55d989800f1e5bf1855a3 100644 --- a/doc/binary_c2.lyx +++ b/doc/binary_c2.lyx @@ -2186,6 +2186,63 @@ cd .. \begin_layout Itemize +\series bold +Optional +\series default + If you want to use +\begin_inset Formula $\binarycpython$ +\end_inset + + to make stellar populations: +\begin_inset listings +inline false +status open + +\begin_layout Plain Layout + +export GSL_DIR=`gsl-config --prefix` +\end_layout + +\begin_layout Plain Layout + +export LD_LIBRARY_PATH= +\begin_inset Quotes erd +\end_inset + +$HOME/lib:$BINARY_C:$BINARY_C/src +\begin_inset Quotes erd +\end_inset + + +\end_layout + +\begin_layout Plain Layout + +export LIBRARY_PATH="$LD_LIBRARY_PATH" +\end_layout + +\begin_layout Plain Layout + +export PATH=$HOME/bin:$HOME/.local/bin:$PATH +\end_layout + +\begin_layout Plain Layout + +pip3 install -U pip setuptools testresources +\end_layout + +\begin_layout Plain Layout + +pip3 install git+https://gitlab.eps.surrey.ac.uk/ri0005/binary_c-python.git +\end_layout + +\end_inset + + +\end_layout + +\begin_layout Itemize + \series bold Optional \series default @@ -2193,7 +2250,7 @@ Optional \begin_inset Formula $\binarygrid$ \end_inset -: + to make stellar populations: \end_layout \begin_deeper @@ -2425,63 +2482,6 @@ cpanm \end_layout \end_deeper -\begin_layout Itemize - -\series bold -Optional -\series default - If you want to use -\begin_inset Formula $\binarycpython$ -\end_inset - - -\begin_inset listings -inline false -status open - -\begin_layout Plain Layout - -export GSL_DIR=`gsl-config --prefix` -\end_layout - -\begin_layout Plain Layout - -export LD_LIBRARY_PATH= -\begin_inset Quotes erd -\end_inset - -$HOME/lib:$BINARY_C:$BINARY_C/src -\begin_inset Quotes erd -\end_inset - - -\end_layout - -\begin_layout Plain Layout - -export LIBRARY_PATH="$LD_LIBRARY_PATH" -\end_layout - -\begin_layout Plain Layout - -export PATH=$HOME/bin:$HOME/.local/bin:$PATH -\end_layout - -\begin_layout Plain Layout - -pip3 install -U pip setuptools testresources -\end_layout - -\begin_layout Plain Layout - -pip3 install git+https://gitlab.eps.surrey.ac.uk/ri0005/binary_c-python.git -\end_layout - -\end_inset - - -\end_layout - \begin_layout Subsection Running a single- or binary-star system \end_layout @@ -3742,6 +3742,19 @@ Mergers. SN stripping of companions. \end_layout +\begin_layout Itemize +Planetary orbits. +\end_layout + +\begin_layout Itemize +Circumbinary discs. +\end_layout + +\begin_layout Itemize +(With MINT) MS burning of the interior of the star and stellar structure + lookup tables. +\end_layout + \begin_layout Standard What does the \begin_inset Formula $\binaryc$ @@ -3765,19 +3778,6 @@ Common envelope nucleosynthesis - thought not to be important, but you never \end_layout -\begin_layout Itemize -(Pre-)MS burning of the interior of the star - this means that if a MS star - is stripped the increase in C13/N14 due to CNO cycling is not taken into - account. - However, if the star makes it to 1st dredge up then this is taken into - account. - Note there is -\emph on -experimental -\emph default - code which can deal with this. -\end_layout - \begin_layout Itemize WD surface layers - these are very complicated! \end_layout @@ -5155,7 +5155,11 @@ name "subsec:System-recommendations" \end_layout \begin_layout Itemize -If you plan to modify + +\series bold +Optional +\series default + If you plan to modify \emph on \begin_inset Formula $\binaryc$ @@ -5188,10 +5192,47 @@ gdb are both excellent, the former for detecting memory leaks and the latter for backtracing, but both are very powerful and flexible tools. + You can run +\begin_inset Formula $\binaryc$ +\end_inset + + through both using +\begin_inset Flex File +status open + +\begin_layout Plain Layout +tbse +\end_layout + +\end_inset + + (e.g. +\begin_inset space ~ +\end_inset + +Sec. +\begin_inset space ~ +\end_inset + + +\begin_inset CommandInset ref +LatexCommand ref +reference "subsec:How-to-debug-memory-leaks" +plural "false" +caps "false" +noprefix "false" + +\end_inset + +). \end_layout \begin_layout Itemize -I highly recommend the use of + +\series bold +Optional +\series default + You could use of \begin_inset Flex Software status open @@ -5217,7 +5258,11 @@ literal "false" \end_layout \begin_layout Itemize -If you can, install RGI's custom version of + +\series bold +Optional +\series default + If you can, install RGI's custom version of \begin_inset Flex Software status open @@ -5244,7 +5289,7 @@ https://gitlab.eps.surrey.ac.uk/ri0005/GSL-RGI \end_inset ). - + If you do not install this custom GSL, a system version must be installed. \begin_inset listings inline false status open @@ -5290,7 +5335,11 @@ make install \end_layout \begin_layout Itemize -If you can, install + +\series bold +Optional +\series default + If you can, install \begin_inset Flex Software status open @@ -5301,7 +5350,11 @@ librinterpolate \end_inset . - + If you do not, +\begin_inset Formula $\binaryc$ +\end_inset + + has an internal version but this may out of date. \begin_inset listings inline false status open @@ -5313,19 +5366,6 @@ export PREFIX=$HOME \begin_layout Plain Layout -export CFLAGS= -\begin_inset Quotes erd -\end_inset - --O3 -mtune=generic -\begin_inset Quotes erd -\end_inset - - -\end_layout - -\begin_layout Plain Layout - mkdir $HOME/lib $HOME/git \end_layout @@ -5341,22 +5381,22 @@ git clone gitlab@gitlab.eps.surrey.ac.uk:ri0005/librinterpolate.git \begin_layout Plain Layout -cd $HOME/git/librinterpolate/src +cd $HOME/git/librinterpolate \end_layout \begin_layout Plain Layout -make +meson builddir --prefix=$HOME --buildtype release \end_layout \begin_layout Plain Layout -make install +cd builddir \end_layout \begin_layout Plain Layout -unset CFLAGS +ninja install \end_layout \end_inset @@ -5422,7 +5462,11 @@ distribution_functions \end_layout \begin_layout Itemize -If you can, install + +\series bold +Optional +\series default + If you can, install \begin_inset Flex Software status open @@ -5433,7 +5477,11 @@ libmemoize \end_inset . - + If you do not, +\begin_inset Formula $\binaryc$ +\end_inset + + has an internal version but this may out of date. \begin_inset listings inline false status open @@ -5445,19 +5493,6 @@ export PREFIX=$HOME \begin_layout Plain Layout -export CFLAGS= -\begin_inset Quotes erd -\end_inset - --O3 -mtune=generic -\begin_inset Quotes erd -\end_inset - - -\end_layout - -\begin_layout Plain Layout - mkdir $HOME/lib $HOME/git \end_layout @@ -5473,22 +5508,22 @@ git clone gitlab@gitlab.eps.surrey.ac.uk:ri0005/libmemoize.git \begin_layout Plain Layout -cd $HOME/git/libmemoize/src +cd $HOME/git/libmemoize \end_layout \begin_layout Plain Layout -make +meson builddir --prefix=$HOME --buildtype release \end_layout \begin_layout Plain Layout -make install +cd builddir \end_layout \begin_layout Plain Layout -unset CFLAGS +ninja install \end_layout \end_inset @@ -5497,7 +5532,11 @@ unset CFLAGS \end_layout \begin_layout Itemize -If you can, install + +\series bold +Optional +\series default + If you can, install \begin_inset Flex Software status open @@ -5528,6 +5567,11 @@ ninja \end_inset ). + If you do not, +\begin_inset Formula $\binaryc$ +\end_inset + + has an internal version but this may out of date. \begin_inset listings inline false status open @@ -5610,7 +5654,7 @@ git \end_layout \begin_layout Standard -Assuming you have checked out your branch, a release or the trunk, from +Assuming you have checked out your branch, a release or the master, from the \emph on git @@ -5963,7 +6007,7 @@ Meson to make \begin_inset Foot -status open +status collapsed \begin_layout Plain Layout Consider installing also @@ -5992,7 +6036,8 @@ Meson \end_inset - a build directory, e.g., + a build directory, e.g., for a normal development build (without full optimizatio +n), \family typewriter \series bold @@ -6003,7 +6048,7 @@ status open \begin_layout Plain Layout -meson builddir --buildtype release +meson builddir \end_layout \end_inset @@ -6011,32 +6056,76 @@ meson builddir --buildtype release \family default \series default -and now you should go to that directory to build the code using -\begin_inset Flex Software +or for a release build (with full optimization), +\family typewriter +\series bold + +\begin_inset listings +lstparams "language=bash" +inline false status open \begin_layout Plain Layout -ninja + +meson builddir --buildtype release \end_layout \end_inset - (see sections + +\family default +\series default +see Sec. \begin_inset space ~ \end_inset \begin_inset CommandInset ref LatexCommand ref -reference "subsec:Ninja-autocompletion" +reference "subsec:Meson-buildtypes" plural "false" caps "false" noprefix "false" \end_inset - and -\begin_inset CommandInset ref + for more information on buildtypes. + Now you should go to the +\begin_inset Flex File +status open + +\begin_layout Plain Layout +builddir +\end_layout + +\end_inset + + directory to and run +\begin_inset Flex Software +status open + +\begin_layout Plain Layout +ninja +\end_layout + +\end_inset + + (see sections +\begin_inset space ~ +\end_inset + + +\begin_inset CommandInset ref +LatexCommand ref +reference "subsec:Ninja-autocompletion" +plural "false" +caps "false" +noprefix "false" + +\end_inset + + and +\begin_inset CommandInset ref LatexCommand ref reference "subsec:Meson-autocompletion" plural "false" @@ -6094,7 +6183,7 @@ cd builddir \begin_layout Plain Layout -ninja +ninja binary_c_install \end_layout \end_inset @@ -6102,7 +6191,7 @@ ninja \family default \series default -The code will now build, assuming everything worked ok. +The code will now build, assuming everything worked correctly. If it does \emph on not @@ -6199,11 +6288,23 @@ for use with distributed computing). \begin_inset Formula $\binaryc$ \end_inset - versions will probably use environment variables to point to data directories. + versions will probably use environment variables to point to data directories + (the +\begin_inset Formula $\MINT$ +\end_inset + + library already does this). \end_layout \begin_layout Subsubsection Meson buildtypes +\begin_inset CommandInset label +LatexCommand label +name "subsec:Meson-buildtypes" + +\end_inset + + \end_layout \begin_layout Standard @@ -6389,46 +6490,6 @@ ninja clean \end_inset -\family default -\series default -This does not clean the data objects, which are built only once. - If you want to clean these as well (equivalent to a -\begin_inset listings -lstparams "language=bash" -inline true -status open - -\begin_layout Plain Layout - -make cleanall -\end_layout - -\end_inset - - of old) you should run, -\family typewriter -\series bold - -\begin_inset listings -lstparams "language=bash" -inline false -status open - -\begin_layout Plain Layout - -./meson/clean_data_objects.sh -\end_layout - -\end_inset - - -\family default -\series default -from within the -\begin_inset Formula $\binaryc$ -\end_inset - - main directory. \end_layout \begin_layout Subsubsection @@ -6440,7 +6501,7 @@ Building the shared library \end_layout \begin_layout Standard -To build the shared library, go back into the builddir and run, +To build the shared library only, go back into the builddir and run, \end_layout \begin_layout Standard @@ -6459,11 +6520,6 @@ cd builddir ninja libbinary_c.so \end_layout -\begin_layout Plain Layout - -ninja libbinary_c_symlink -\end_layout - \end_inset @@ -6509,80 +6565,6 @@ API functions. \end_layout -\begin_layout Standard -The -\begin_inset Flex Args -status open - -\begin_layout Plain Layout -libbinary_c_symlink -\end_layout - -\end_inset - - call to -\begin_inset Flex Software -status open - -\begin_layout Plain Layout -ninja -\end_layout - -\end_inset - - symbolically links the -\begin_inset Formula $\binaryc$ -\end_inset - - executable to the -\begin_inset Formula $\binaryc$ -\end_inset - - -\begin_inset Flex File -status open - -\begin_layout Plain Layout -src -\end_layout - -\end_inset - - directory. - Warning: if the -\begin_inset Flex File -status open - -\begin_layout Plain Layout -builddir -\end_layout - -\end_inset - - is deleted, this link will not work. - If you want the executable copied, consider running -\begin_inset Flex Command -status open - -\begin_layout Plain Layout -ninja binary_c_install -\end_layout - -\end_inset - - instead (see below) or use -\begin_inset Flex Command -status open - -\begin_layout Plain Layout -ninja install -\end_layout - -\end_inset - -. -\end_layout - \begin_layout Subsubsection Building \begin_inset Formula $\binaryc$ @@ -6752,7 +6734,7 @@ cd builddir \begin_layout Plain Layout -ninja +ninja binary_c_install \end_layout \end_inset @@ -6798,7 +6780,7 @@ meson --reconfigure --buildtype release \begin_layout Plain Layout -ninja +ninja binary_c_install \end_layout \end_inset @@ -6837,7 +6819,7 @@ meson builddir -Dvalgrind=true --buildtype debug \begin_layout Plain Layout -ninja +ninja binary_c_install \end_layout \end_inset @@ -6866,7 +6848,7 @@ cd builddir \begin_layout Plain Layout -ninja +ninja binary_c_install \end_layout \end_inset @@ -7026,7 +7008,11 @@ status open \end_inset - if you want to run through + if you want to run +\begin_inset Formula $\binaryc$ +\end_inset + + through \begin_inset Flex Software status open @@ -7214,7 +7200,17 @@ literal "false" ). These should really just be installed locally, but there are internal versions - inside + of these (except +\begin_inset Flex Software +status open + +\begin_layout Plain Layout +GSL +\end_layout + +\end_inset + +) inside \begin_inset Formula $\binaryc$ \end_inset @@ -7402,386 +7398,253 @@ status open (which is what is in \begin_inset Flex Envvar status open - -\begin_layout Plain Layout -$HOME -\end_layout - -\end_inset - -), give you something like -\begin_inset listings -inline false -status open - -\begin_layout Plain Layout - --I/home/user/include -\end_layout - -\end_inset - -otherwise you should do something like -\family typewriter -\series bold - -\begin_inset listings -lstparams "language=bash" -inline false -status open - -\begin_layout Plain Layout - -export PATH=$HOME/bin:$PATH -\end_layout - -\end_inset - - -\family default -\series default -to force -\begin_inset Flex Command -status open - -\begin_layout Plain Layout -$HOME/bin/gsl-config -\end_layout - -\end_inset - - to run first. - -\end_layout - -\begin_layout Subsubsection -Extra libraries -\end_layout - -\begin_layout Standard -A number of external libraries can be used, particularly during debugging. - These include -\begin_inset Flex Software -status open - -\begin_layout Plain Layout -libiberty -\end_layout - -\end_inset - -, -\begin_inset Flex Software -status open - -\begin_layout Plain Layout -libbfd -\end_layout - -\end_inset - - (part of -\begin_inset Flex Software -status open - -\begin_layout Plain Layout -GCC -\end_layout - -\end_inset - -) and (if it does not come with your -\begin_inset Flex Software -status open - -\begin_layout Plain Layout -GCC -\end_layout - -\end_inset - -) -\begin_inset Flex Software -status open - -\begin_layout Plain Layout - -\emph off -libbacktrace -\end_layout - -\end_inset - -. - The latter is particularly useful, and I recommend installing it if you - want to do any serious debugging. - You can download -\begin_inset Flex Software -status open - -\begin_layout Plain Layout -libbacktrace -\end_layout - -\end_inset - - from -\begin_inset CommandInset href -LatexCommand href -name "https://github.com/ianlancetaylor/libbacktrace" -target "https://github.com/ianlancetaylor/libbacktrace" -literal "false" - -\end_inset - -. -\end_layout - -\begin_layout Subsubsection -Troubleshooting -\end_layout - -\begin_layout Itemize -If you see compilation errors like -\begin_inset listings -inline false -status open - -\begin_layout Plain Layout - -text segment at different address -\end_layout - -\end_inset - -you need to disable -\emph on -Address Space Layout Randomization -\emph default - (ASLR), see e.g. - -\begin_inset Flex URL -status open - -\begin_layout Plain Layout - -https://askubuntu.com/questions/318315/how-can-i-temporarily-disable-aslr-address --space-layout-randomization + +\begin_layout Plain Layout +$HOME \end_layout \end_inset - or run +), give you something like \begin_inset listings inline false status open \begin_layout Plain Layout -echo 0 | sudo tee /proc/sys/kernel/randomize_va_space +-I/home/user/include \end_layout \end_inset - (note: this requires root access) -\end_layout +otherwise you should do something like +\family typewriter +\series bold -\begin_layout Itemize -If you see errors like \begin_inset listings +lstparams "language=bash" inline false status open \begin_layout Plain Layout -libbinary_c_objects___src_tables.a(src_tables_table_novae.c.o): In function - `table_novae': +export PATH=$HOME/bin:$PATH \end_layout -\begin_layout Plain Layout - -/home/izzard/progs/stars/binary_c/builddir/../src/tables/table_novae.c:14: - undefined reference to `_binary_nucsyn_novae_JH98_CO_dat_start' -\end_layout +\end_inset -\begin_layout Plain Layout -/home/izzard/progs/stars/binary_c/builddir/../src/tables/table_novae.c:19: - undefined reference to `_binary_nucsyn_novae_JH98_ONe_dat_start' -\end_layout +\family default +\series default +to force +\begin_inset Flex Command +status open \begin_layout Plain Layout - -libbinary_c_objects___src_tables.a(src_tables_table_s_process.c.o): In function - `table_s_process': +$HOME/bin/gsl-config \end_layout -\begin_layout Plain Layout +\end_inset -/home/izzard/progs/stars/binary_c/builddir/../src/tables/table_s_process.c:32: - undefined reference to `_binary_nucsyn_extended_s_process_dat_start' + to run first. + \end_layout -\end_inset +\begin_layout Subsubsection +Extra libraries +\end_layout -this is because you have run +\begin_layout Standard +A number of external libraries can be used, particularly during debugging. + These include \begin_inset Flex Software status open \begin_layout Plain Layout -meson +libiberty \end_layout \end_inset - and built with +, \begin_inset Flex Software status open \begin_layout Plain Layout -ninja +libbfd \end_layout \end_inset - with -\begin_inset Flex CMacro + (part of +\begin_inset Flex Software status open \begin_layout Plain Layout -NUCSYN +GCC \end_layout \end_inset - undefined (in -\begin_inset Flex File +) and (if it does not come with your +\begin_inset Flex Software status open \begin_layout Plain Layout -binary_c_parameters.h +GCC \end_layout \end_inset -), then you have turned -\begin_inset Flex CMacro +) +\begin_inset Flex Software status open \begin_layout Plain Layout -NUCSYN + +\emph off +libbacktrace \end_layout \end_inset - on and tried to rebuild with +. + The latter is particularly useful, and I recommend installing it if you + want to do any serious debugging. + You can download \begin_inset Flex Software status open \begin_layout Plain Layout -ninja +libbacktrace \end_layout \end_inset - without rerunning -\begin_inset Flex Software -status open - -\begin_layout Plain Layout -meson -\end_layout + from +\begin_inset CommandInset href +LatexCommand href +name "https://github.com/ianlancetaylor/libbacktrace" +target "https://github.com/ianlancetaylor/libbacktrace" +literal "false" \end_inset . - You can probably solve the problem with -\begin_inset listings -lstparams "language=bash" -inline false -status open - -\begin_layout Plain Layout - -cd builddir \end_layout -\begin_layout Plain Layout +\begin_layout Subsubsection +Profile-guided builds +\begin_inset CommandInset label +LatexCommand label +name "subsec:Profile-guided-builds" -meson --reconfigure -\end_layout +\end_inset -\begin_layout Plain Layout -ninja \end_layout +\begin_layout Standard +Some compilers allow for profile-guided optimization (PGO). + +\begin_inset Formula $\binaryc$ \end_inset -or delete the -\begin_inset Flex File + has a script that wraps meson and ninja to allow you to do this automatically. + Run, from the +\begin_inset Formula $\binaryc$ +\end_inset + + root directory, +\begin_inset listings +inline false status open \begin_layout Plain Layout -builddir + +./meson/pgo.sh \end_layout \end_inset - and rerun -\begin_inset Flex Software +to do this. + This builds with PGO, running +\begin_inset Formula $\binaryc$ +\end_inset + + +\begin_inset Flex Args status open \begin_layout Plain Layout -meson +N \end_layout \end_inset - and -\begin_inset Flex Software + times to test the speed increase. + You can pass an integer value for +\begin_inset Flex Args status open \begin_layout Plain Layout -ninja +N \end_layout \end_inset -, e.g., + as the first argument of the script – more stars is more accurate, but + takes longer. +\end_layout + +\begin_layout Subsubsection +Troubleshooting +\end_layout + +\begin_layout Itemize +If you see compilation errors like \begin_inset listings -lstparams "language=bash" inline false status open \begin_layout Plain Layout -cd .. +text segment at different address \end_layout -\begin_layout Plain Layout +\end_inset -rm -r builddir -\end_layout +you need to disable +\emph on +Address Space Layout Randomization +\emph default + (ASLR), see e.g. + +\begin_inset Flex URL +status open \begin_layout Plain Layout -meson builddir +https://askubuntu.com/questions/318315/how-can-i-temporarily-disable-aslr-address +-space-layout-randomization \end_layout -\begin_layout Plain Layout +\end_inset -cd builddir -\end_layout + or run +\begin_inset listings +lstparams "language=bash" +inline false +status open \begin_layout Plain Layout -ninja +echo 0 | sudo tee /proc/sys/kernel/randomize_va_space \end_layout \end_inset - + (note: this requires root access) \end_layout \begin_layout Subsection @@ -7833,27 +7696,6 @@ tbse You should see some output. -\begin_inset Newline newline -\end_inset - -Note: You may have to symbolically link the executable to make this work. - You can do this manually by going into the builddir and running -\family typewriter -\series bold - -\begin_inset listings -lstparams "language=bash" -inline false -status open - -\begin_layout Plain Layout - -ninja binary_c_symlink -\end_layout - -\end_inset - - \end_layout \begin_layout Subsubsection @@ -7966,6 +7808,22 @@ debug This runs \end_inset +\emph default +with the gdb debugger +\end_layout + +\begin_layout Description +tbse +\begin_inset space ~ +\end_inset + +gdb This runs +\emph on + +\begin_inset Formula $\binaryc$ +\end_inset + + \emph default with the gdb debugger \end_layout @@ -8116,7 +7974,7 @@ Valgrind \emph on ptrcheck \emph default - tool. + tool (note: this tool no longer seems to exist). \end_layout \begin_layout Description @@ -8140,7 +7998,7 @@ Valgrind \emph on sgcheck \emph default - tool. + tool (note: this tool no longer seems to exist). \end_layout \begin_layout Description @@ -8249,7 +8107,11 @@ tbse \end_inset pgo Profile guided optimization. - This option is deprecated. + +\series bold +This option is deprecated. + +\series default Please use the \begin_inset Flex File status open @@ -8260,11 +8122,7 @@ meson/pgo.sh \end_inset - script instead (see -\begin_inset space ~ -\end_inset - -. + script instead. \end_layout \begin_layout Description @@ -21195,6 +21053,13 @@ valgrind \begin_layout Subsection How to debug memory leaks +\begin_inset CommandInset label +LatexCommand label +name "subsec:How-to-debug-memory-leaks" + +\end_inset + + \end_layout \begin_layout Standard @@ -21645,26 +21510,42 @@ How to build as a shared library \end_layout \begin_layout Standard -Easy, just execute -\family typewriter -\series bold - -\begin_inset listings -lstparams "language=bash" -inline false +The shared library is built by default when you install +\begin_inset Formula $\binaryc$ +\end_inset + + with +\begin_inset Flex Software status open \begin_layout Plain Layout +meson +\end_layout + +\end_inset + + and +\begin_inset Flex Software +status open -./make libbinary_c.so +\begin_layout Plain Layout +ninja \end_layout \end_inset +. + You will find libbinary_c.so in the +\begin_inset Flex File +status open -\family default -\series default - The API uses this shared library. +\begin_layout Plain Layout +src +\end_layout + +\end_inset + + subdirectory. \end_layout \begin_layout Subsection @@ -21703,26 +21584,6 @@ NUCSYN_GCE enabled, as well as the required physics \end_layout -\begin_layout Enumerate -You have to (re)build the shared library with -\family typewriter -\series bold - -\begin_inset listings -lstparams "language=bash" -inline false -status open - -\begin_layout Plain Layout - -make libbinary_c.so -\end_layout - -\end_inset - - -\end_layout - \begin_layout Enumerate You have to install the \begin_inset Flex Perlmodule diff --git a/doc/binary_c2.pdf b/doc/binary_c2.pdf index 3470f464a73fd082c38e20924828d9cc80a9ab8e..b5a434e412046a48b8de40fe8864f03bb8005266 100644 Binary files a/doc/binary_c2.pdf and b/doc/binary_c2.pdf differ diff --git a/doc/binary_grid_scaling.lyx b/doc/binary_grid_scaling.lyx index 235f86a66b95b3a84780f79f7334639f5bcc5ffc..8e58b462c12c35eda2583d748c8168c3c5f5183e 100644 --- a/doc/binary_grid_scaling.lyx +++ b/doc/binary_grid_scaling.lyx @@ -385,7 +385,10 @@ End \begin_layout Standard The binary_grid software is used to run binary_c, and other stellar evolution codes, on either a single CPU or a grid of machines, e.g. - with its +\begin_inset space ~ +\end_inset + +with its \begin_inset Flex Software status open diff --git a/doc/deprecated/DataStructures.pdf b/doc/deprecated/DataStructures.pdf deleted file mode 100644 index 27212ffa76ec3f13fb8b0a104f9ee38575be6fed..0000000000000000000000000000000000000000 Binary files a/doc/deprecated/DataStructures.pdf and /dev/null differ diff --git a/doc/deprecated/WARNING b/doc/deprecated/WARNING deleted file mode 100644 index 52a509e870297452b66a132f4b9ee54ebae9e2b6..0000000000000000000000000000000000000000 --- a/doc/deprecated/WARNING +++ /dev/null @@ -1 +0,0 @@ -The documentation in this folder, while useful, is unmaintained and may be out of date. You have been warned! \ No newline at end of file diff --git a/doc/deprecated/adding_a_variable.lyx b/doc/deprecated/adding_a_variable.lyx deleted file mode 100644 index 49ee28d37b0c1cce642ddaff8ef6a35ab5bd59d0..0000000000000000000000000000000000000000 Binary files a/doc/deprecated/adding_a_variable.lyx and /dev/null differ diff --git a/doc/deprecated/adding_a_variable.pdf b/doc/deprecated/adding_a_variable.pdf deleted file mode 100644 index 0d48c16f5be8231c26f74089a3d055db0e811788..0000000000000000000000000000000000000000 Binary files a/doc/deprecated/adding_a_variable.pdf and /dev/null differ diff --git a/doc/deprecated/binary_c_timesteps.lyx b/doc/deprecated/binary_c_timesteps.lyx deleted file mode 100644 index 3b1030759db7a770bf8f2999eafed338a796cccd..0000000000000000000000000000000000000000 --- a/doc/deprecated/binary_c_timesteps.lyx +++ /dev/null @@ -1,427 +0,0 @@ -#LyX 1.5.6 created this file. For more info see http://www.lyx.org/ -\lyxformat 276 -\begin_document -\begin_header -\textclass article -\language english -\inputencoding auto -\font_roman default -\font_sans default -\font_typewriter default -\font_default_family default -\font_sc false -\font_osf false -\font_sf_scale 100 -\font_tt_scale 100 -\graphics default -\paperfontsize default -\papersize default -\use_geometry false -\use_amsmath 1 -\use_esint 1 -\cite_engine basic -\use_bibtopic false -\paperorientation portrait -\secnumdepth 3 -\tocdepth 3 -\paragraph_separation indent -\defskip medskip -\quotes_language english -\papercolumns 1 -\papersides 1 -\paperpagestyle default -\tracking_changes false -\output_changes false -\author "" -\end_header - -\begin_body - -\begin_layout Standard -Timestepping -\end_layout - -\begin_layout Standard -\begin_inset Formula $dt_{r}$ -\end_inset - - is the remaining time -\end_layout - -\begin_layout Standard -iterate -\end_layout - -\begin_layout Itemize -skip_to_RLOF=FALSE, intpol=0 -\begin_inset Formula $\rightarrow$ -\end_inset - - -\end_layout - -\begin_deeper -\begin_layout Itemize -time is advanced by -\begin_inset Formula $dt_{m}$ -\end_inset - - -\end_layout - -\begin_layout Itemize -sets dtm from -\begin_inset Formula $dt_{mi,k}$ -\end_inset - - -\end_layout - -\begin_layout Itemize -\begin_inset Formula $dt_{mi,k}$ -\end_inset - - are set in acquire\SpecialChar \ldots{} - from deltat calls for each star -\end_layout - -\begin_layout Itemize -then in set_next_timestep -\begin_inset Formula $dt_{m}=\min\left[dt_{mi1},dt_{mi2},dtr\right]$ -\end_inset - - -\end_layout - -\begin_layout Itemize -if -\emph on -not interpolating -\emph default - then -\begin_inset Formula $dt_{m0}$ -\end_inset - - is set to -\begin_inset Formula $dt_{m}$ -\end_inset - - (this is important!) -\end_layout - -\end_deeper -\begin_layout Itemize -RLOF for first time executes the end of the skip_to_RLOF=FALSE code block, - including set_nuclear_timescale sets -\begin_inset Formula $k_{m0}=10^{3}dt_{m0}/P$ -\end_inset - - (i.e. - 1000 orbits are taken per timestep) -\end_layout - -\begin_layout Itemize -skip_to_RLOF=TRUE then RLOF (special_cases) is called. - If RLOF is -\begin_inset Quotes eld -\end_inset - -mass_transfer_in_one_kepler_orbit -\begin_inset Quotes erd -\end_inset - - -\end_layout - -\begin_deeper -\begin_layout Itemize -speed_up_factor calculates -\begin_inset Formula $k_{m}$ -\end_inset - - - the number of orbits per timestep, -\begin_inset Formula $k_{m}=\min\left[2k_{m0},\frac{5\times10^{-3}}{\max(f_{1},f_{2})}\right]$ -\end_inset - - where -\begin_inset Formula $f_{k}=\frac{dM_{k}}{M_{k}}$ -\end_inset - - and -\begin_inset Formula $dM_{k}$ -\end_inset - - is the mass change of star -\begin_inset Formula $k$ -\end_inset - - of mass -\begin_inset Formula $M_{k}$ -\end_inset - - -\end_layout - -\begin_layout Itemize -modify_timestep_and_mass_loss_by_speed_up_factor then does the following: -\end_layout - -\begin_deeper -\begin_layout Itemize -\begin_inset Formula $dt=k_{m}P$ -\end_inset - - -\end_layout - -\begin_layout Itemize -\begin_inset Formula $dt_{m}=\min\left(dt_{r},10^{-6}dt\right)$ -\end_inset - - -\end_layout - -\begin_layout Itemize -\begin_inset Formula $dt=10^{6}dt_{m}$ -\end_inset - - (i.e. - -\begin_inset Formula $dt$ -\end_inset - - is in -\emph on -years -\emph default -) -\end_layout - -\begin_layout Itemize -\begin_inset Formula $k_{m}^{\mbox{new}}=dt/P$ -\end_inset - - -\end_layout - -\end_deeper -\begin_layout Itemize -The net effect is -\begin_inset Formula $k_{m}^{\mbox{new}}=\min\left(10^{6}dt_{r},k_{m}P\right)/P$ -\end_inset - - (although -\begin_inset Formula $dt$ -\end_inset - - is set too and may be used elsewhere!) -\end_layout - -\begin_layout Itemize -Next the timestep -\begin_inset Formula $dt_{m}$ -\end_inset - - is calculated from the usual -\begin_inset Formula $dt_{m}=\min\left[dt_{mi1},dt_{mi2},dtr\right]$ -\end_inset - - and -\begin_inset Formula $dt=10^{6}dt_{m}$ -\end_inset - - -\end_layout - -\begin_layout Itemize -Then the new -\begin_inset Formula $k_{m}=dt/P=10^{6}dtm/P$ -\end_inset - - -\end_layout - -\begin_layout Itemize -The mass transferred in one timestep is then -\begin_inset Formula $k_{m}\dot{M}$ -\end_inset - - where -\begin_inset Formula $\dot{M}$ -\end_inset - - is the mass transfer rate (remodify_by_speedup_factor) -\end_layout - -\begin_layout Itemize -The orbit and masses are then updated and RLOF called again. -\end_layout - -\begin_layout Itemize -update_time update -\begin_inset Formula $t$ -\end_inset - - by -\begin_inset Formula $dt_{m}$ -\end_inset - - when in RLOF -\end_layout - -\end_deeper -\begin_layout Itemize -In contact_system in some cases -\begin_inset Formula $dt_{m}=0$ -\end_inset - - -\end_layout - -\begin_layout Itemize -initial_mass_loss: -\end_layout - -\begin_deeper -\begin_layout Itemize -Multiplies -\begin_inset Formula $dt_{m}$ -\end_inset - - by -\begin_inset Formula $M_{\mbox{env}}/dM_{s}$ -\end_inset - - where -\begin_inset Formula $dM_{s}=dt\times\dot{M}$ -\end_inset - - -\end_layout - -\begin_layout Itemize -Multiplies -\begin_inset Formula $dt_{m}$ -\end_inset - - by -\begin_inset Formula $0.01M/dM_{s}$ -\end_inset - - if -\begin_inset Formula $>1\%$ -\end_inset - - of the envelope would be removed -\end_layout - -\begin_layout Itemize -Sets -\begin_inset Formula $dt=10^{6}dt_{m}$ -\end_inset - - (i.e. - -\begin_inset Formula $dt$ -\end_inset - - is in years, -\begin_inset Formula $dt_{m}$ -\end_inset - - in Myr) -\end_layout - -\end_deeper -\begin_layout Itemize -limit_to_2percent_ang_mom_change sets -\begin_inset Formula $dt_{m}=10^{-6}dt$ -\end_inset - - (i.e. - wants -\begin_inset Formula $dt$ -\end_inset - - in years) -\end_layout - -\begin_layout Itemize -test_for_roche_lobe_overflow does the interpolation in time back to -\begin_inset Formula $R=R_{L}$ -\end_inset - - so sets -\begin_inset Formula $dt_{m}$ -\end_inset - - often ( -\begin_inset Formula $dt_{m}$ -\end_inset - - in Myr) -\end_layout - -\begin_layout Itemize -test_if_primary_fills_roche_lobe sets -\begin_inset Formula $dt_{m}=0$ -\end_inset - - when RLOF finishes -\end_layout - -\begin_layout Itemize -loop_iteration sets -\begin_inset Formula $dt_{m}=0$ -\end_inset - - in the case of mergers -\end_layout - -\begin_layout Itemize -post_roche_logging sets -\begin_inset Formula $dt_{m}=0$ -\end_inset - - in the case of supernovae -\end_layout - -\begin_layout Itemize -dynamical_comenv sets -\begin_inset Formula $dt_{m}=0$ -\end_inset - - in the case of a common envelope evolution -\end_layout - -\begin_layout Itemize -limit_mass_transfer_rate sets -\begin_inset Formula $dt_{m}=0$ -\end_inset - - in the case where -\begin_inset Formula $R>R_{\mbox{L}}$ -\end_inset - - (contact) -\end_layout - -\begin_layout Itemize -RLOF_mass_transfer_rate sets a local -\begin_inset Formula $dt$ -\end_inset - - to be -\begin_inset Formula $10^{6}dt_{m}$ -\end_inset - - i.e. - -\begin_inset Formula $dt$ -\end_inset - - in years -\end_layout - -\end_body -\end_document diff --git a/doc/deprecated/binary_c_timesteps.pdf b/doc/deprecated/binary_c_timesteps.pdf deleted file mode 100644 index ff20ebb217db55d8ab74d7001c7588fc8b6c901a..0000000000000000000000000000000000000000 Binary files a/doc/deprecated/binary_c_timesteps.pdf and /dev/null differ diff --git a/doc/deprecated/binary_grid-flexigrid.lyx b/doc/deprecated/binary_grid-flexigrid.lyx deleted file mode 100644 index 9a2e7c661ada837b3556569638f8a703c0d61ea4..0000000000000000000000000000000000000000 --- a/doc/deprecated/binary_grid-flexigrid.lyx +++ /dev/null @@ -1,13566 +0,0 @@ -#LyX 2.3 created this file. For more info see http://www.lyx.org/ -\lyxformat 544 -\begin_document -\begin_header -\save_transient_properties true -\origin unavailable -\textclass scrartcl -\begin_preamble -\usepackage{eulervm} -% bibliography stuff -\def\aj{Astronomical Journal} % Astronomical Journal -\def\araa{ARA\&A} % Annual Review of Astron and Astrophys -\def\apj{Astrophysical Journal} % Astrophysical Journal -\def\apjl{Astrophysical Journal, Letters} % Astrophysical Journal, Letters -\def\apjs{Astrophysical Journal, Supplement} % Astrophysical Journal, Supplement -\def\apss{Ap\&SS} % Astrophysics and Space Science -\def\aap{Astronomy and Astrophysics} % Astronomy and Astrophysics -\def\aapr{A\&A~Rev.} % Astronomy and Astrophysics Reviews -\def\aaps{A\&AS} % Astronomy and Astrophysics, Supplement -\def\mnras{Monthly Notices of the Royal Astronomical Society} % Monthly Notices of the RAS -\def\pra{Phys.~Rev.~A} % Physical Review A: General Physics -\def\prl{Phys.~Rev.~Lett.} % Physical Review Letters -\def\pasa{PASA} % Publications of the ASP -\def\pasp{PASP} % Publications of the ASP -\def\pasj{PASJ} % Publications of the ASJ -\def\nat{Nature} % Nature -\def\aplett{Astrophys.~Lett.} % Astrophysics Letters -\def\physrep{Phys.~Rep.} % Physics Reports% - - -\usepackage{listings} -\usepackage{natbibspacing} -\setlength{\bibspacing}{0mm} - - - - - - \usepackage[usenames,dvipsnames]{xcolor} -\usepackage{eurosym} -\usepackage{eulervm} -\usepackage{enumitem} -\usepackage{latexsym} -\usepackage{multicol} -\usepackage{setspace} -\date{} -\usepackage{tikz} -\usetikzlibrary{calc,shadings} - -%\usepackage[usenames, dvipsnames]{color} -\definecolor{Sectioncolour2}{RGB}{210,180,180} -\definecolor{Sectioncolour1}{RGB}{179,100,100} -\definecolor{Sectioncolour}{RGB}{159,29,35} - -% background - -%\usepackage{gradientframe} - -%\usepackage[pages=all,color=Sectioncolour,angle=90,hshift=-5cm,scale=1.5,contents={Nucleosynthesis in AGB Stars}]{background} - -%\usepackage{framed} -%\colorlet{shadecolor}{gray!25} % you may try 'blue' here -%\renewenvironment{leftbar}{% - % \def\FrameCommand{% -%{% -%\textcolor{Sectioncolour2}{\vrule width 2pt}% -%\textcolor{Sectioncolour1}{\vrule width 2pt}% -%\textcolor{Sectioncolour}{\vrule width 2pt}% -%\textcolor{Sectioncolour1}{\vrule width 2pt}% -%\textcolor{Sectioncolour2}{\vrule width 2pt}% -%}\hspace{10pt}}% -% \MakeFramed {\advance\hsize-\width \FrameRestore}}% -%{\endMakeFramed} - - -%\rule{0.4pt}{\textheight} - -% try this -%http://www.ctan.org/tex-archive/macros/latex/contrib/eso-pic/ -%http://stackoverflow.com/questions/2986240/latex-how-to-make-a-fullpage-vertical-rule-on-every-page - -\usepackage{eso-pic} -\usepackage{graphicx} -%\newcommand\BackgroundPic{} - -\newcommand\BackgroundPic{% -\put(0,0){% -\parbox[b][\paperheight]{\paperwidth}{% -\vfill -\centering -\includegraphics[width=\paperwidth,height=\paperheight,% -keepaspectratio]{images/falk2-low-lolores.eps}% -\vfill -}}} - -% remove background image (for speed) -%\renewcommand\BackgroundPic{} - -% redefine sections to use red colour -\usepackage{titlesec} -\titleformat{name=\section}% command to alter -{\color{Sectioncolour}\normalfont\itshape\bfseries\large\setstretch{0.5}}%format -{\thesection}%label -{1em}%sep -{}%before code -{}%after code - -% redefine subsections to use red colour -\titleformat{name=\subsection}% command to alter -{\color{Sectioncolour}\normalfont\itshape\bfseries\large\setstretch{0.5}}%format -{\thesubsection}%label -{1em}%sep -{}%before code -{}%after code - - -\def\aj{AJ} % Astronomical Journal -\def\araa{ARA\&A} % Annual Review of Astron and Astrophys -\def\apj{ApJ} % Astrophysical Journal -\def\apjl{ApJ} % Astrophysical Journal, Letters -\def\apjs{ApJS} % Astrophysical Journal, Supplement -\def\apss{Ap\&SS} % Astrophysics and Space Science -\def\aap{A\&A} % Astronomy and Astrophysics -\def\aapr{A\&A~Rev.} % Astronomy and Astrophysics Reviews -\def\aaps{A\&AS} % Astronomy and Astrophysics, Supplement -\def\mnras{MNRAS} % Monthly Notices of the RAS -\def\pra{Phys.~Rev.~A} % Physical Review A: General Physics -\def\prl{Phys.~Rev.~Lett.} % Physical Review Letters -\def\pasa{PASA} % Publications of the ASP -\def\pasp{PASP} % Publications of the ASP -\def\pasj{PASJ} % Publications of the ASJ -\def\nat{Nature} % Nature -\def\aplett{Astrophys.~Lett.} % Astrophysics Letters -\def\physrep{Phys.~Rep.} % Physics Reports% -\def\na{NewA} % new astronomy% - -\usepackage{natbibspacing} -\setlength{\bibspacing}{0mm} - -% header -\usepackage{fancyhdr} -\pagestyle{fancy} -\renewcommand{\headrulewidth}{0pt} -\fancyhead[LE,RO]{\color{Sectioncolour}\normalfont\itshape\bfseries{Flexigrid}} % page number in "outer" position of footer line -\fancyhead[RE,LO]{\color{Sectioncolour}\rightmark} % other info in "inner" position of footer line - -\raggedbottom -\end_preamble -\use_default_options true -\maintain_unincluded_children false -\language british -\language_package default -\inputencoding auto -\fontencoding global -\font_roman "default" "default" -\font_sans "helvet" "default" -\font_typewriter "beramono" "default" -\font_math "auto" "auto" -\font_default_family sfdefault -\use_non_tex_fonts false -\font_sc false -\font_osf false -\font_sf_scale 100 100 -\font_tt_scale 90 100 -\use_microtype false -\use_dash_ligatures true -\graphics default -\default_output_format default -\output_sync 0 -\bibtex_command default -\index_command default -\paperfontsize default -\spacing single -\use_hyperref true -\pdf_bookmarks true -\pdf_bookmarksnumbered false -\pdf_bookmarksopen false -\pdf_bookmarksopenlevel 1 -\pdf_breaklinks true -\pdf_pdfborder true -\pdf_colorlinks true -\pdf_backref false -\pdf_pdfusetitle true -\papersize default -\use_geometry true -\use_package amsmath 2 -\use_package amssymb 2 -\use_package cancel 1 -\use_package esint 1 -\use_package mathdots 1 -\use_package mathtools 1 -\use_package mhchem 1 -\use_package stackrel 1 -\use_package stmaryrd 1 -\use_package undertilde 1 -\cite_engine natbib -\cite_engine_type authoryear -\biblio_style plainnat -\use_bibtopic false -\use_indices false -\paperorientation portrait -\suppress_date false -\justification true -\use_refstyle 0 -\use_minted 0 -\index Index -\shortcut idx -\color #008000 -\end_index -\leftmargin 2cm -\topmargin 3cm -\rightmargin 2cm -\bottommargin 3cm -\secnumdepth 3 -\tocdepth 3 -\paragraph_separation indent -\paragraph_indentation default -\is_math_indent 0 -\math_numbering_side default -\quotes_style english -\dynamic_quotes 0 -\papercolumns 1 -\papersides 2 -\paperpagestyle fancy -\tracking_changes false -\output_changes false -\html_math_output 0 -\html_css_as_file 0 -\html_be_strict false -\end_header - -\begin_body - -\begin_layout Title -Binary_grid: Flexigrid -\end_layout - -\begin_layout Standard -\begin_inset ERT -status open - -\begin_layout Plain Layout - - -\backslash -vspace{-1cm} -\end_layout - -\end_inset - -Written by Robert Izzard, with greatly appreciated help from other users - of -\emph on -binary_grid -\emph default -and the -\emph on -flexigrid -\emph default -. -\end_layout - -\begin_layout Standard - -\series bold -The following documentation should work either with binary_c version 1.2x - or 2.x, although in version 2.x some of the variable names have been changed. -\end_layout - -\begin_layout Standard -\begin_inset CommandInset toc -LatexCommand tableofcontents - -\end_inset - - -\end_layout - -\begin_layout Standard -\begin_inset Newpage pagebreak -\end_inset - - -\end_layout - -\begin_layout Section -Introduction -\end_layout - -\begin_layout Standard -The -\emph on -binary_grid -\emph default - software has been developed over the last ten years or so by Robert Izzard - with help from many people around the world. - It is designed to work with the -\emph on -binary_c/nucsyn -\emph default - stellar evolution code, based on -\emph on -BSE -\emph default - of -\begin_inset CommandInset citation -LatexCommand citet -key "2002MNRAS_329_897H" -literal "true" - -\end_inset - -, but should work with any suitably prepared stellar evolution code. - In 2011 and 2012, the old -\emph on -binary_grid -\emph default - code has been replaced with the -\emph on -flexigrid -\emph default - – this document is the guide to the -\emph on -flexigrid -\emph default - version of software. - As of 2015, -\emph on -flexigrid -\emph default - works on multi-core PCs and distributed computing grids (e.g. - -\emph on -HTCondor -\emph default -). -\end_layout - -\begin_layout Standard -Before using -\emph on -binary_grid -\emph default - please note that it is subject to the -\emph on -binary_c -\emph default - licence file which is included with binary_c, the only difference being - that while -\emph on -binary_c -\emph default - is based on -\emph on -BSE -\emph default -, -\emph on -binary_grid -\emph default - is entirely Robert Izzard's creation. - As stated in the licence, appropriate citations (e.g. - -\begin_inset CommandInset citation -LatexCommand citealp -key "Izzard_et_al_2003b_AGBs" -literal "true" - -\end_inset - -, -\begin_inset CommandInset citation -LatexCommand citealp -key "2006A&A...460..565I" -literal "true" - -\end_inset - - and -\begin_inset CommandInset citation -LatexCommand citealp -key "2009A&A...508.1359I" -literal "true" - -\end_inset - -) are -\emph on -mandatory -\emph default - if you publish work which uses -\emph on -binary_grid -\emph default - or -\emph on -binary_c -\emph default -, and co-authorship is an option which should be considered. - Please remember that the amount of work that has gone into this project, - especially at weekends and during holiday time, is quite considerable: - give credit where it is due and help Rob to get another job! -\end_layout - -\begin_layout Standard -Frequently Asked Questions are in Section -\begin_inset space ~ -\end_inset - - -\begin_inset CommandInset ref -LatexCommand ref -reference "sec:FAQ" - -\end_inset - - and installation instructions are given in Section -\begin_inset space ~ -\end_inset - - -\begin_inset CommandInset ref -LatexCommand ref -reference "sec:installation" - -\end_inset - -. -\end_layout - -\begin_layout Standard -It is up to you to test and debug this code because, as with all codes, - it is not perfect and probably does not do what you would like it to do - without some tweaking. - You can contact Robert Izzard via his website -\begin_inset CommandInset href -LatexCommand href -target "http://www.ast.cam.ac.uk/~rgi/" -literal "false" - -\end_inset - - (which gives an email address) or use the -\emph on -binary_c -\emph default -mailing lists: -\end_layout - -\begin_layout Itemize -binary_c-nucsyn-announce@googlegroups.com at -\begin_inset Newline newline -\end_inset - - -\begin_inset CommandInset href -LatexCommand href -target "https://groups.google.com/forum/?fromgroups=#!forum/binary_c-nucsyn-announce" -literal "false" - -\end_inset - - -\end_layout - -\begin_layout Itemize -binary_c-nucsyn-devel@googlegroups.com at -\begin_inset Newline newline -\end_inset - - -\begin_inset CommandInset href -LatexCommand href -target "https://groups.google.com/forum/?fromgroups=#!forum/binary_c-nucsyn-devel" -literal "false" - -\end_inset - - -\end_layout - -\begin_layout Itemize -Facebook page at -\begin_inset Newline newline -\end_inset - - -\begin_inset CommandInset href -LatexCommand href -target "https://www.facebook.com/groups/149489915089142/?fref=ts" -literal "false" - -\end_inset - - -\end_layout - -\begin_layout Section -Aims: what the grid does and why -\end_layout - -\begin_layout Standard -\begin_inset CommandInset label -LatexCommand label -name "sec:aims" - -\end_inset - -Binary population synthesis is a glorified form of accountancy, without - the huge pay but with of course much more fun! It involves modelling perhaps - millions of binary stars in a population to pick out those few that contribute - to the population of scientific interest. - The rate of formation, or number of these stars, or some other property - of them can then be examined in a -\emph on -quantitative -\emph default - and -\emph on -statistical -\emph default - manner. - This manual explains how the -\emph on -binary_grid -\emph default -module – part of the -\emph on -binary_c/nucsyn -\emph default - code package – can be used to model populations of single and binary stars. - -\end_layout - -\begin_layout Standard -For details about the binary stellar evolution code -\emph on -binary_c/nucsyn -\emph default - please see the nucsyn_manual document. - This guide is -\emph on -only -\emph default - concerned with the details of running grids of models, not about the details - of the models themselves. -\end_layout - -\begin_layout Subsection -Grid dimensions -\begin_inset CommandInset label -LatexCommand label -name "subsec:Grid-dimensions" - -\end_inset - - -\end_layout - -\begin_layout Standard -There are many parameters which can be set before running a stellar model. - The most important, for single stars, are the stellar mass -\begin_inset Formula $M$ -\end_inset - - and metallicity -\begin_inset Formula $Z$ -\end_inset - -. - It is common to set the metallicity -\begin_inset Formula $Z$ -\end_inset - - to be constant and vary the initial stellar mass -\begin_inset Formula $M$ -\end_inset - -. - In everything that follows I will assume you are working at a constant - metallicity -\begin_inset Formula $Z$ -\end_inset - -. - -\end_layout - -\begin_layout Standard -The situation is more complicated in binaries because instead of just -\begin_inset Formula $M$ -\end_inset - - there are two stellar masses -\begin_inset Formula $M_{1}$ -\end_inset - - and -\begin_inset Formula $M_{2}$ -\end_inset - -, the separation -\begin_inset Formula $a$ -\end_inset - - (or, equivalently, the period -\begin_inset Formula $P$ -\end_inset - -) and perhaps the eccentricity -\begin_inset Formula $e$ -\end_inset - -. - To run a population of binary stars then requires a grid of models in four - dimensions. - Often the eccentricity is ignored because close binaries – which are the - ones in which you may be interested – tend to circularise rapidly. - This reduces the problem to three dimensions. -\end_layout - -\begin_layout Standard -The number of stars on each side of the grid, i.e. - the -\emph on -resolution -\emph default - -\begin_inset Formula $n$ -\end_inset - -, roughly determines the total runtime of your simulation. - In single stars this is just -\begin_inset Formula $\Delta t\times n$ -\end_inset - -, where one model takes a time -\begin_inset Formula $\Delta t$ -\end_inset - - to run. - In the case of binaries on a three-dimensional grid, this increases to - -\begin_inset Formula $\Delta t\times n^{3}$ -\end_inset - - (see Fig. -\begin_inset space ~ -\end_inset - - -\begin_inset CommandInset ref -LatexCommand ref -reference "fig:grid-size" - -\end_inset - -). - In a typical population -\begin_inset Formula $n\sim100$ -\end_inset - - so the total runtime increases by a factor of -\begin_inset Formula $100^{2}=10^{4}$ -\end_inset - -. - This ignores the increase in -\begin_inset Formula $\Delta t$ -\end_inset - - for binaries which is unavoidable because there are two stars under considerati -on as well as smaller timesteps during mass transfer. - It is for this reason that the -\emph on -binary_c/nucsyn -\emph default - code (and its BSE ancestor) must be – and is – fast. - It can run a population of -\begin_inset Formula $10^{6}$ -\end_inset - - binaries in less than -\begin_inset Formula $24\,\mathrm{CPU\,hours}$ -\end_inset - -. - -\begin_inset Float figure -wide false -sideways false -status open - -\begin_layout Plain Layout -\begin_inset Graphics - filename binary_grid_images/m1_cuboid.ps - lyxscale 10 - scale 30 - rotateAngle 270 - -\end_inset - - -\begin_inset Graphics - filename binary_grid_images/m1_m2_a_cuboid.ps - lyxscale 10 - scale 30 - rotateAngle 270 - -\end_inset - - -\end_layout - -\begin_layout Plain Layout -\begin_inset Caption Standard - -\begin_layout Plain Layout -\begin_inset CommandInset label -LatexCommand label -name "fig:grid-size" - -\end_inset - -The relative size of the single- and binary-star grids. - In single stars only one mass is required, -\begin_inset Formula $M_{1}$ -\end_inset - -, while in binaries the two masses -\begin_inset Formula $M_{1}$ -\end_inset - - and -\begin_inset Formula $M_{2}$ -\end_inset - - and separation are needed. - For a grid resolution of -\begin_inset Formula $n=100$ -\end_inset - -, the runtime for the single stars (left cuboid) is -\begin_inset Formula $100\times\Delta t$ -\end_inset - -, where -\begin_inset Formula $\Delta t$ -\end_inset - - is the runtime for one stellar system. - In binaries (right cuboid) this increases to at least -\begin_inset Formula $10^{6}\times\Delta t$ -\end_inset - - because of the extra grid dimensions. - In addition, -\begin_inset Formula $\Delta t$ -\end_inset - - will be longer for binaries because of the short timesteps required during - some phases of mass transfer, the fact that there are two stars to follow - in the evolution/nucleosynthesis algorithms and extra overhead from logging - and parsing output from both stars. - Typically, -\begin_inset Formula $\Delta t\sim0.1\,\mbox{s}$ -\end_inset - - on a -\begin_inset Formula $3\,\mbox{Ghz}$ -\end_inset - - PC. -\end_layout - -\end_inset - - -\end_layout - -\begin_layout Plain Layout - -\end_layout - -\end_inset - - -\end_layout - -\begin_layout Subsection -What to do with the grid -\begin_inset CommandInset label -LatexCommand label -name "subsec:What-to-do" - -\end_inset - - -\end_layout - -\begin_layout Standard -What do we do once the grid of stars is set up? In most cases this involves - adding up some statistics related to each star on the grid. - There are two approaches which are commonly used, constant star formation - and a starburst. - The one that suits you depends on what you are trying to calculate and - to which observations you hope to compare. -\end_layout - -\begin_layout Subsubsection -Constant star formation rate -\end_layout - -\begin_layout Standard -In this case the formation rate or (perhaps -\begin_inset Formula $\delta t$ -\end_inset - --weighted) probabilities for each star corresponding to those in which you - are interested are simply added up. - This is why I say it is like accountancy! Because the rate of star formation - is assumed to be -\emph on -constant -\emph default - the evolution time of the stellar evolution is irrelevant. - A hybrid scheme can also be used, you might only consider stars older than - a given age (e.g. - for halo stars). -\end_layout - -\begin_layout Subsubsection -Starburst -\end_layout - -\begin_layout Standard -All stars form at time zero and you add up the (probably -\begin_inset Formula $\delta t$ -\end_inset - --weighted) number of stars in which you are interested which form or exist - in each time bin. - A good example is the delay-time distribution of type Ia supernovae. -\begin_inset Newline newline -\end_inset - - -\end_layout - -\begin_layout Standard -The statistic you wish to add up is usually output from -\emph on -binary_c/nucsyn. - -\emph default -Your -\begin_inset Quotes eld -\end_inset - -grid script -\begin_inset Quotes erd -\end_inset - - runs each star in your population, takes the output of -\emph on -binary_c/nucsyn -\emph default - and adds up the statistic. - You can generate single numbers, histograms or arbitrarily complicated - statistical constructs for comparison with observations. - You can choose whether to do the calculations on the fly or save the progenitor - information for later data processing. -\end_layout - -\begin_layout Standard -The grid script can be used on multi-CPU machines and handles the administrative - issues regarding parallel processing. -\end_layout - -\begin_layout Standard -\begin_inset Newpage pagebreak -\end_inset - - -\end_layout - -\begin_layout Section -Grid setup (in theory) -\end_layout - -\begin_layout Standard -\begin_inset CommandInset label -LatexCommand label -name "sec:grid-setup-theory" - -\end_inset - -This section presents the -\emph on -theory -\emph default - behind the setup of a grid in -\begin_inset Formula $M$ -\end_inset - -, for single stars, or -\begin_inset Formula $M_{1}$ -\end_inset - -, -\begin_inset Formula $M_{2}$ -\end_inset - - and -\begin_inset Formula $a$ -\end_inset - - for binary stars. - In general a -\emph on -logarithmic -\emph default - spacing is chosen for the mass grid because the important relevant physical - processes are -\begin_inset Quotes eld -\end_inset - -more different -\begin_inset Quotes erd -\end_inset - - for the mass range -\begin_inset Formula $1-10\,\mathrm{M}_{\odot}$ -\end_inset - - than between -\begin_inset Formula $10-100\,\mathrm{M}_{\odot}$ -\end_inset - -. - This is rather subjective but you can chose the bounds of your grid to - reflect the stars in which your interest lies. -\end_layout - -\begin_layout Standard -Each star in the grid represents a -\emph on -phase volume -\emph default -. - This means that a star of mass -\begin_inset Formula $M$ -\end_inset - - represents stars which, in reality, have masses -\begin_inset Formula $M-\delta M/2$ -\end_inset - - to -\begin_inset Formula $M+\delta M/2$ -\end_inset - -, where -\begin_inset Formula $\delta M$ -\end_inset - - is the grid spacing. - In an ideal world -\begin_inset Formula $\delta M$ -\end_inset - - would be very small, so our simulations match reality as closely as possible. - However, this is not usually possible if the grid is to run in a reasonable - amount of time (before funding runs out). - The usual way around this is to 1) be clever and/or 2) use a brute-force - approach where the resolution is increased (in this case -\begin_inset Formula $\delta M$ -\end_inset - - decreased) until your -\begin_inset Quotes eld -\end_inset - -answer -\begin_inset Quotes erd -\end_inset - - converges. -\end_layout - -\begin_layout Standard -One concept which must be grasped is that the bounds of the -\emph on -grid -\emph default - are not necessarily the bounds of the -\emph on -initial distributions -\emph default - you will be using (e.g. - the initial mass function, IMF). - This is a critical point which can lead to confusion, it is best explained - with an example. - Say you wish to calculate the ratio of type II to type Ib/c supernovae. - You would do this by adding up the number of stars that explode as type - IIs and divide by the number of stars that explode as type Ib/cs. - You -\emph on -could -\emph default - do this with a grid from -\begin_inset Formula $0.1$ -\end_inset - - to -\begin_inset Formula $100\,\mathrm{M}_{\odot}$ -\end_inset - - and, given enough stars, you would come up with the correct answer. - This is easy for single stars, because -\begin_inset Formula $10^{4}$ -\end_inset - - single stars are easily run on a modern PC. - However, for binaries this is difficult, because even with only -\begin_inset Formula $100$ -\end_inset - - stars in the -\begin_inset Formula $M_{2}$ -\end_inset - - and -\begin_inset Formula $a$ -\end_inset - - dimensions, there would be -\begin_inset Formula $10^{8}$ -\end_inset - - stars in your simulation and the runtime would be huge. - You can, however, be smarter and reduce the grid bounds and resolution. - You know in advance that at solar metallicity ( -\begin_inset Formula $Z=0.02$ -\end_inset - -) type II and Ib/c supernovae occur in -\emph on -single stars -\emph default - with -\begin_inset Formula $M\gtrsim8\mathrm{M}_{\odot}$ -\end_inset - -. - If you choose -\begin_inset Formula $M_{1}$ -\end_inset - - to run between (say) -\begin_inset Formula $4$ -\end_inset - - and -\begin_inset Formula $100\,\mathrm{M}_{\odot}$ -\end_inset - - you know you will record the supernovae from mass transfer (as -\begin_inset Formula $M_{2}\le M_{1}$ -\end_inset - - so the minimum mass of merged stars is the required -\begin_inset Formula $8\,\mathrm{M}_{\odot}$ -\end_inset - -) as well as all the others at higher masses. - So, you will get the -\emph on -same answer -\emph default - from a grid between -\begin_inset Formula $4$ -\end_inset - - and -\begin_inset Formula $100\,\mathrm{M}_{\odot}$ -\end_inset - - as with a grid between -\begin_inset Formula $0.1$ -\end_inset - - and -\begin_inset Formula $100\,\mathrm{M}_{\odot}$ -\end_inset - -. - Note that the -\emph on -grid -\emph default - has changed, but the result has not. - This is because the initial distributions have fixed bounds independent - of the grid bounds. - See Section -\begin_inset space ~ -\end_inset - - -\begin_inset CommandInset ref -LatexCommand ref -reference "sec:initial-dists" - -\end_inset - - for more details on initial distributions. - -\end_layout - -\begin_layout Standard -This process requires some knowledge in advance, which you may not have. - In that case, run a low resolution grid, find suitable grid bounds and - then repeat at higher resolution until you are happy. - The downside to the process is that you may well miss small parts of the - parameter space which contain interesting systems. - In practice this is often a compromise worth making and, if in doubt, test - your model runs at low resolution but then crank the resolution to the - maximum you think is possible for the final model run. -\end_layout - -\begin_layout Standard -Another advantage of choosing the grid bounds is that sub-grids can be run - on different computers or CPU cores and the results combined. - This is discussed further in Section -\begin_inset space ~ -\end_inset - - -\begin_inset CommandInset ref -LatexCommand ref -reference "sec:The-Thread-Model" - -\end_inset - -. -\end_layout - -\begin_layout Subsection -Phase Volume -\end_layout - -\begin_layout Standard -\begin_inset CommandInset label -LatexCommand label -name "subsec:phase-volume" - -\end_inset - -Given a chosen set of these distributions a logarithmic grid is set up in - one-dimensional -\begin_inset Formula $M$ -\end_inset - - space for single stars or 3D -\begin_inset Formula $M_{1}$ -\end_inset - -– -\begin_inset Formula $M_{2}$ -\end_inset - -– -\begin_inset Formula $a$ -\end_inset - - space for binary stars. - The grid is split into -\begin_inset Formula $n$ -\end_inset - - stars per dimension such that each star represents the centre of a logarithmic - grid-cell of size -\begin_inset Formula $\delta V$ -\end_inset - - where -\end_layout - -\begin_layout Standard -\begin_inset Formula -\begin{equation} -\delta V=\left\{ \begin{array}{cc} -\delta\ln M & \textrm{single stars}\\ -\delta\ln M_{1}\,\delta\ln M_{2}\,\delta\ln a & \textrm{binary stars} -\end{array}\right. -\end{equation} - -\end_inset - -and -\begin_inset Formula -\begin{equation} -\delta\ln x=\frac{\ln x_{\textrm{max}}-\ln x_{\textrm{min}}}{n}\,, -\end{equation} - -\end_inset - -where -\begin_inset Formula $x$ -\end_inset - - represents -\begin_inset Formula $M$ -\end_inset - -, -\begin_inset Formula $M_{1}$ -\end_inset - -, -\begin_inset Formula $M_{2}$ -\end_inset - - or -\begin_inset Formula $a$ -\end_inset - - and -\begin_inset Formula $x_{\textrm{max}}$ -\end_inset - - and -\begin_inset Formula $x_{\textrm{min}}$ -\end_inset - - are the grid limits. - The total number of stars is denoted by -\begin_inset Formula $N$ -\end_inset - - such that -\begin_inset Formula $N=n$ -\end_inset - - for single stars and -\begin_inset Formula $N=n^{3}$ -\end_inset - - for binary stars. -\end_layout - -\begin_layout Standard -The probability of existence of star -\begin_inset Formula $i$ -\end_inset - - is given by -\end_layout - -\begin_layout Standard -\begin_inset Formula -\begin{equation} -\delta p_{i}=\Psi\delta V_{i}=\Psi\delta V\,, -\end{equation} - -\end_inset - -because -\begin_inset Formula $\delta V$ -\end_inset - - is a constant. - The function -\begin_inset Formula $\Psi$ -\end_inset - - is discussed in Section -\begin_inset space ~ -\end_inset - - -\begin_inset CommandInset ref -LatexCommand ref -reference "sec:initial-dists" - -\end_inset - -. - -\end_layout - -\begin_layout Standard -The probability, -\begin_inset Formula $\delta p_{i}$ -\end_inset - -, is sometimes the quantity you wish to add up, although commonly you want - -\begin_inset Formula $\delta p_{\mathrm{i}}\times\delta t$ -\end_inset - - where -\begin_inset Formula $\delta t$ -\end_inset - - is the time spent in the phase of interest. - This is usually the case when comparing the number of stars which go through - a particular phase of evolution because the -\emph on -time -\emph default -in the phase of evolution is as important as the -\emph on -probability -\emph default - of the star existing in the first place. - -\emph on - -\emph default -However, for -\emph on -event rates -\emph default - (e.g. - supernovae) the time involved is zero, they are instantaneous events on - a stellar evolution timescale, so you have to sum up the -\begin_inset Formula $\delta p_{i}$ -\end_inset - -. - You have to be careful to calculate the appropriate statistics for comparison - with the observations. -\end_layout - -\begin_layout Subsection -Grid loops -\end_layout - -\begin_layout Standard -\begin_inset CommandInset label -LatexCommand label -name "subsec:grid-loops" - -\end_inset - -In binary systems, the secondary mass -\begin_inset Formula $M_{2}$ -\end_inset - - typically depends on the primary mass -\begin_inset Formula $M_{1}$ -\end_inset - -, and the separation, -\begin_inset Formula $a$ -\end_inset - -, or period -\begin_inset Formula $P$ -\end_inset - -, may depend on both. - This means that usually the grid must be constructed in a series of nested - loops: -\end_layout - -\begin_layout Standard -\begin_inset Formula -\begin{equation} -{\displaystyle \sum}_{M_{1}=M_{\mathrm{1,min}}}^{M_{1,\mathrm{max}}}\left(\sum_{M_{2}=M_{2}}^{M_{2\mathrm{,max}}}\left\{ \sum_{a=a_{\mathrm{min}}}^{a_{\mathrm{max}}}\left[\dots\right]\right\} \right)\,.\label{eq:grid-loops} -\end{equation} - -\end_inset - -In the most grids, -\begin_inset Formula $M_{2}$ -\end_inset - - depends on -\begin_inset Formula $M_{1}$ -\end_inset - - through the mass-ratio, -\begin_inset Formula $q=M_{2}/M_{1}$ -\end_inset - -, distribution. - The default mass-ratio distribution is flat in -\begin_inset Formula $q$ -\end_inset - - (see Section -\begin_inset space ~ -\end_inset - - -\begin_inset CommandInset ref -LatexCommand ref -reference "sec:initial-dists" - -\end_inset - -), with -\begin_inset Formula $0.1\,\mathrm{M}_{\odot}\leq M_{2}\leq M_{1}$ -\end_inset - -. - The period or separation distribution may also depend on -\begin_inset Formula $M_{1}$ -\end_inset - - and -\begin_inset Formula $M_{2}$ -\end_inset - -. -\end_layout - -\begin_layout Subsection -Resolution -\end_layout - -\begin_layout Standard -\begin_inset CommandInset label -LatexCommand label -name "subsec:resolution" - -\end_inset - -The choice of grid resolution depends very much on the problem you wish - to address and what you are trying to calculate. - As a general rule, assuming you are modelling stars from -\begin_inset Formula $M_{\mathrm{min}}=0.1\,\mathrm{M}_{\odot}$ -\end_inset - - to -\begin_inset Formula $M_{\mathrm{max}}=100\,\mathrm{M}_{\odot}$ -\end_inset - - you probably want at least -\begin_inset Formula $100$ -\end_inset - - stars in the -\begin_inset Formula $M$ -\end_inset - - (or -\begin_inset Formula $M_{1}$ -\end_inset - -) dimension. - -\end_layout - -\begin_layout Standard -However, before rushing off to run millions of stars, run some low-resolution - test models and gradually increase the number of stars. - The best way to determine the required resolution is simply the brute force - method: keep increasing the resolution until your answers converge. -\end_layout - -\begin_layout Standard -You can roughly estimate the -\emph on -statistical -\emph default -error by counting the number of stars that satisfy your criterion (say -\begin_inset Formula $k$ -\end_inset - - stars) and then use Poisson statistics (i.e. - the error on a value -\begin_inset Formula $x$ -\end_inset - - is -\begin_inset Formula $x/\sqrt{k}$ -\end_inset - -). - -\series bold -Be warned that this is -\emph on -not -\emph default - the error due to the use of a grid. - -\series default - If your data calculation binning is -\emph on -over -\emph default --resolved you may see problems with artefacts and aliasing. - These may or may not affect your results. - If in doubt, increase the resolution until the problem goes away (if it - goes away!). - In some cases this may not be possible because your computer is not fast - enough. - You could always buy a time machine\SpecialChar ldots - but then you wouldn't be doing astrophysics -! -\end_layout - -\begin_layout Standard -Overall resolution is often not your only concern: perhaps you want more - stars in a certain region of the parameter space. - Well, with the flexigrid and its spacing_functions module you can define - your own grid spacing function which as flexible as you like (see Sections -\begin_inset space ~ -\end_inset - - -\begin_inset CommandInset ref -LatexCommand ref -reference "sec:flexigrid" - -\end_inset - - and -\begin_inset CommandInset ref -LatexCommand ref -reference "sec:The-spacing_functions-module" - -\end_inset - -). - -\end_layout - -\begin_layout Standard -\begin_inset Newpage pagebreak -\end_inset - - -\end_layout - -\begin_layout Section -Data parsing (Accountancy without the salary) -\end_layout - -\begin_layout Standard -\begin_inset CommandInset label -LatexCommand label -name "sec:data-parsing" - -\end_inset - - Before you actually run your own population synthesis grid you have to - think about what you want to discover from your stellar models. - A few standard cases are outlined here. - You may, of course, want a combination of all these methods. -\end_layout - -\begin_layout Standard -This section describes the theory, the practical aspects of combining -\emph on -binary_c/nucsyn -\emph default - with your grid script are described in the following, e.g. - Section -\begin_inset space ~ -\end_inset - - -\begin_inset CommandInset ref -LatexCommand ref -reference "sec:grid.pl" - -\end_inset - -. -\end_layout - -\begin_layout Subsection -Rates of things -\end_layout - -\begin_layout Standard -\begin_inset CommandInset label -LatexCommand label -name "subsec:rates-of-things" - -\end_inset - -The simplest thing to calculate is the rate of formation of some type of - star, or alternatively the rate of stellar death (e.g. - the supernova rate), merger rate, etc. - These are -\emph on -events -\emph default -which have no duration so the important thing to log is the -\emph on -time at which the event happened -\emph default -, -\emph on - -\begin_inset Formula $t_{i}$ -\end_inset - - -\emph default -, and -\emph on -the probability of existence of the stellar system, -\emph default - -\begin_inset Formula $p_{i}$ -\end_inset - -. -\end_layout - -\begin_layout Standard -You will probably want to count the number of systems that explode in a - given time bin, i.e. - between time -\begin_inset Formula $t$ -\end_inset - - and -\begin_inset Formula $t+\Delta t$ -\end_inset - -, where -\begin_inset Formula $\Delta t$ -\end_inset - - is the time bin width ( -\emph on -not -\emph default - the -\emph on -binary_c/nucsyn -\emph default - timestep!). - The formation rate is the product of the star formation rate -\begin_inset Formula $S$ -\end_inset - - and the summed probability of the stars that do whatever it is that is - interesting in time -\begin_inset Formula $t$ -\end_inset - - to -\begin_inset Formula $t+\Delta t$ -\end_inset - -, -\begin_inset Formula $\sum p_{i}$ -\end_inset - -. - You have to somehow calculate -\begin_inset Formula $S$ -\end_inset - - (see e.g. - -\begin_inset CommandInset citation -LatexCommand citealp -key "2002MNRAS_329_897H" -literal "true" - -\end_inset - - for a simple prescription). - You would be better comparing the relative rates of two types of event, - in which case -\begin_inset Formula $S$ -\end_inset - - (and its associated uncertainty) cancels out. -\end_layout - -\begin_layout Standard -This is all correct for a starburst at time -\begin_inset Formula $t=0$ -\end_inset - -. - If you want to use a more realistic star formation history with varying - metallicity you have to convolve the results of many starbursts. - You can do this manually (and it is easy if, say, the metallicity and other - physics is not a function of -\begin_inset Formula $t$ -\end_inset - -) or use a pre-existing code such as Rob's Galactic Chemical Evolution (GCE) - code. - The latter has the advantage that it already exists and is well tested. - You will, however, have to ask Rob about it because it is not (yet) a part - of the standard -\emph on -binary_c/nucsyn -\emph default - distribution. - -\end_layout - -\begin_layout Subsection -Numbers of things -\end_layout - -\begin_layout Standard -\begin_inset CommandInset label -LatexCommand label -name "subsec:numbers-of-things" - -\end_inset - - -\end_layout - -\begin_layout Standard -Alternatively, perhaps you wish to calculate the number of stars of a certain - type e.g. - the number of carbon stars or the number of K-type stars. - In this case you have to count both the probability of the existence of - the star -\begin_inset Formula $p_{i}$ -\end_inset - - and the time the star spends in the evolutionary phase of interest. - If we assume -\begin_inset Formula $S=1$ -\end_inset - - (i.e. - constant star formation) you should then count -\begin_inset Formula $\sum p_{i}\,\delta t\,\bar{\delta}$ -\end_inset - - where -\begin_inset Formula $\bar{\delta}=1$ -\end_inset - - if the star is interesting to you, but zero otherwise. -\end_layout - -\begin_layout Standard -As in the previous example, if -\begin_inset Formula $S$ -\end_inset - - is not simply a constant things get tricky. - But usually a constant star formation rate is -\begin_inset Quotes eld -\end_inset - -good enough -\begin_inset Quotes erd -\end_inset - - for e.g. - Galactic stellar population studies of anything but the youngest stars. - In other cases a starburst is more appropriate and you will have to factor - in a check on the time -\begin_inset Formula $t$ -\end_inset - - into -\begin_inset Formula $\bar{\delta}$ -\end_inset - - to match the present-day age of the population. - -\end_layout - -\begin_layout Standard -\begin_inset Newpage pagebreak -\end_inset - - -\end_layout - -\begin_layout Section -Grid setup (in practice: the -\emph on -flexigrid -\emph default -) -\end_layout - -\begin_layout Standard -\begin_inset CommandInset label -LatexCommand label -name "sec:grid-setup-practice" - -\end_inset - -The grid is set up by use of a Perl module called -\emph on -binary_grid -\emph default -. - This is available with -\emph on -binary_c/nucsyn -\emph default - in the -\emph on -src/perl/modules -\emph default - directory (see also the -\emph on -binary_c/nucsyn -\emph default - manual). - -\emph on -binary_grid -\emph default -uses a number of secondary modules as well as some standard (CPAN) Perl - modules. - -\end_layout - -\begin_layout Standard -The newest version of -\emph on -binary_grid -\emph default - uses the -\emph on -flexigrid. - -\emph default - For details on this part of the grid, see Section -\begin_inset space ~ -\end_inset - - -\begin_inset CommandInset ref -LatexCommand ref -reference "sec:flexigrid" - -\end_inset - -. -\end_layout - -\begin_layout Subsection -Your -\emph on -grid script -\end_layout - -\begin_layout Standard -You load the -\emph on -binary_grid -\emph default - Perl module from your -\emph on -grid -\emph default - -\emph on -script -\emph default - (see Sec. -\begin_inset space ~ -\end_inset - - -\begin_inset CommandInset ref -LatexCommand ref -reference "sec:grid.pl" - -\end_inset - - for full details). - This is a -\emph on -Perl -\emph default - script which contains the definition of both your population synthesis - grid and your input physics. - Do not make this yourself: instead, use the example scripts in the -\emph on -src/perl/scripts-flexigrid -\emph default - directory of the -\emph on -binary_c/nucsyn -\emph default - tree and modify them appropriately (Sec. -\begin_inset space ~ -\end_inset - - -\begin_inset CommandInset ref -LatexCommand ref -reference "sec:grid.pl" - -\end_inset - -). - The most appropriate starting place is -\begin_inset Newline newline -\end_inset - - -\family typewriter -src/perl/scripts-flexigrid/grid-flexigrid.pl -\family default - -\begin_inset Newline newline -\end_inset - -which is a very basic grid that can be adapted. -\end_layout - -\begin_layout Subsection -The -\emph on -binary_grid -\emph default - Perl Module -\end_layout - -\begin_layout Standard -\begin_inset CommandInset label -LatexCommand label -name "subsec:the binary_grid perl module" - -\end_inset - - -\end_layout - -\begin_layout Standard -The -\emph on -binary_grid -\emph default - Perl module contains (almost) all the code to set up, manage and run the - grid, as well as the interface to the -\emph on -binary_c/nucsyn -\emph default -. - This should be (almost) completely transparent to you, the user, and the - process is as automated as possible. - You still have to do something, of course, and – most importantly – decide - on input physics. -\end_layout - -\begin_layout Subsubsection -Variables -\end_layout - -\begin_layout Standard -You can set variables in two data hashes -\emph on -binary_grid::grid_options -\emph default -and -\emph on -binary_grid::bse_options -\emph default -. - Usually you do this in the -\emph on -defaults -\emph default - subroutine of your grid script. -\end_layout - -\begin_layout Itemize -The -\emph on -grid_options -\emph default - control the behaviour of the grid and allow you to set up the -\emph on -flexigrid -\emph default -. - These options control the grid loops, logic, logging, threads etc. -\end_layout - -\begin_layout Itemize -The -\emph on -bse_options -\emph default - control the binary-star physics, such as the metallicity, common-envelope - parameters, etc. - The names of the -\emph on -bse_options -\emph default - keys (mostly) match those of the arguments to -\emph on -binary_c -\emph default -. - This is deliberate: if you add a command-line option to -\emph on -binary_c -\emph default - you can add it directly to -\emph on -bse_options -\emph default - to have it work immediately. -\end_layout - -\begin_layout Itemize -In your grid script you need a globally defined hash to store the population - synthesis results, usually called -\emph on -%results -\emph default -. - You must tell -\emph on -binary_grid -\emph default - what it is called, e.g. - in your -\emph on -defaults -\emph default - subroutine (see Sec. -\begin_inset space ~ -\end_inset - - -\begin_inset CommandInset ref -LatexCommand ref -reference "subsec:subs-in-your-script" - -\end_inset - -) insert -\begin_inset Newline newline -\end_inset - - -\emph on -$binary_grid::grid_options{'results_hash'}= -\backslash -%results; -\end_layout - -\begin_layout Itemize -Each thread has a hash called -\emph on -%binary_grid::threadinfo -\emph default - associated with it. - This contains information such as the process ID of your evolution code - (usually -\emph on -binary_c -\emph default -), the thread's data hash (which is eventually merged into -\emph on -%results -\emph default -), the last arguments sent to the evolution code, the runtime, number of - stars run, thread number, start time, etc. - You should not change this hash, but you can use it for debugging. - See also Section -\begin_inset space ~ -\end_inset - - -\begin_inset CommandInset ref -LatexCommand ref -reference "sec:The-Thread-Model" - -\end_inset - -. -\end_layout - -\begin_layout Subsubsection -Important Subroutines in -\emph on -binary_grid -\end_layout - -\begin_layout Standard -\begin_inset CommandInset label -LatexCommand label -name "subsec:subs in binary_grid" - -\end_inset - -Only the most important subroutines which you may call from your grid script - are listed here. -\end_layout - -\begin_layout Labeling -\labelwidthstring 00.00.0000 - -\emph on -grid_defaults -\emph default - sets up the default values in the -\emph on -binary_grid::grid_options -\emph default - and -\emph on -binary_grid::bse_options -\emph default - hashes. - You have to call this before you do anything else with -\emph on -binary_grid -\emph default -. -\end_layout - -\begin_layout Labeling -\labelwidthstring 00.00.0000 - -\emph on -setup_binary_grid -\emph default - After setting up your -\emph on -binary_grid::grid_options -\emph default - and -\emph on -binary_grid::bse_options -\emph default - hashes, call this function to finalise setup. -\end_layout - -\begin_layout Labeling -\labelwidthstring 00.00.0000 - -\emph on -parse_grid_args -\emph default - This loops over the command-line arguments of your script and looks for - them in the form -\emph on -x=y -\emph default -. - If -\emph on -x -\emph default - matches a -\emph on -grid_option -\emph default - or -\emph on -bse_options -\emph default -, it is set appropriately to -\emph on -y -\emph default -. - (You can pass an array of arguments to -\emph on -parse_grid_args -\emph default - which is used in place of the command-line, otherwise it defaults to -\emph on -@ARGV -\emph default -.) -\end_layout - -\begin_layout Labeling -\labelwidthstring 00.00.0000 - -\emph on -flexigrid(n) -\emph default - Call this subroutine to launch your grid after you have done all the above - setup. - -\emph on -n -\emph default - is the number of threads. - -\end_layout - -\begin_layout Subsection -Important Subroutines in your grid script -\end_layout - -\begin_layout Standard -\begin_inset CommandInset label -LatexCommand label -name "subsec:subs-in-your-script" - -\end_inset - - -\end_layout - -\begin_layout Labeling -\labelwidthstring 00.00.0000 - -\emph on -defaults -\emph default - (required) You have to set up the variables of your grid before doing anything - else, usually in a -\emph on -defaults -\emph default - function. - This must call -\emph on -grid_defaults() -\emph default -and then override variables in the -\emph on -binary_grid::grid_options -\emph default - and -\emph on -binary_grid::bse_options -\emph default - hashes. - It must also set the code reference to the -\emph on -results_hash -\emph default - -\emph on -grid_option -\emph default -, e.g. -\begin_inset Newline newline -\end_inset - - -\emph on -$binary_grid::grid_options{'results_hash'}= -\backslash -%results; -\end_layout - -\begin_layout Labeling -\labelwidthstring 00.00.0000 - -\emph on -parse_bse -\emph default - (required) You have to write a function to parse the data which comes from - -\emph on -binary_grid -\emph default -, as described in Section -\begin_inset space ~ -\end_inset - - -\begin_inset CommandInset ref -LatexCommand ref -reference "sec:grid.pl" - -\end_inset - -. - You can tell -\emph on -binary_grid -\emph default - about your function by setting -\begin_inset Newline newline -\end_inset - - -\emph on -$binary_grid::grid_options{'parse_bse_function_pointer'}= -\backslash -&my_function_name; -\begin_inset Newline newline -\end_inset - - -\emph default -although binary_grid should use -\emph on -parse_bse -\emph default -(actually -\emph on - -\backslash -&main::parse_bse -\emph default -) by default. -\begin_inset Newline newline -\end_inset - -The first argument passed to -\emph on -parse_bse -\emph default - is always a pointer to the thread's data hash, usually referred to as -\emph on -$h -\emph default -. - This stores all the data in the hash and is added to the global -\emph on -%results -\emph default - hash when the thread finishes so you can output the result of your population - synthesis (see Section -\begin_inset space ~ -\end_inset - - -\begin_inset CommandInset ref -LatexCommand ref -reference "subsec:thread-resources" - -\end_inset - - for more details on how data is joined to make the results). -\end_layout - -\begin_layout Labeling -\labelwidthstring 00.00.0000 - -\emph on -tbse_line -\emph default - This gets a line of data from -\emph on -binary_c/nucsyn -\emph default -. - This should be called by parse_bse (see examples in Section -\begin_inset space ~ -\end_inset - -). -\end_layout - -\begin_layout Labeling -\labelwidthstring 00.00.0000 - -\emph on -join_thread -\emph default - (optional) You can override the default thread-joining function with your - own, e.g. - with -\begin_inset Newline newline -\end_inset - - -\emph on - $binary_grid::grid_options{'threads_join_function_pointer'}= -\backslash -&join_thread; -\end_layout - -\begin_layout Labeling -\labelwidthstring 00.00.0000 - -\emph on -output -\emph default - (required) After the population synthesis is complete, you have to output - data to screen or (better) to disk. - This function should do this. -\end_layout - -\begin_layout Standard -\begin_inset Newpage pagebreak -\end_inset - - -\end_layout - -\begin_layout Section -Your -\emph on -grid script -\emph default -and coupling your population synthesis to -\emph on -binary_c/nucsyn -\end_layout - -\begin_layout Standard -\begin_inset CommandInset label -LatexCommand label -name "sec:grid.pl" - -\end_inset - -This describes what you should do in your grid script in order to make the - -\emph on -flexigrid -\emph default -work. - Learn about the -\emph on -flexigrid -\emph default - in Section -\begin_inset space ~ -\end_inset - - -\begin_inset CommandInset ref -LatexCommand ref -reference "sec:flexigrid" - -\end_inset - -. -\begin_inset Newline newline -\end_inset - - -\begin_inset Newline newline -\end_inset - -Before you start: you should copy the -\family typewriter -grid-flexigrid.pl -\family default - script in the -\family typewriter -src/perl/scripts -\family default - directory to a script of your own naming (usually grid- -\emph on -xxx -\emph default -.pl where you choose a suitable label to replace -\emph on -xxx -\emph default -). - Work on your copy, not the original! -\end_layout - -\begin_layout Subsection -Logging in -\emph on -binary_c -\end_layout - -\begin_layout Standard -\begin_inset CommandInset label -LatexCommand label -name "subsec:logging in binary_c" - -\end_inset - - -\end_layout - -\begin_layout Standard -When -\emph on -binary_c -\emph default - is run for one star with the -\family typewriter -tbse -\family default - script the output is dumped to the screen (known in -\emph on -UNIX -\emph default - as -\family typewriter -stdout -\family default -). - A standard build of -\emph on -binary_c -\emph default - outputs very little information because it does not know what you wish - to know (this is a -\emph on -known unknown -\emph default -). - Every line that is output is expensive in terms of CPU time, and CPU time - is critical when running millions of stars. - This means you have to think carefully about what you will output from - -\emph on -binary_c -\emph default - and when. - Too much information slows things down, too little is useless – you have - to decide. -\end_layout - -\begin_layout Standard -You may want to output one line of information per -\emph on - binary_c -\emph default -timestep. - This should be done in the -\family typewriter -src/logging/log_every_timestep -\family default - subroutine which is called every timestep. - Your logging code should look something like: -\end_layout - -\begin_layout Standard - -\family typewriter -printf( -\begin_inset Quotes eld -\end_inset - -MYLOG %g %g %g %i -\backslash -n -\begin_inset Quotes erd -\end_inset - -, -\end_layout - -\begin_layout Standard - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -stardata->model.model_time, -\end_layout - -\begin_layout Standard - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -stardata->model.probability, -\end_layout - -\begin_layout Standard - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -dt, -\end_layout - -\begin_layout Standard - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -stardata->star[1].mass, -\end_layout - -\begin_layout Standard - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -stardata->star[1].stellar_type); -\end_layout - -\begin_layout Standard -The string -\family typewriter -MYLOG -\family default - is critical: this is what will be recognised and used by -\emph on -binary_grid -\emph default -. - You should have a think (and consult Section -\begin_inset space ~ -\end_inset - - -\begin_inset CommandInset ref -LatexCommand ref -reference "sec:data-parsing" - -\end_inset - -) to determine whether you want to output either the probability ( -\family typewriter -stardata-> model.probability -\family default -) or both the probability and timestep -\begin_inset Foot -status collapsed - -\begin_layout Plain Layout -Do -\size normal -\emph on -not -\emph default - use -\family typewriter -stardata->model.dt -\family default - or -\family typewriter -stardata->model.dtm -\family default -: use the local variable -\family typewriter -dt -\family default -. -\end_layout - -\end_inset - - ( -\family typewriter -dt -\family default -). - Often it is the number of stars in a particular phase that you want to - count, in which case you want to add up the product: -\family typewriter -stardata-> model.probability*dt -\family default -, which is set up for you as the local variable -\family typewriter -dtp -\family default -. -\end_layout - -\begin_layout Subsection -Coupling your -\emph on -binary_c/nucsyn -\emph default - and your grid: -\family typewriter -tbse_line -\family default -and -\family typewriter - parse_bse -\end_layout - -\begin_layout Standard -\begin_inset CommandInset label -LatexCommand label -name "subsec:coupling binary_c to grid" - -\end_inset - - -\end_layout - -\begin_layout Standard -Now you know how to make lines of logging information come out of the -\emph on -binary_c -\emph default - program. - It remains to couple this to the grid. - This is done through the -\family typewriter -tbse_line -\family default - subroutine in the -\family typewriter -parse_bse -\family default - function (see the example -\family typewriter -grid.pl -\family default -). - Each time -\family typewriter -tbse_line -\family default - is called it gets a line of output from -\emph on -binary_c -\emph default - and loads returns it (usually to -\family typewriter -$_ -\family default - the Perl default variable). - It is then up to you to decide what to with the data from -\family typewriter -tbse_line -\family default -. - -\end_layout - -\begin_layout Standard -There may be many lines of data pumped into -\family typewriter -tbse_line -\family default -, so you have to choose those labelled with your header string – in the - above example this is -\family typewriter -MYLOG -\family default -. - This is best done with a Perl substitution-regular expression: the regular - expression matches -\family typewriter -MYLOG -\family default -, the substitution removes it (because it is not data). - In the following example note that the check for ' -\family typewriter -fin -\family default -' -\emph on -must -\emph default - be there. - -\emph on -binary_c -\emph default - returns a ' -\family typewriter -fin -\family default -' when the star has finished its evolution. - Without this it would be stuck in an infinite loop, so avoid removing the - -\family typewriter -$brk -\family default - stuff. - -\begin_inset Newline newline -\end_inset - - -\end_layout - -\begin_layout Standard -$h=$_[0]; # data hash -\end_layout - -\begin_layout Standard - -\family typewriter -while($brk==0) -\end_layout - -\begin_layout Standard - -\family typewriter -{ -\end_layout - -\begin_layout Standard - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -$_=tbse_line(); # get line of data from binary_c -\end_layout - -\begin_layout Standard - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -if($_ eq 'fin') -\end_layout - -\begin_layout Standard - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -{ -\end_layout - -\begin_layout Standard - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -$brk=1; # the end of output -\end_layout - -\begin_layout Standard - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -} -\end_layout - -\begin_layout Standard - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -elsif(s/^MYLOG //) # regular expression to match and remove MYLOG -\end_layout - -\begin_layout Standard - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -{ -\end_layout - -\begin_layout Standard - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -my @x=split(' ',$_); # convert space-separated data string to array -\end_layout - -\begin_layout Standard - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -#... - do stuff with @x ... -\end_layout - -\begin_layout Standard - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -# e.g. - $x[0] is the time, $x[1] is the probability etc. -\end_layout - -\begin_layout Standard - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -} -\end_layout - -\begin_layout Standard -} -\end_layout - -\begin_layout Subsection -Adding things up -\end_layout - -\begin_layout Standard -\begin_inset CommandInset label -LatexCommand label -name "subsec:adding things up" - -\end_inset - - -\end_layout - -\begin_layout Standard -So you have the probabilities (and maybe the timesteps) for each timestep - of -\emph on -binary_c -\emph default - and for each star. - What do you do now? Well, you have to create meaningful statistics by summing - up the results. - You should put results into the -\emph on - $h -\emph default - hash pointer as follows: -\begin_inset Newline newline -\end_inset - - -\end_layout - -\begin_layout Standard - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -elsif(s/^MYLOG //) # regular expression to match and remove MYLOG -\end_layout - -\begin_layout Standard - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -{ -\end_layout - -\begin_layout Standard - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -my @x=split(' ',$_); # convert data string to array -\end_layout - -\begin_layout Standard - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -my $dtp=$x[1]*$x[2]; # calculate dt * p -\end_layout - -\begin_layout Standard - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -if($x[3]>8.0) # check mass (element 3 of @x) -\end_layout - -\begin_layout Standard - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -{ -\end_layout - -\begin_layout Standard - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -# high mass star -\end_layout - -\begin_layout Standard - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -$$h{'high-mass'}+=$dtp; -\end_layout - -\begin_layout Standard - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -} -\end_layout - -\begin_layout Standard - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -else -\end_layout - -\begin_layout Standard - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -{ -\end_layout - -\begin_layout Standard - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -# low mass star -\end_layout - -\begin_layout Standard - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -$$h{'low-mass'}+=$dtp; -\end_layout - -\begin_layout Standard - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\family default -} -\end_layout - -\begin_layout Subsection* - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -} -\begin_inset Newline newline -\end_inset - - -\end_layout - -\begin_layout Subsection -Joining the results -\end_layout - -\begin_layout Standard -The -\emph on -$h -\emph default - hash pointer is unique to a single thread: it does not contain your final - result, just part of it. - You have to add up the results by -\emph on -joining -\emph default - the various threads. - In practice this is done automatically by binary_grid in combination with - some Perl wizardry. - You can, however, override this yourself by writing your own join function, - which should be set in the following manner: -\begin_inset Newline newline -\end_inset - - -\emph on -$binary_grid::grid_options{'threads_join_function_pointer'}= -\backslash -&join_thread; -\end_layout - -\begin_layout Standard -Beware that joining large hashes may require a lot of RAM. -\end_layout - -\begin_layout Subsection -Outputting the results -\end_layout - -\begin_layout Standard -At the end of the grid.pl script you should output the results, usually by - writing an -\emph on -output -\emph default - subroutine and calling it. - It is up to your to do this: -\emph on -binary_grid -\emph default - cannot possibly know your results or how you have structured your results - hash. -\end_layout - -\begin_layout Subsection -More advanced accountancy -\end_layout - -\begin_layout Standard -Consider the previous example. - Perhaps instead of simply having -\begin_inset Quotes eld -\end_inset - -low -\begin_inset Quotes erd -\end_inset - - and -\begin_inset Quotes eld -\end_inset - -high -\begin_inset Quotes erd -\end_inset - - mass stars you actually want to calculate a histogram of number of stars - as a function of mass at a certain time. -\end_layout - -\begin_layout Standard -The problem of how to force -\emph on -binary_c -\emph default - to output at given times is a tricky one which is not dealt with here. - However, it can be done and indeed is in the -\family typewriter -NUCSYN_GCE -\family default - logging. - Let us assume you have fixed -\emph on -binary_c/nucsyn -\emph default - so it outputs the mass of each star every -\begin_inset Formula $1\,\mathrm{Myr}$ -\end_inset - -. - You want to bin the masses at each timestep, so you will have a series - of histograms. - Note that -\family typewriter -$dtp -\family default - is not required because you are not counting the number of stars in a given - -\emph on -phase -\emph default - but rather an instantaneous property of the stars at a given time -\family typewriter -$t -\family default -. -\end_layout - -\begin_layout Standard -Something like this will do it: -\begin_inset Newline newline -\end_inset - - -\end_layout - -\begin_layout Standard - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -elsif(s/^MYLOG //) # regular expression to match and remove MYLOG -\end_layout - -\begin_layout Standard - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -{ -\end_layout - -\begin_layout Standard - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -my @x=split(' ',$_); # convert data string to array -\end_layout - -\begin_layout Standard - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -my $t=$x[0]; # time (an integer number of Myr since the starburst) -\end_layout - -\begin_layout Standard - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -my $p=$x[1]; # probability -\end_layout - -\begin_layout Standard - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -my $m=$x[3]; # stellar mass -\end_layout - -\begin_layout Standard - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\end_layout - -\begin_layout Standard - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -# bin stellar mass in 1Msun bins -\end_layout - -\begin_layout Standard - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -$m = rebin($m,1.0); -\end_layout - -\begin_layout Standard - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\end_layout - -\begin_layout Standard - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -$$h{'mass histogram'}{$t}{$m}+=$p; # construct histogram -\end_layout - -\begin_layout Standard - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -} -\end_layout - -\begin_layout Standard -Things to note include: -\end_layout - -\begin_layout Itemize -We use the -\emph on -rebin -\emph default - function of -\emph on -binary_grid -\emph default - to do the binning very efficiently to the nearest -\begin_inset Formula $1.0\mathrm{\,M_{\odot}}$ -\end_inset - -. - -\end_layout - -\begin_layout Itemize -You can construct a similar expression for an arbitrary bin width. - Why do we do this? Well, if we take the instantaneous mass of each star - in a population at a given time there will be a huge number of different - masses because mass loss may be effective. - This would give a histogram with -\begin_inset Formula $N\times N_{t}=n_{\mathrm{M1}}\times n_{\mathrm{M2}}\times n_{\mathrm{a}}\times N_{t}$ -\end_inset - - bins where -\begin_inset Formula $N_{t}$ -\end_inset - - is the number of timesteps of -\emph on -binary_c -\emph default - output. - This is too much data to deal with and negates the whole purpose of making - a histogram! Bin your data: it makes life a lot easier. -\end_layout - -\begin_layout Itemize -The time and mass are integers in this case, so we could have used arrays - (which have integer index) instead of hashes for the output, but if you - want finer resolution they will not be and hashes are -\emph on -required -\emph default -. - It is good to get into the habit. - -\end_layout - -\begin_layout Itemize -The 'mass histogram' hash label is not really necessary in this simple example - because nothing else is stored, but in a real grid you may be constructing - many different histograms, each will required a different label. - It is good to get into the habit of using nested hashes. -\end_layout - -\begin_layout Itemize -The results are saved in hash of hashes of hashes. - This is a typical example of a Perl nested variable, help for how to deal - with (and output) hashes of hashes is easily found with a simple web search - (or consult the excellent -\emph on -Programming Perl -\emph default -). -\end_layout - -\begin_layout Itemize -Beware resolution! Always test different resolutions and beware binning - and aliasing effects. -\end_layout - -\begin_layout Subsection -Save your data – or process on the fly? -\end_layout - -\begin_layout Standard -Before running a grid you have to make the big decision: do you save your - data or process it all on the fly? There are advantages and disadvantages - to both, as described below. -\end_layout - -\begin_layout Subsubsection -Saving data -\end_layout - -\begin_layout Standard -\begin_inset CommandInset label -LatexCommand label -name "subsec:saving_data" - -\end_inset - -In this case you run a grid and tag the initial parameters of each system - of interest (i.e. - the -\begin_inset Formula $M_{1}$ -\end_inset - -, -\begin_inset Formula $M_{2}$ -\end_inset - -, -\begin_inset Formula $a$ -\end_inset - - and -\begin_inset Formula $\delta V=\delta\ln M_{1}\,\delta\ln M_{2}\,\delta a$ -\end_inset - -). - -\emph on -You save these initial parameters into a large datafile. - -\emph default - The big advantage of this technique is that you can rerun the saved grid - -\emph on -from the datafile, -\emph default -possibly -\emph on - -\emph default -without running -\emph on -binary_c/nucsyn -\emph default - again, and with a different initial distribution function (e.g. - initial mass function) or very slightly different physics (on the assumption - that changing the physics will not change the systems which were saved). - -\end_layout - -\begin_layout Standard -You could save, as well as the initial parameters of the systems, the time - spent in the phase of interest, -\begin_inset Formula $\Delta t$ -\end_inset - -. - Each time the grid is rerun you would then calculate the probability -\begin_inset Formula $p_{i}$ -\end_inset - - for each system again, hence you know -\begin_inset Formula $p_{i}\Delta t$ -\end_inset - - which is your required -\begin_inset Quotes eld -\end_inset - -number of stars -\begin_inset Quotes erd -\end_inset - -. - You can either -\end_layout - -\begin_layout Enumerate -Change -\begin_inset Formula $p_{i}$ -\end_inset - - and recalculate your statistics. - This does -\emph on -not -\emph default -require the running of -\emph on -binary_c/nucsyn -\emph default - and is the fast option. -\end_layout - -\begin_layout Enumerate -Change -\begin_inset Formula $p_{i}$ -\end_inset - - and some physics, which requires rerunning of -\emph on -binary_c/nucsyn -\emph default -. - This is slower, but still faster than running the full grid. -\end_layout - -\begin_layout Standard -Saving the progenitor data set is a very useful way of saving time after - an initial high-resolution grid run. -\end_layout - -\begin_layout Standard -You may want to consider converting your saved data from ASCII to binary - format, particularly if you will be processing it repeatedly. - This can save a lot of time, but it renders your data very difficult to - read, and it is hard to make such code truly backwards compatible. - If someone comes to look at your results in ten years' time, will you remember - exactly what is going on? Sacrificing clarity for speed is not necessarily - a good thing. -\end_layout - -\begin_layout Subsubsection -On the fly data processing -\end_layout - -\begin_layout Standard -\begin_inset CommandInset label -LatexCommand label -name "subsec:on-the-fly" - -\end_inset - - -\end_layout - -\begin_layout Standard -If you do not want to recalculate your answer with different initial functions, - you might be better off calculating the results you require -\begin_inset Quotes eld -\end_inset - -on the fly -\begin_inset Quotes erd -\end_inset - -. - This means you do your data processing -\emph on -in your grid script -\emph default -. - The main advantages to this are speed and data storage. - For example, if you have -\begin_inset Formula $10^{6}$ -\end_inset - - -\begin_inset space ~ -\end_inset - -stars in your grid, that is -\begin_inset Formula $10^{6}$ -\end_inset - - -\begin_inset space ~ -\end_inset - -lines of data – this might be a lot of data. -\end_layout - -\begin_layout Standard -In some cases you -\emph on -must -\emph default - do this. - If you are looking at data which is time dependent then you will have -\begin_inset Formula $10^{6}\times N_{t}$ -\end_inset - - -\begin_inset space ~ -\end_inset - -lines of data, where -\begin_inset Formula $N_{t}$ -\end_inset - - is the number of timesteps during which your system is of interest. - -\begin_inset Formula $N_{t}$ -\end_inset - - may be many hundreds for a given system, hence the total number of lines - of data is of the order of -\begin_inset Formula $10^{8}$ -\end_inset - - and the data storage requirements become quite ridiculous. - For example, a typical line of data has about 200 characters, so -\begin_inset Formula $200\times10^{8}=2\times10^{10}\,\mathrm{bytes}$ -\end_inset - - of data, or -\begin_inset Formula $20\,\mbox{GB}$ -\end_inset - -. - The time it takes to process all this data may be longer than the time - to -\emph on -rerun -\emph default - -\emph on -binary_c/nucsyn -\emph default -for each system, especially if your data storage is non-local (e.g. - on an NFS (network) partition). - -\end_layout - -\begin_layout Standard -You can save some space by outputting data every, say, Myr, but this may - not be the time resolution you require to catch systems of interest. -\begin_inset Newpage pagebreak -\end_inset - - -\end_layout - -\begin_layout Section -Flexigrid -\end_layout - -\begin_layout Standard -\begin_inset CommandInset label -LatexCommand label -name "sec:flexigrid" - -\end_inset - -As of summer 2011, the -\begin_inset Quotes eld -\end_inset - -flexi -\emph on -grid -\emph default - -\begin_inset Quotes erd -\end_inset - - was developed. - This is an attempt to replace much of the old grid framework with a new, - dynamic set of instructions which are much more flexible and, at the same - time, more efficient. - The key concepts are the following: -\end_layout - -\begin_layout Itemize -When a -\emph on -flexigrid -\emph default - is run, it sets up -\begin_inset Formula $n$ -\end_inset - - concurrently running -\emph on -threads -\emph default -. - Each of these is fed with stars until the population is complete. - Because of this, flexigrid is designed specifically to work on the latest - multi-core CPUs on shared-memory machines (which are the typical PCs of - the early 21st century). -\end_layout - -\begin_layout Itemize - -\emph on -Flexigrid -\emph default - sets up its -\begin_inset Formula $M_{1}-M_{2}-a$ -\end_inset - - (or -\begin_inset Formula $P$ -\end_inset - -) etc. - grid -\emph on -dynamically -\emph default -. - It does this by writing the grid code itself and then compiling it with - Perl's -\emph on -eval -\emph default - command. - This means it is truly flexible, you can add or remove -\emph on -any variable you like -\emph default - to the grid with an -\emph on -arbitrary spacing -\emph default -and do not have to write any new code in the -\emph on -binary_grid -\emph default - module! -\end_layout - -\begin_layout Itemize -Probabilities are calculated more efficiently and flexibly by the -\emph on -distribution_functions -\emph default - module. -\end_layout - -\begin_layout Subsection -Setup in your grid script -\end_layout - -\begin_layout Standard -\begin_inset CommandInset label -LatexCommand label -name "subsec:setup grid script" - -\end_inset - - -\end_layout - -\begin_layout Standard -You need to do a few things: -\end_layout - -\begin_layout Enumerate -Set up the grid in the -\family typewriter -grid_options -\family default -hash by calling -\emph on -grid_defaults -\emph default -. - -\begin_inset Newline newline -\end_inset - -Note that you -\emph on -must -\emph default - link a hash in your script to -\family typewriter -$binary_grid::grid_options{results_hash} -\family default - e.g. - -\begin_inset Newline newline -\end_inset - - -\family typewriter -$binary_grid::grid_options{results_hash}=$results; -\family default - (if you have a global anonymous hash e.g. - -\family typewriter -$results={}; -\family default -) -\begin_inset Newline newline -\end_inset - -or -\begin_inset Newline newline -\end_inset - - -\family typewriter -$binary_grid::grid_options{results_hash}= -\backslash -%results; -\family default - (if you have a global hash e.g. - -\family typewriter -%results; -\family default -) -\begin_inset Newline newline -\end_inset - - -\begin_inset Newline newline -\end_inset - - -\end_layout - -\begin_layout Enumerate -Change parameters as you see fit. -\end_layout - -\begin_layout Enumerate -Call -\family typewriter -flexigrid( -\emph on -n -\emph default -); -\family default -where n is the number of threads -\end_layout - -\begin_layout Enumerate -Output. -\end_layout - -\begin_layout Subsubsection -Grid variables: 1D example -\end_layout - -\begin_layout Standard -Setting up which variables you use is best defined by example. - Let's start with -\begin_inset Formula $M_{1}$ -\end_inset - - which you will always require. - First, define the grid resolution as $n -\begin_inset Formula $\times$ -\end_inset - -$n -\begin_inset Formula $\times$ -\end_inset - -$n (here -\begin_inset Formula $10\times10\times10$ -\end_inset - -) -\end_layout - -\begin_layout Standard - -\family typewriter -$n=10; -\family default - -\begin_inset Newline newline -\end_inset - -Next, set up the variable number corresponding to the grid variable. - Each grid variable must have a unique number, starting with 0 and working - upward. - -\end_layout - -\begin_layout Standard - -\family typewriter -my $nvar=0; -\family default - -\begin_inset Newline newline -\end_inset - - -\begin_inset Newline newline -\end_inset - -Now use an -\emph on -anonymous hash -\emph default - in the grid option -\family typewriter -{'flexigrid'}{'grid variable '.$nvar} -\family default - to give the options: -\begin_inset Newline newline -\end_inset - - -\end_layout - -\begin_layout Standard - -\family typewriter -\begin_inset Box Frameless -position "t" -hor_pos "c" -has_inner_box 1 -inner_pos "t" -use_parbox 0 -use_makebox 0 -width "100col%" -special "none" -height "1in" -height_special "totalheight" -thickness "0.4pt" -separation "3pt" -shadowsize "4pt" -framecolor "black" -backgroundcolor "none" -status open - -\begin_layout Plain Layout - -\family typewriter -# Mass 1 -\end_layout - -\begin_layout Plain Layout - -\family typewriter -my $mmin=0.1; -\end_layout - -\begin_layout Plain Layout - -\family typewriter -my $mmax=80.0; -\end_layout - -\begin_layout Plain Layout - -\family typewriter -$binary_grid::grid_options{'flexigrid'}{'grid variable '.$nvar++}= -\end_layout - -\begin_layout Plain Layout - -\family typewriter -{ -\end_layout - -\begin_layout Plain Layout - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -'name'=>'lnm1', -\end_layout - -\begin_layout Plain Layout - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -'longname'=>'Primary_Mass', -\end_layout - -\begin_layout Plain Layout - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -'range' => [$mmin,$mmax], -\end_layout - -\begin_layout Plain Layout - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -'resolution'=>$n, -\end_layout - -\begin_layout Plain Layout - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -'spacingfunc'=>"const(log($mmin),log($mmax),$n)", -\end_layout - -\begin_layout Plain Layout - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -'precode'=>"my -\backslash -$m1=exp( -\backslash -$lnm1);my -\backslash -$eccentricity=0.0;", -\end_layout - -\begin_layout Plain Layout - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -'probdist'=>"ktg93( -\backslash -$m1)* -\backslash -$m1", -\end_layout - -\begin_layout Plain Layout - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -'dphasevol'=>" -\backslash -$dlnm1 " -\end_layout - -\begin_layout Plain Layout - -\family typewriter -}; -\end_layout - -\end_inset - - -\family default -(Note the -\family typewriter -++ -\family default - after -\family typewriter -$nvar -\family default - which raises the variable number for the next variable. -\family typewriter -) -\begin_inset Newline newline -\end_inset - - -\end_layout - -\begin_layout Standard -What does this mean? -\end_layout - -\begin_layout Labeling -\labelwidthstring 00.00.0000 - -\family typewriter -name -\family default - -\begin_inset space ~ -\end_inset - - -\emph on -string -\emph default - This is the variable name. - It should be parsable in Perl, e.g. - in the above case it is expanded to -\family typewriter -$lnm1 -\family default - in the gridcode. -\end_layout - -\begin_layout Labeling -\labelwidthstring 00.00.0000 - -\family typewriter -longname -\family default - -\begin_inset space ~ -\end_inset - - -\emph on -string -\emph default - This is a long (human-readable) name used in logging. - It should contain no spaces (use underscores). -\end_layout - -\begin_layout Labeling -\labelwidthstring 00.00.0000 - -\family typewriter -range -\family default - -\begin_inset space ~ -\end_inset - - -\emph on -min -\emph default - -\begin_inset space ~ -\end_inset - - -\emph on -max -\emph default - This defines the range of the grid, from -\emph on -min -\emph default - to -\emph on -max. - -\emph default - In the above case from -\family typewriter -log(0.1) -\family default - to -\family typewriter -log(80.0) -\family default -. - (We are using a grid in -\emph on -log -\emph default - -\begin_inset Formula $M_{1}$ -\end_inset - -.) Note that this is sent as an -\emph on -anonymous array -\emph default - of the form -\family typewriter - [ -\emph on -min -\emph default -, -\emph on -max -\emph default -] -\family default - (remember the square brackets!). -\end_layout - -\begin_layout Labeling -\labelwidthstring 00.00.0000 - -\family typewriter -resolution -\family default - -\begin_inset space ~ -\end_inset - - -\emph on -n -\emph default -This is the grid resolution, given above by -\family typewriter -$n -\family default -. -\end_layout - -\begin_layout Labeling -\labelwidthstring 00.00.0000 - -\family typewriter -spacingfunc -\family default - -\begin_inset space ~ -\end_inset - - -\emph on -func -\emph default -This defines the spacing function which should be in the -\emph on -spacing_functions -\emph default - Perl module. - In the above example the spacing is constant between -\family typewriter -log(0.1) -\family default -and -\family typewriter - log(80.0) -\family default -with -\family typewriter - $n -\family default -steps. -\end_layout - -\begin_layout Labeling -\labelwidthstring 00.00.0000 - -\family typewriter -preloopcode -\family default - -\begin_inset space ~ -\end_inset - - -\emph on -code -\emph default -This is code executed before the loop is set up. -\end_layout - -\begin_layout Labeling -\labelwidthstring 00.00.0000 - -\family typewriter -precode -\family default - -\begin_inset space ~ -\end_inset - - -\emph on -code -\emph default -This is code executed before the next part of the grid is set up. - In our case we have to specify -\family typewriter -$m1 -\family default - because we have only calculated -\family typewriter -$lnm1 -\family default -. - We also set up the eccentricity because there is no grid for this and it - is required. - -\end_layout - -\begin_layout Labeling -\labelwidthstring 00.00.0000 - -\family typewriter -postcode -\family default - -\begin_inset space ~ -\end_inset - - -\emph on -code -\emph default -This is code executed after the next part of the grid is set up. - (In our case there is no -\emph on -postcode -\emph default -). -\end_layout - -\begin_layout Labeling -\labelwidthstring 00.00.0000 - -\family typewriter -probdist -\family default - -\begin_inset space ~ -\end_inset - - -\emph on -func -\emph default -This is a probability distribution function as given in the -\emph on -distribution_functions -\emph default - Perl module. - In the above we use the -\family typewriter -ktg93 -\family default - ( -\begin_inset CommandInset citation -LatexCommand citealp* -key "KTG1993MNRAS-262-545K" -literal "true" - -\end_inset - - IMF) function. - -\end_layout - -\begin_layout Labeling -\labelwidthstring 00.00.0000 - -\family typewriter -dphasevol -\family default - -\begin_inset space ~ -\end_inset - - -\emph on -expression -\emph default -This defines the contribution to the phase volume from this variable. - In general this is just -\family typewriter -$dlnm1 -\family default - (i.e. - should be -\family typewriter -$d -\emph on -name -\family default -\emph default -) but you can set it to whatever you like. - -\end_layout - -\begin_layout Subsection -3D grid example -\end_layout - -\begin_layout Standard -\begin_inset CommandInset label -LatexCommand label -name "subsec:3d grid example" - -\end_inset - - -\end_layout - -\begin_layout Standard -The next step is to set up the further grid variables. - Usually these are -\begin_inset Formula $M_{2}$ -\end_inset - - and -\begin_inset Formula $a$ -\end_inset - -, as defined in the code below. -\end_layout - -\begin_layout Standard - -\family typewriter -\begin_inset Box Frameless -position "t" -hor_pos "c" -has_inner_box 1 -inner_pos "t" -use_parbox 0 -use_makebox 0 -width "100col%" -special "none" -height "1in" -height_special "totalheight" -thickness "0.4pt" -separation "3pt" -shadowsize "4pt" -framecolor "black" -backgroundcolor "none" -status open - -\begin_layout Plain Layout - -\family typewriter -# Binary stars: Mass 2 and Separation -\end_layout - -\begin_layout Plain Layout - -\family typewriter -if($binary_grid::grid_options{'binary'}) -\end_layout - -\begin_layout Plain Layout - -\family typewriter -{ -\end_layout - -\begin_layout Plain Layout - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -my $m2min=0.1; -\end_layout - -\begin_layout Plain Layout - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -$binary_grid::grid_options{'flexigrid'}{'grid variable '.$nvar++}= -\end_layout - -\begin_layout Plain Layout - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -{ -\end_layout - -\begin_layout Plain Layout - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -'name'=>'m2', -\end_layout - -\begin_layout Plain Layout - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -'longname'=>'Secondary_mass', -\end_layout - -\begin_layout Plain Layout - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -'range'=>[$m2min,'$m1'], -\end_layout - -\begin_layout Plain Layout - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -'resolution'=>$n, -\end_layout - -\begin_layout Plain Layout - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -'spacingfunc'=>"const($m2min, -\backslash -$m1,$n)", -\end_layout - -\begin_layout Plain Layout - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -'probdist'=>"const($m2min, -\backslash -$m1)", -\end_layout - -\begin_layout Plain Layout - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -'dphasevol','$dm2' -\end_layout - -\begin_layout Plain Layout - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -}; -\begin_inset Newline newline -\end_inset - - -\end_layout - -\begin_layout Plain Layout - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -$binary_grid::grid_options{'flexigrid'}{'grid variable '.$nvar++}= -\end_layout - -\begin_layout Plain Layout - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -{ -\end_layout - -\begin_layout Plain Layout - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -'name'=>'lnsep', -\end_layout - -\begin_layout Plain Layout - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -'longname'=>'ln(Orbital_Separation)', -\end_layout - -\begin_layout Plain Layout - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -'range'=>['log(3.0)','log(1e4)'], -\end_layout - -\begin_layout Plain Layout - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -'resolution',$n, -\end_layout - -\begin_layout Plain Layout - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -'spacingfunc',"const(log(3.0),log(1e4),$n)", -\end_layout - -\begin_layout Plain Layout - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -'precode'=>'my $sep=exp($lnsep);my $per=calc_period_from_sep($m1,$m2,$sep);', -\end_layout - -\begin_layout Plain Layout - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -'probdist'=>'const(log(3.0),log(1e4))', -\end_layout - -\begin_layout Plain Layout - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -'dphasevol'=>'$dlnsep' -\end_layout - -\begin_layout Plain Layout - -\family typewriter -} -\end_layout - -\begin_layout Plain Layout - -\family typewriter -} -\end_layout - -\end_inset - - -\end_layout - -\begin_layout Standard -The above setup has the same general form as for -\begin_inset Formula $M_{1}$ -\end_inset - - but with different spacing functions (the -\emph on -const -\emph default - spacing function is used, for -\begin_inset Formula $M_{2}$ -\end_inset - - in the range -\begin_inset Formula $0.1$ -\end_inset - - to -\begin_inset Formula $M_{1}$ -\end_inset - - and for -\begin_inset Formula $\ln a$ -\end_inset - - in the range -\begin_inset Formula $3$ -\end_inset - - to -\begin_inset Formula $10^{4}$ -\end_inset - -). -\end_layout - -\begin_layout Subsection -Viewing The (Automatically Generated) Gridcode -\end_layout - -\begin_layout Standard -\begin_inset CommandInset label -LatexCommand label -name "subsec:viewing the gridcode" - -\end_inset - - -\end_layout - -\begin_layout Standard -When you run -\family typewriter -flexigrid -\family default - in your grid script, a (flexi)grid with two threads will be constructed - and then run via the Perl -\emph on -eval -\emph default -operator. -\end_layout - -\begin_layout Standard -You can find the code that is constructed by the -\emph on -binary_grid -\emph default - module (and executed by your call to -\emph on -flexigrid -\emph default -) in the file -\family typewriter -/tmp/gridcode -\family default -. - View it with -\emph on -less -\emph default - or some other tool that can parse ANSI colours, or use the file -\family typewriter -/tmp/gridcode.clean -\family default - instead. - Note that the location of -\emph on -/tmp -\emph default - can be overridden in -\emph on -$binary_grid::grid_options{tmp} -\emph default -. - -\end_layout - -\begin_layout Subsection -Error handling -\end_layout - -\begin_layout Standard -\begin_inset CommandInset label -LatexCommand label -name "subsec:flexigrid error handling" - -\end_inset - - -\end_layout - -\begin_layout Standard -Things do go wrong. - Usually when this happens, the threads will be shut down and your grid - script will exit, telling you as much as it can about the error. - -\end_layout - -\begin_layout Standard -There is, however, a small chance that a -\emph on -zombie -\emph default - -\emph on -binary_c -\emph default - will still be running. - You will notice it when it starts using 100% of your CPU power! Check on - your system using an appropriate system-monitor (e.g. - -\emph on -top -\emph default - on Unix) and kill the process (see -\emph on -man kill -\emph default -) if required. -\end_layout - -\begin_layout Subsection -Flexigrid global options -\end_layout - -\begin_layout Standard -\begin_inset CommandInset label -LatexCommand label -name "subsec:flexigrid global options" - -\end_inset - - -\end_layout - -\begin_layout Standard -The flexigrid is set up inside a hash called, oddly, -\emph on -%flexigrid -\emph default -. - Options that affect it are: -\end_layout - -\begin_layout Labeling -\labelwidthstring 00.00.0000 - -\family typewriter -grid -\begin_inset space ~ -\end_inset - -type -\family default -\emph on - -\begin_inset space ~ -\end_inset - -string -\emph default -Usually this is -\begin_inset Quotes eld -\end_inset - -grid -\begin_inset Quotes erd -\end_inset - -, which is a normal grid. - However, a ( -\series bold -very experimental -\series default -) Monte Carlo grid is also available, in which case set it to -\begin_inset Quotes eld -\end_inset - -monte carlo -\begin_inset Quotes erd -\end_inset - -. -\end_layout - -\begin_layout Subsection -Flexigrid variable options -\end_layout - -\begin_layout Standard -\begin_inset CommandInset label -LatexCommand label -name "subsec:flexigrid variable options" - -\end_inset - - -\end_layout - -\begin_layout Standard -Note that any -\emph on -code -\emph default - is executed in the context of the flexigrid -\emph on -eval -\emph default -call, so you should prepend calls to subroutines with -\emph on -main:: -\emph default - or -\emph on -module_name:: -\emph default - -\end_layout - -\begin_layout Labeling -\labelwidthstring 00.00.0000 - -\family typewriter -condition -\family default - -\begin_inset space ~ -\end_inset - - -\emph on -code -\emph default - The loop is executed only if -\emph on -condition -\emph default - is true. - -\end_layout - -\begin_layout Labeling -\labelwidthstring 00.00.0000 - -\family typewriter -dphasevol -\family default - -\begin_inset space ~ -\end_inset - - -\emph on -expression -\emph default -This defines the contribution to the phase volume from this variable. -\end_layout - -\begin_layout Labeling -\labelwidthstring 00.00.0000 - -\family typewriter -gridtype -\family default - -\begin_inset space ~ -\end_inset - - -\emph on -string -\emph default -Most grid variables are of type -\begin_inset Quotes eld -\end_inset - -grid -\begin_inset Quotes erd -\end_inset - - which implies cell-centred variables. - However, you can also specify -\begin_inset Quotes eld -\end_inset - -edge -\begin_inset Quotes erd -\end_inset - - to keep the variable on the cell edge instead. - -\end_layout - -\begin_layout Labeling -\labelwidthstring 00.00.0000 - -\family typewriter -longname -\family default - -\begin_inset space ~ -\end_inset - - -\emph on -string -\emph default - This is a long (human-readable) name used in logging. - It should contain no spaces (use underscores). -\end_layout - -\begin_layout Labeling -\labelwidthstring 00.00.0000 - -\family typewriter -name -\family default - -\begin_inset space ~ -\end_inset - - -\emph on -string -\emph default - This is the variable name. - (It is best that it contains no special characters, just a-z, A-Z, 0-9 - or _, but is converted internally into a hash key, so in theory it could - be any string.) -\end_layout - -\begin_layout Labeling -\labelwidthstring 00.00.0000 -noprobdist -\begin_inset space ~ -\end_inset - - -\emph on -n -\emph default -If this is -\begin_inset Formula $1$ -\end_inset - - then no probability is calculated. - Useful for changing, e.g., the duplicity (see Recipe -\begin_inset space ~ -\end_inset - - -\begin_inset CommandInset ref -LatexCommand ref -reference "Recipe:Single and binary stars" - -\end_inset - -). -\end_layout - -\begin_layout Labeling -\labelwidthstring 00.00.0000 - -\family typewriter -preloopcode -\family default - -\begin_inset space ~ -\end_inset - - -\emph on -code -\emph default -This is code executed before the loop is set up. -\end_layout - -\begin_layout Labeling -\labelwidthstring 00.00.0000 - -\family typewriter -precode -\family default - -\begin_inset space ~ -\end_inset - - -\emph on -code -\emph default -This is code executed before the next part of the grid is set up. - -\end_layout - -\begin_layout Labeling -\labelwidthstring 00.00.0000 - -\family typewriter -postcode -\family default - -\begin_inset space ~ -\end_inset - - -\emph on -code -\emph default -This is code executed after the next part of the grid is set up. - (In our case there is no -\emph on -postcode -\emph default -). -\end_layout - -\begin_layout Labeling -\labelwidthstring 00.00.0000 - -\family typewriter -postloopcode -\family default - -\begin_inset space ~ -\end_inset - - -\emph on -code -\emph default -This is code executed after the loop and before the beginning of the next - loop. -\end_layout - -\begin_layout Labeling -\labelwidthstring 00.00.0000 - -\family typewriter -probdist -\family default - -\begin_inset space ~ -\end_inset - - -\emph on -func -\emph default -This is a probability distribution function as given in the -\emph on -distribution_functions -\emph default - Perl module. - -\end_layout - -\begin_layout Labeling -\labelwidthstring 00.00.0000 - -\family typewriter -range -\family default - -\begin_inset space ~ -\end_inset - - -\emph on -min -\emph default - -\begin_inset space ~ -\end_inset - - -\emph on -max -\emph default - This defines the range of the grid variable, from -\emph on -min -\emph default - to -\emph on -max. - -\emph default - -\end_layout - -\begin_layout Labeling -\labelwidthstring 00.00.0000 - -\family typewriter -resolution -\family default - -\begin_inset space ~ -\end_inset - - -\emph on -(n -\emph default -| -\emph on -code) -\emph default -This is the grid variable resolution, which is -\emph on -eval -\emph default -ed in the gridcode context, so it can be a function or a constant. - Mostly this is used for logging to estimate when the grid is finished. -\end_layout - -\begin_layout Labeling -\labelwidthstring 00.00.0000 - -\family typewriter -spacingfunc -\family default - -\begin_inset space ~ -\end_inset - - -\emph on -func -\emph default -This defines the spacing function which should be in the -\emph on -spacing_functions -\emph default - Perl module. - -\end_layout - -\begin_layout Standard -\begin_inset Newpage pagebreak -\end_inset - - -\end_layout - -\begin_layout Subsection -Flexigrid loop structure -\end_layout - -\begin_layout Standard -\begin_inset CommandInset label -LatexCommand label -name "subsec:flexigrid loop structure" - -\end_inset - - -\end_layout - -\begin_layout Standard -Each loop is logically structured as follows: -\end_layout - -\begin_layout Itemize -setup -\family typewriter -%fvar -\family default - (min, max, initial grid spacing -\begin_inset Formula $\delta$ -\end_inset - - from the -\emph on -spacing_functions, -\emph default -type= -\emph on -grid -\emph default - or -\emph on -edge -\emph default -) -\end_layout - -\begin_layout Itemize -calculate the resolution (with an -\emph on -eval -\emph default -call) -\end_layout - -\begin_layout Itemize -execute preloopcode -\end_layout - -\begin_layout Itemize -check condition code -\end_layout - -\begin_layout Itemize -{ (start the loop) -\end_layout - -\begin_layout Itemize -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -execute precode -\end_layout - -\begin_layout Itemize -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -calculate this loop's contribution to the phase space and probability (using - the -\emph on -distribution_functions -\emph default -) -\end_layout - -\begin_layout Itemize -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -update the counter -\end_layout - -\begin_layout Itemize -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -move loop variable on by -\begin_inset Formula $\delta/2$ -\end_inset - - (if it is is a grid variable) -\end_layout - -\begin_layout Itemize -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\family typewriter -<next loop> -\family default - (or push commands onto the thread queue) -\end_layout - -\begin_layout Itemize -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -execute postcode -\end_layout - -\begin_layout Itemize -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -move loop variable on by -\begin_inset Formula $\delta/2$ -\end_inset - - (if it is is a grid variable) or -\begin_inset Formula $\delta$ -\end_inset - - (if it is an edge variable) -\end_layout - -\begin_layout Itemize -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -update grid spacing -\begin_inset Formula $\delta$ -\end_inset - - (using the -\emph on -spacing_functions) -\end_layout - -\begin_layout Itemize -} (close the loop) -\end_layout - -\begin_layout Itemize -execute postloopcode -\end_layout - -\begin_layout Standard -Only the innermost loop contains the calls to push commands onto the thread - queue. -\end_layout - -\begin_layout Subsection -Flexigrid and HTCondor -\end_layout - -\begin_layout Standard -\begin_inset CommandInset label -LatexCommand label -name "subsec:Condor" - -\end_inset - -Warning: this is work in progress and subject to change! -\begin_inset Newline newline -\end_inset - - -\begin_inset Newline newline -\end_inset - -Flexigrid now supports the HTCondor distributed computing engine. - To use it, a few minor changes need to be made to your grid script. - Please see -\family typewriter -src/perl/scripts-flexigrid/grid-condor.pl -\family default - for an example. -\end_layout - -\begin_layout Itemize -Add a line (near the top of your Perl script) to use the condor module: -\begin_inset Newline newline -\end_inset - - -\family typewriter -use binary_grid::condor; -\end_layout - -\begin_layout Itemize -Replace the call to -\family typewriter -flexigrid(\SpecialChar ldots -); -\family default - with -\family typewriter -condor_grid(); -\end_layout - -\begin_layout Itemize -At the beginning of your output() subroutine, add a line -\begin_inset Newline newline -\end_inset - - -\family typewriter -return if($binary_grid::grid_options{condor_command} eq 'run_flexigrid'); -\family default - -\begin_inset Newline newline -\end_inset - -(This suppresses output except for the final running job which has all the - data) -\end_layout - -\begin_layout Itemize -Put the following in your -\family typewriter -defaults() -\family default - subroutine: -\begin_inset Newline newline -\end_inset - - -\family typewriter -$binary_grid::grid_options{condor_dir}='some world readable directory'; -\family default - -\begin_inset Newline newline -\end_inset - -This sets the working directory for this Condor job: it should be readable - -\emph on -from every Condor machine! -\emph default - Usually this is an NFS mounted disk. - I have not tried to make Condor work without a universally-writable directory. -\end_layout - -\begin_layout Itemize -Every job you run should use a different output directory. -\end_layout - -\begin_layout Subsubsection* -Condor issues and FAQ -\end_layout - -\begin_layout Standard -(Some of these problems are AIfA specific, but may apply to you) -\end_layout - -\begin_layout Itemize - -\emph on -What are the requirements for the output directory? -\emph default - -\begin_inset Newline newline -\end_inset - -The output directory must be in a world-writable location, e.g. - an NFS mount (see the problem with -\family typewriter - /export -\family default - below). - Each time you run a grid script with a call to condor_grid, a new directory - must be used. - -\emph on -It is up to you to ensure this is the case! -\end_layout - -\begin_layout Itemize - -\emph on -How are the jobs numbered? -\emph default - -\begin_inset Newline newline -\end_inset - -The jobs are numbered -\emph on -x.y -\emph default - (where -\emph on -x -\emph default -is the job number, -\emph on -y -\emph default - is the total number of jobs). - These numbers just have to be unique, you are free to change them. -\end_layout - -\begin_layout Itemize - -\emph on -What goes into the output directory? -\emph default - -\begin_inset Newline newline -\end_inset - -Each job's output ( -\family typewriter -stdout -\family default - and -\family typewriter -stderr -\family default -) goes into the directories -\emph on -stdout -\emph default - and -\emph on -stderr -\emph default -. - -\begin_inset Newline newline -\end_inset - -Each job also has a log which goes into the -\emph on -log -\emph default - directory. - -\end_layout - -\begin_layout Itemize - -\emph on -How do I put extra parameters in the Condor submit scripts? -\emph default - -\begin_inset Newline newline -\end_inset - -You can use a hash called -\family typewriter -%binary_grid::grid_options{condor_options} -\family default - e.g. -\begin_inset Newline newline -\end_inset - - -\family typewriter -$binary_grid::grid_options{condor_options}{Requirements}='Machine!= -\begin_inset Quotes erd -\end_inset - -aibn73.astro.uni-bonnv.de -\begin_inset Quotes erd -\end_inset - -'; -\end_layout - -\begin_layout Itemize - -\emph on -I have problems running my script with errors -\family typewriter -/export/\SpecialChar ldots - -\family default - not found -\emph default - -\begin_inset Newline newline -\end_inset - -The problem here is the -\family typewriter -/export -\family default - is local to your PC: you should run your script from -\family typewriter -/vol/\SpecialChar ldots - -\family default - (a world-readable NFS mount point) instead. - There is a function in the example condor scripts called -\family typewriter -fix_aifa_environment( -\family default -) ... - try using it. -\end_layout - -\begin_layout Itemize - -\emph on -Condor jobs are using all my CPU! -\emph default - -\begin_inset Newline newline -\end_inset - -They should be niced (nice -n 19) and preferably ioniced (ionice -c3) and - given SCHED_IDLE priority ( -\family typewriter -chrt -i -p 0 -\emph on -<pid> -\family default -\emph default -) as well. - The -\emph on -rob_misc -\emph default - Perl module is used to do this automatically (with a call to -\family typewriter -renice_me(); -\family default -) There are issues with the -\emph on -Linux -\emph default - kernel and -\emph on -cgroups -\emph default - which are pending. -\end_layout - -\begin_layout Itemize - -\emph on -Condor jobs run fine but then crash when joining the data hashes -\emph default - -\begin_inset Newline newline -\end_inset - -Check that you have sufficient RAM available: when joining the data hashses, - you need twice as much memory as normal because there are two copies of - the hashes in RAM at the same time. -\end_layout - -\begin_layout Standard -\begin_inset Newpage pagebreak -\end_inset - - -\end_layout - -\begin_layout Section -Initial distributions (IMF etc.) -\end_layout - -\begin_layout Standard -\begin_inset CommandInset label -LatexCommand label -name "sec:initial-dists" - -\end_inset - -The initial distributions of stellar masses, mass ratios, separations and - periods are handled by the -\emph on -distribution_functions -\emph default - Perl module. - The general idea is that given a set of stellar parameters -\begin_inset Formula $M_{1}$ -\end_inset - -, -\begin_inset Formula $M_{2}$ -\end_inset - - and -\begin_inset Formula $a$ -\end_inset - - (or -\begin_inset Formula $P$ -\end_inset - -) and phase volume -\begin_inset Formula $\delta\ln M_{1}$ -\end_inset - -, -\begin_inset Formula $\delta\ln M_{2}$ -\end_inset - - and -\begin_inset Formula $\delta\ln a$ -\end_inset - - (or -\begin_inset Formula $\delta\ln P$ -\end_inset - -) the probability of existence of star -\begin_inset Formula $i$ -\end_inset - - is calculated from -\end_layout - -\begin_layout Standard -\begin_inset Formula -\begin{eqnarray} -p_{i} & = & \Psi(M_{1})\Phi(M_{2})\chi(a)\,\delta\ln M_{1}\,\delta\ln M_{2}\,\delta\ln a\nonumber \\ - & = & \Psi\Phi\chi\delta\ln V\label{eq:prob-eq} -\end{eqnarray} - -\end_inset - -where -\begin_inset Formula $\delta\ln V$ -\end_inset - - is the 'phasevol' (as stored in the progenitor hash, see Section -\begin_inset space ~ -\end_inset - - -\begin_inset CommandInset ref -LatexCommand ref -reference "sec:grid-options" - -\end_inset - -). - The functions -\begin_inset Formula $\Psi$ -\end_inset - -, -\begin_inset Formula $\Phi$ -\end_inset - - and -\begin_inset Formula $\chi$ -\end_inset - - are not necessarily independent (e.g. - -\begin_inset Formula $\Phi(M_{2})$ -\end_inset - - may actually be -\begin_inset Formula $\Phi(q=M_{2}/M_{1})$ -\end_inset - - in which case it depends on -\begin_inset Formula $M_{1}$ -\end_inset - -) but the assumption we make is that -\begin_inset Formula $p_{i}$ -\end_inset - - is separable. - Note that -\begin_inset Formula $\sum p_{i}$ -\end_inset - - must add to one, i.e. - -\begin_inset Formula $\int p\,dV=1$ -\end_inset - -. - In general, each of the distributions must also satisfy -\begin_inset Formula $\int\Psi(M_{1})dM_{1}=\int\Psi(M_{2})dM_{2}=\int\chi(a)da=1$ -\end_inset - - where the integrals are from -\begin_inset Formula $-\infty$ -\end_inset - - to -\begin_inset Formula $+\infty$ -\end_inset - -. -\end_layout - -\begin_layout Standard -There are many forms for each initial distributions and they depend on which - authors you believe and/or which stars you are looking at (e.g. - low- or high-mass stars). - There is no one true answer – yet! -\end_layout - -\begin_layout Subsection -Predefined functions in the distribution_functions module -\end_layout - -\begin_layout Standard -\begin_inset CommandInset label -LatexCommand label -name "subsec:distribution functions predefined functions" - -\end_inset - - -\end_layout - -\begin_layout Description -const( -\begin_inset Formula $a$ -\end_inset - -, -\begin_inset Formula $b$ -\end_inset - -, -\begin_inset Formula $x$ -\end_inset - -) Returns a constant distribution function between -\begin_inset Formula $x$ -\end_inset - - and -\begin_inset Formula $y$ -\end_inset - - i.e. - returns -\begin_inset Formula $1/(b-a)$ -\end_inset - -. - -\begin_inset Formula $x$ -\end_inset - - is optional, if given then a result is returned only if -\begin_inset Formula $a\geq x\geq b$ -\end_inset - -, otherwise zero. - (This is useful for specifying a flat- -\begin_inset Formula $q$ -\end_inset - - distribution for the secondary mass or a flat- -\begin_inset Formula $\ln a$ -\end_inset - - separation distribution.) -\end_layout - -\begin_layout Description -powerlaw( -\begin_inset Formula $a$ -\end_inset - -, -\begin_inset Formula $b$ -\end_inset - -, -\begin_inset Formula $k$ -\end_inset - -, -\begin_inset Formula $x$ -\end_inset - -) A power-law distribution in -\begin_inset Formula $x$ -\end_inset - - between -\begin_inset Formula $a$ -\end_inset - - and -\begin_inset Formula $b$ -\end_inset - - with slope -\begin_inset Formula $k$ -\end_inset - -, zero if out of range. -\end_layout - -\begin_layout Description -three_part_power_law( -\begin_inset Formula $x$ -\end_inset - -, -\begin_inset Formula $x_{0}$ -\end_inset - -, -\begin_inset Formula $x_{1}$ -\end_inset - -, -\begin_inset Formula $x_{2}$ -\end_inset - -, -\begin_inset Formula $x_{\mathrm{max}}$ -\end_inset - -, -\begin_inset Formula $p_{1}$ -\end_inset - -, -\begin_inset Formula $p_{2}$ -\end_inset - -, -\begin_inset Formula $p_{3}$ -\end_inset - -, -\family typewriter -$consts -\family default -) A three-part power-law distrubition between -\begin_inset Formula $x_{0}$ -\end_inset - - and -\begin_inset Formula $x_{\mathrm{max}}$ -\end_inset - -, with slopes -\begin_inset Formula $p_{i}$ -\end_inset - - between -\begin_inset Formula $x_{i-1}$ -\end_inset - - and -\begin_inset Formula $x_{i}$ -\end_inset - - ( -\begin_inset Formula $i=1,2,3$ -\end_inset - -), zero otherwise. - -\end_layout - -\begin_layout Description -ktg93( -\begin_inset Formula $M$ -\end_inset - -) A wrapper function to use the -\begin_inset CommandInset citation -LatexCommand citet -key "KTG1993MNRAS-262-545K" -literal "true" - -\end_inset - - initial mass function for mass -\begin_inset Formula $M$ -\end_inset - -. - All the constants are set up for you, you just have to specify the mass - -\begin_inset Formula $M$ -\end_inset - -. - -\end_layout - -\begin_layout Description -Kroupa2001( -\begin_inset Formula $M$ -\end_inset - -) A wrapper function to use the -\begin_inset CommandInset citation -LatexCommand citet -key "2001MNRAS.322..231K" -literal "true" - -\end_inset - - mass function, similar in design to -\emph on -ktg93 -\emph default - above. -\end_layout - -\begin_layout Description -gaussian( -\begin_inset Formula $x$ -\end_inset - -, -\begin_inset Formula $\mu$ -\end_inset - -, -\begin_inset Formula $\sigma$ -\end_inset - -, -\begin_inset Formula $x_{\mathrm{min}}$ -\end_inset - -, -\begin_inset Formula $x_{\mathrm{max}}$ -\end_inset - -) A Gaussian distribution, mean -\begin_inset Formula $\mu$ -\end_inset - -, variance -\begin_inset Formula $\sigma,$ -\end_inset - - between -\begin_inset Formula $x_{\mathrm{min}}$ -\end_inset - - and -\begin_inset Formula $x_{\mathrm{max}}$ -\end_inset - - evaluated at -\begin_inset Formula $x$ -\end_inset - -. -\end_layout - -\begin_layout Standard -\begin_inset Newpage pagebreak -\end_inset - - -\end_layout - -\begin_layout Section -Grid spacings -\end_layout - -\begin_layout Standard -\begin_inset CommandInset label -LatexCommand label -name "sec:The-spacing_functions-module" - -\end_inset - -The -\emph on -spacing_functions -\emph default -module is used to set up the grid spacings. - At the moment there are only a few functions, but you can add your own - of course. -\end_layout - -\begin_layout Description -const( -\begin_inset Formula $x_{\mathrm{min}}$ -\end_inset - -, -\begin_inset Formula $x_{\mathrm{max}}$ -\end_inset - -, -\begin_inset Formula $n$ -\end_inset - -) Constant spacing between -\begin_inset Formula $x_{\mathrm{min}}$ -\end_inset - - and -\begin_inset Formula $x_{\mathrm{max}}$ -\end_inset - - with -\begin_inset Formula $n$ -\end_inset - - steps, i.e. - spacing -\begin_inset Formula $dx=(x_{\mathrm{max}}-x_{\mathrm{min}})/n$ -\end_inset - -. -\end_layout - -\begin_layout Description -number( -\begin_inset Formula $x$ -\end_inset - -) Simply returns -\begin_inset Formula $x$ -\end_inset - -, i.e. - spacing -\begin_inset Formula $dx=x$ -\end_inset - -. -\end_layout - -\begin_layout Description -const_dt This is a special distribution which chooses primary masses -\begin_inset Formula $M_{1}$ -\end_inset - - such that the stellar lifetime between two stars -\begin_inset Formula $\delta t=\delta t(M_{1})$ -\end_inset - - is constant. - This is very useful for making grids to calculate e.g. - yields as a function of time for a large number of timesteps. - Note that in this case, such a distribution is -\emph on -far -\emph default - more efficient than, say, fixed in -\begin_inset Formula $\log M$ -\end_inset - -. - This distribution also has options to increase the resolution for low- - and high-mass stars, as well as around the helium-flash mass, and can work - in -\begin_inset Formula $\log_{10}t$ -\end_inset - - instead of -\begin_inset Formula $t$ -\end_inset - -. - See Sec. -\begin_inset space ~ -\end_inset - - -\begin_inset CommandInset ref -LatexCommand ref -reference "Recipe:time-resolved-mass-grid" - -\end_inset - - for an example of its use. -\end_layout - -\begin_layout Standard -\begin_inset Newpage pagebreak -\end_inset - - -\end_layout - -\begin_layout Section -The Thread Model -\end_layout - -\begin_layout Standard -\begin_inset CommandInset label -LatexCommand label -name "sec:The-Thread-Model" - -\end_inset - -CPUs used to be simple devices that did one job at a time. - No more: every CPU these days has multiple -\emph on -cores -\emph default - which can run simultaneously while sharing system resources (e.g. - RAM, disk). - Binary_grid takes advantage of this by splitting the workload of running - stars over a parameter space into multiple -\emph on -threads -\emph default - which run concurrently, thus speeding up execution of the grid. -\end_layout - -\begin_layout Standard -When you call -\emph on -flexigrid -\emph default -it takes a single argument: the number of child threads. - Let's say you launch -\emph on -flexigrid(4); -\emph default -then the parent thread launches four children which are managed in a thread - queue (using Perl's Thread::Queue module). - Each star you want to run is placed in the queue and the threads pull them - off one by one until the parameter space is complete. -\end_layout - -\begin_layout Subsection -Thread resources -\end_layout - -\begin_layout Standard -\begin_inset CommandInset label -LatexCommand label -name "subsec:thread-resources" - -\end_inset - -Each thread stores its results in a -\emph on -hash table -\emph default -(marked by % in -\emph on -Perl -\emph default -, see -\begin_inset Newline newline -\end_inset - - -\begin_inset CommandInset href -LatexCommand href -target "http://en.wikipedia.org/wiki/Hash_function#Hash_tables" -literal "false" - -\end_inset - - and -\begin_inset CommandInset href -LatexCommand href -target "http://www.perltutorial.org/perl-hash.aspx" -literal "false" - -\end_inset - -, if you know about -\emph on -Python -\emph default -dictionaries, these are pretty much the same). - This is like an array, which is probably familiar to you from other programming - languages e.g. - -\emph on -C -\emph default -, -\emph on -C++ -\emph default - and -\emph on -FORTRAN -\emph default -, but instead of using numbers (e.g. - 0, 1, 2\SpecialChar ldots -) as indices, it uses -\emph on -keys -\emph default - instead which can be any scalar, i.e. - strings or numbers. - Hashes can be nested, e.g. - as hashes of hashes or hashes of arrays etc. - This concept is very powerful because it allows you to store the results - of your population synthesis in a -\emph on -single hash table. - -\emph default - Because hashes can be nested, a single table can store -\emph on -everything -\emph default - you can throw at it. - -\end_layout - -\begin_layout Standard -Each thread has its own hash, usually accessed (e.g. - in -\emph on -parse_bse -\emph default -) through the variable $h (which is actually a -\emph on -reference -\emph default - to a hash, similar to a C pointer). - You put your data in -\emph on -$h -\emph default - and it is propagated where it is required. -\end_layout - -\begin_layout Standard -When the threads finish they are -\emph on -joined -\emph default - together – in this process, the thread's -\emph on -$h -\emph default - hash is added to a global hash (usually called -\emph on -%results -\emph default - or something similar): the mechanism to do this is automatically included - in -\emph on -binary_grid -\emph default -, you do not usually have to do anything yourself. - At the end of the grid, the -\emph on - %results -\emph default - hash contains the sum of the population synthesis over all the stars you - have run. - -\end_layout - -\begin_layout Subsection -CPU load and thread number -\end_layout - -\begin_layout Standard -\begin_inset CommandInset label -LatexCommand label -name "subsec:CPU load" - -\end_inset - -It is not obviously clear how many threads you should launch even if you - know the number of CPUs in your system. - If your -\emph on -binary_c -\emph default - process does a lot of work and outputs very little, then -\emph on -binary_grid -\emph default - will not have much processing to do and you may as well launch as many - threads as you have CPUs. - However, if -\emph on -binary_c -\emph default - outputs a lot of data (e.g. - at every timestep) then -\emph on -binary_grid -\emph default - will have to work hard to keep up and you may need as much (or more!) CPU - for -\emph on - binary_grid -\emph default - as -\emph on -binary_c -\emph default -. - Remember that each Perl -\emph on -binary_grid -\emph default - thread launches its own binary_c, so if you have -\begin_inset Formula $N$ -\end_inset - - CPUs, you might want -\begin_inset Formula $N/2$ -\end_inset - - threads for the fastest possible grid. -\end_layout - -\begin_layout Standard -The best option is to experiment with a limited (low-resolution) parameter - space and gradually increase the number of stars while changing the number - of threads. - This is, in any case, good practice for debugging your newly programmed - code. - -\end_layout - -\begin_layout Subsection -Memory usage -\end_layout - -\begin_layout Standard -\begin_inset CommandInset label -LatexCommand label -name "subsec:memory usage" - -\end_inset - -Each thread stores its data in its own hash, so the more threads you have - the more memory you will use. - If you are not saving much data, this will not bother you, but obviously - if you save a lot of high-resolution data you may start to use a lot of - RAM. - -\end_layout - -\begin_layout Standard -You should bin your hash keys to save RAM: consider this example. - If you save the luminosity at each timestep, you will end up with hashes - with keys (e.g.) 1.0, 1.0001, 1.0002, 1.0003 etc. - Very quickly – in seconds! – you will have more data than you or your RAM - can handle. - Instead, bin your data and use logarithms when you can. - Binary_grid has a bin_data function for this, e.g. - -\family typewriter -$logL=bin_data(log10($L),0.1); -\family default - bins the logarithm of -\family typewriter -$L -\family default - (e.g. - the luminosity) to the nearest -\begin_inset Formula $0.1\,\mathrm{dex}$ -\end_inset - -. - -\end_layout - -\begin_layout Standard -Remember that if each thread uses -\begin_inset Formula $N$ -\end_inset - - megabytes of RAM and you have -\begin_inset Formula $n$ -\end_inset - - threads, the maximum RAM use is -\begin_inset Formula $\sim2nN$ -\end_inset - - because, when the data is joined, the main thread contains a copy of all - the data as well. - While binary_grid tries very hard to use as little memory as possible, - such that the total memory use is -\begin_inset Formula $<2nN$ -\end_inset - -, your grid may fail at the thread join step if there is not sufficient - RAM. - In the case of an HTCondor grid, your data files are preserved and you - can simply rerun the final grid join step on a machine with more memory. -\end_layout - -\begin_layout Subsection - -\family typewriter -%threadinfo -\family default - variables -\end_layout - -\begin_layout Standard -\begin_inset CommandInset label -LatexCommand label -name "subsec:thread variables" - -\end_inset - -Each thread sets its own copy of the -\family typewriter -%binary_grid::threadinfo -\family default - hash, containing information relevant only to the thread. - Most of this is used internally but you have access to it (do not change - it unless you know what you are doing!). -\end_layout - -\begin_layout Labeling -\labelwidthstring 00.00.0000 - -\emph on -evcode_pid -\emph default - binary_c/nucsyn process id associated with this thread -\end_layout - -\begin_layout Labeling -\labelwidthstring 00.00.0000 - -\emph on -cmd -\emph default - Internal thread command number (used to label various stop conditions) -\end_layout - -\begin_layout Labeling -\labelwidthstring 00.00.0000 - -\emph on -h -\emph default - Reference to the data hash filled by this thread ( -\emph on -$h -\emph default - in -\emph on -parse_bse -\emph default -) -\end_layout - -\begin_layout Labeling -\labelwidthstring 00.00.0000 - -\emph on -lastargs -\emph default - The last argument string which was fed to binary_c/nucsyn -\end_layout - -\begin_layout Labeling -\labelwidthstring 00.00.0000 - -\emph on -runtime -\emph default - The total runtime of the thread (including Perl) -\end_layout - -\begin_layout Labeling -\labelwidthstring 00.00.0000 - -\emph on -runcount -\emph default - The number of stars run by this thread -\end_layout - -\begin_layout Labeling -\labelwidthstring 00.00.0000 - -\emph on -state -\emph default - Thread state variable: 0=finished, 1=running -\end_layout - -\begin_layout Labeling -\labelwidthstring 00.00.0000 - -\emph on -thread_number -\emph default -The unique thread number (starts at zero) -\end_layout - -\begin_layout Labeling -\labelwidthstring 00.00.0000 - -\emph on -thread_queue -\emph default - The thread queue object (see the CPAN module -\emph on -Thread::Queue -\emph default -) -\end_layout - -\begin_layout Labeling -\labelwidthstring 00.00.0000 - -\emph on -tstart -\emph default - Start time of the thread (from -\family typewriter -[gettimeofday] -\family default -) -\end_layout - -\begin_layout Labeling -\labelwidthstring 00.00.0000 - -\emph on -tvb_fp -\emph default - File (pointer) to which output is sent if -\family typewriter -$binary_grid::grid_options{tvb} -\family default - is true -\end_layout - -\begin_layout Labeling -\labelwidthstring 00.00.0000 - -\emph on -tvb_repeat -\emph default - Thread logging control variable (prevents repeated lines) -\end_layout - -\begin_layout Labeling -\labelwidthstring 00.00.0000 - -\emph on -tvb_last -\emph default - The previous thread log line -\end_layout - -\begin_layout Labeling -\labelwidthstring 00.00.0000 - -\emph on -tvb_lasttime -\emph default -The time of the previous output to the thread log -\end_layout - -\begin_layout Labeling -\labelwidthstring 00.00.0000 - -\emph on -thread_prev_alive -\emph default - Thread timer (from -\family typewriter -time() -\family default -): this is the time the thread last registered as being alive -\end_layout - -\begin_layout Labeling -\labelwidthstring 00.00.0000 - -\emph on -thread_prev_complaint -\emph default - Thread timer (from -\family typewriter -time() -\family default -): this is the time the thread last registered a complaint about taking - too long -\end_layout - -\begin_layout Standard -\begin_inset Newpage pagebreak -\end_inset - - -\end_layout - -\begin_layout Section -Debugging, benchmarking and advanced topics -\end_layout - -\begin_layout Standard -\begin_inset CommandInset label -LatexCommand label -name "sec:debugging" - -\end_inset - -This section provides a summary of debugging options and suggestions for - ways to fix your code (or -\emph on -binary_grid -\emph default -!). - -\end_layout - -\begin_layout Subsection -Debugging options -\end_layout - -\begin_layout Itemize - -\family typewriter -$binary_grid::grid_options{'vb'} -\family default - -\begin_inset Newline newline -\end_inset - -See Section -\begin_inset space ~ -\end_inset - - -\begin_inset CommandInset ref -LatexCommand ref -reference "subsec:Verbosity" - -\end_inset - - below. -\end_layout - -\begin_layout Itemize - -\family typewriter -$binary_grid::grid_options{'tvb'} -\family default -controls individual thread logging. -\end_layout - -\begin_layout Itemize - -\family typewriter -$binary_grid::grid_options{'log_args'} -\family default - will output the arguments sent to -\emph on -binary_c/nucsyn -\emph default - in files in -\family typewriter -/tmp/binary_c.thread_$n.lastargs -\family default - where -\family typewriter -$n -\family default - is the thread number. - -\end_layout - -\begin_layout Itemize - -\family typewriter -$binary_grid::grid_options{'args'} -\family default - stores a single string with the raw arguments that were passed into -\emph on -binary_c/nucsyn -\emph default -. - This is useful if you want to do some debugging in the -\family typewriter -parse_bse -\family default - function (which has access to this variable). - Within a thread, this data is also accessible in -\family typewriter -$threadinfo{lastargs} -\family default -. -\end_layout - -\begin_layout Itemize - -\family typewriter -$binary_grid::grid_options{'progenitor'} -\family default - stores the progenitor information in a single string, in the following - order: duplicity, -\begin_inset Formula $M_{1}$ -\end_inset - -, -\begin_inset Formula $M_{2}$ -\end_inset - -, -\begin_inset Formula $P$ -\end_inset - -, -\begin_inset Formula $a$ -\end_inset - -, -\begin_inset Formula $e$ -\end_inset - -, -\begin_inset Formula $Z$ -\end_inset - -, -\begin_inset Formula $P$ -\end_inset - - and -\begin_inset Formula $\delta\ln V$ -\end_inset - - (the ' -\family typewriter -logphasevol -\family default -'= -\begin_inset Formula $\delta\ln M_{1}\delta\ln M_{2}\delta a$ -\end_inset - -). - If the star is a single star ( -\family typewriter -$grid_options{binary}==0 -\family default -) then -\begin_inset Formula $M_{2}$ -\end_inset - -, -\begin_inset Formula $P$ -\end_inset - -, -\begin_inset Formula $a$ -\end_inset - - and -\begin_inset Formula $e$ -\end_inset - - are omitted and -\begin_inset Formula $\delta\ln V=\delta\ln M$ -\end_inset - -. - This data is accessible from -\family typewriter -parse_bse -\family default -. -\end_layout - -\begin_layout Itemize -The nested hash -\family typewriter - -\begin_inset Newline newline -\end_inset - -%binary_grid::grid_options{'progenitor_hash'}{ -\begin_inset Formula $\dots$ -\end_inset - -} -\family default - -\begin_inset Newline newline -\end_inset - -contains the same information as the progenitor string (above) in a more - accessible form: the hash -\emph on -keys -\emph default - are binarity, -\begin_inset Formula $M_{1}$ -\end_inset - -, -\begin_inset Formula $M_{2}$ -\end_inset - -, -\begin_inset Formula $P$ -\end_inset - -, -\begin_inset Formula $a$ -\end_inset - -, -\begin_inset Formula $e$ -\end_inset - -, -\begin_inset Formula $Z$ -\end_inset - -, -\begin_inset Formula $P$ -\end_inset - - and -\begin_inset Formula $\delta\ln V$ -\end_inset - -, and the values contain the appropriate data. - Again, this is accessible from -\family typewriter -parse_bse -\family default -. - -\end_layout - -\begin_layout Itemize -Use the -\family typewriter -timeout -\family default - feature if your code is freezing. - This is -\emph on -not -\emph default - the same as fixing your problem, but you may be able to stop the code from - using all your CPU when it freezes! (Note that this uses Unix signals to - test for timeouts: it may not work e.g. - with the Condor queueing system). -\end_layout - -\begin_layout Subsection -Verbosity -\begin_inset CommandInset label -LatexCommand label -name "subsec:Verbosity" - -\end_inset - - -\end_layout - -\begin_layout Standard - -\family typewriter -$binary_grid::grid_options{'vb'} -\family default - controls the amount of grid output to the screen, usually lines showing - the number of stars evolved, the total number in the grid, the current - time, -\begin_inset Formula $M_{1}$ -\end_inset - -, -\begin_inset Formula $M_{2}$ -\end_inset - -, -\begin_inset Formula $a$ -\end_inset - -, -\begin_inset Formula $P$ -\end_inset - - and -\begin_inset Formula $Z$ -\end_inset - -, the probability, the total grid probability, -\begin_inset Formula $\%$ -\end_inset - - grid completion, estimated time until arrival (finish) i.e. - -\emph on -ETA -\emph default -, -\emph on -tpr -\emph default - (time per run), -\emph on -ETF -\emph default - (estimated time at which it will finish) and memory usage. - If set to 1 it shows output every second or every -\family typewriter -$binary_grid::grid_options{'nmod'} -\family default - models. - -\end_layout - -\begin_layout Standard -If -\family typewriter -vb -\family default - is set to -\family typewriter -2 -\family default - then more output, showing the arguments sent to -\emph on -binary_c/nucsyn -\emph default -, will be dumped onto the screen for each model. - This is only useful for small grids, for large grids it will overwhelm - you. - It is possible to set -\family typewriter -vb=3 -\family default - for even more output. -\begin_inset Newline newline -\end_inset - -Note that as of -\emph on -binary_grid -\emph default - 0.18 it is impossible to set -\family typewriter -vb -\family default - from inside your script if you are using the two-stage bootstrapping (which - you really should, see Section -\begin_inset space ~ -\end_inset - - -\begin_inset CommandInset ref -LatexCommand ref -reference "subsec:Two-stage-bootstrapping" - -\end_inset - - below): it -\emph on -must -\emph default - be sent on the command line that runs your script. -\end_layout - -\begin_layout Standard -Inside binary_grid.pm are many vbout( -\begin_inset Formula $n$ -\end_inset - -,\SpecialChar ldots -); statements. - These control the verbose output from binary_grid, such that the statement - is output to the screen -\emph on -only if -\family typewriter -\emph default -vb -\family default -\emph on - -\begin_inset Formula $\geq n$ -\end_inset - - -\emph default -. - If you want to insert new verbose statements, please use this format! -\end_layout - -\begin_layout Subsection -Benchmarking with subroutine timers -\begin_inset CommandInset label -LatexCommand label -name "subsec:Subroutine-timers" - -\end_inset - - -\end_layout - -\begin_layout Standard -If your grid is running slowly, you can use subroutine timers by first setting: -\end_layout - -\begin_layout Standard - -\family typewriter -$binary_grid::grid_options{timers}=1; -\family default - -\begin_inset Newline newline -\end_inset - -and then make a list of subroutines you would like to time: -\end_layout - -\begin_layout Standard - -\family typewriter -$binary_grid::grid_options{timer_subroutines}=['main::parse_bse','binary_out','p -rint_binary_in']; -\family default - -\begin_inset Newline newline -\end_inset - -Note that a default subroutine list is used (see -\emph on -binary_grid.pm -\emph default -) which includes most of the subroutines in -\emph on -binary_grid -\emph default -. - To see the results of the subroutine timing, put a call to -\end_layout - -\begin_layout Standard - -\family typewriter -output_binary_grid_timers(); -\family default - -\begin_inset Newline newline -\end_inset - -in your script before it exits. -\end_layout - -\begin_layout Standard -There is considerable overhead in activating subroutine timers, so your - grid will run possibly up to twice as slow as normal. - Timers should -\emph on -not -\emph default - be used for production code, but are very useful if you want to know what - is slowing you down. -\end_layout - -\begin_layout Standard -Note that some subroutines are designed to sit and wait for something to - happen (e.g. - -\emph on -binary_out -\emph default -) and these will therefore use up a lot of time. - This is normal: I have gone to great length to make these functions as - fast as possible (while keeping debugging and code-crash checking) – if - you can make them faster, great, but this will be difficult if you want - stability and error-checking. -\end_layout - -\begin_layout Subsection -Two-stage bootstrapping -\begin_inset CommandInset label -LatexCommand label -name "subsec:Two-stage-bootstrapping" - -\end_inset - - -\end_layout - -\begin_layout Standard -As of version 0.18 of -\emph on -binary_grid -\emph default -, the -\emph on -binary_grid -\emph default - module is loaded using a two-stage bootstrap technique. - The aim of this is to reduce the overhead of using verbose debugging statements - (and the like) in the -\emph on -binary_grid -\emph default - code by removing unnecessary code at runtime -\emph on -prior to compilation -\emph default -. - Perl is a superb language for doing this by means of its -\emph on -eval -\emph default - command. - Roughly, when you load -\emph on -binary_grid.pm -\emph default - the following happens: -\end_layout - -\begin_layout Enumerate -The module loads a few basic subroutines, including -\emph on -parse_args -\emph default - to check the command line arguments, especially to look for a -\emph on -vb=n -\emph default - switch that controls verbosity. -\end_layout - -\begin_layout Enumerate -The variable -\family typewriter -$binary_grid_code -\family default - is set up: this contains most of the module code. - This is then filtered to remove -\family typewriter -vbout() -\family default - and -\family typewriter -verbose_output() -\family default - statements that would never output anything, based on your choice of the - -\family typewriter -vb -\family default - grid_option (as given in the arguments to your script). - Note that the useless code is -\emph on -completely removed -\emph default - rather than left to always do nothing. -\end_layout - -\begin_layout Enumerate -The -\family typewriter -$binary_grid_code -\family default - is eval'd, i.e. - compiled at runtime. -\end_layout - -\begin_layout Standard -This -\emph on -bootstrapping -\emph default - eliminates the overhead of calls to the vbout subroutine, and its check - of the -\family typewriter -vb -\family default - variable. - You may think this overhead is small, but it really is not. - The reason is that the arguments to a Perl subroutine are evaluated -\emph on -prior -\emph default -to the call. - This often makes sense, but if the arguments are (say) long lists that - need joining, this takes valuable CPU time – and for nothing! -\end_layout - -\begin_layout Standard -Benchmarking tests with subroutine timers (see Section -\begin_inset space ~ -\end_inset - - -\begin_inset CommandInset ref -LatexCommand ref -reference "subsec:Subroutine-timers" - -\end_inset - -) show a considerable saving by using this technique, sometimes up to a - factor of two in runtime. - Bootstrapping is set to be on by default, but can be disabled by setting -\begin_inset Newline newline -\end_inset - - -\family typewriter -$binary_grid::grid_options{binary_grid_code_filtering}=0; -\end_layout - -\begin_layout Standard -If you have problems, e.g. - the -\emph on -eval -\emph default -step fails, you should be able to spot this at module installation time - (e.g. - -\emph on - cpanm -\emph default - will fail). - Alternatively, you can set -\family typewriter -$binary_grid::grid_options{pre_filter_file} -\family default - and -\family typewriter -$binary_grid::grid_options{post_filter_file} -\family default - to dump the contents of -\family typewriter -$binary_grid_code -\family default - to files, which you can then diff to determine what went wrong. - -\end_layout - -\begin_layout Standard -Note that, if you use the bootstrapping – which you really should! – you - -\emph on -must -\emph default - set -\family typewriter -vb -\family default - in the arguments to your script. - Any later settings (e.g. - setting the variable manually inside your script) will be ignored. -\end_layout - -\begin_layout Standard -\begin_inset Newpage pagebreak -\end_inset - - -\end_layout - -\begin_layout Section -Future Plans -\end_layout - -\begin_layout Standard -\begin_inset CommandInset label -LatexCommand label -name "sec:future-plans" - -\end_inset - - -\end_layout - -\begin_layout Itemize -A graphical frontend would be good! Please write one for me. -\end_layout - -\begin_layout Standard -\begin_inset Newpage pagebreak -\end_inset - - -\end_layout - -\begin_layout Section -Cookbook -\end_layout - -\begin_layout Standard -\begin_inset CommandInset label -LatexCommand label -name "sec:Cookbook" - -\end_inset - -This section contains some examples of how to use the -\emph on -flexigrid -\emph default -. -\end_layout - -\begin_layout Subsection -Star Formation History -\end_layout - -\begin_layout Standard -\begin_inset CommandInset label -LatexCommand label -name "Recipe-SFR" - -\end_inset - -You may not want to use a constant star formation rate (SFR). - If you can live with all your models having the same input physics (i.e. - metallicity, etc.) you can easily fold in a star formation history (SFH). -\end_layout - -\begin_layout Enumerate -Make sure you know the -\emph on -time -\emph default - at each output of -\emph on -binary_c -\emph default -, let's call this -\family typewriter -$t -\family default -. -\end_layout - -\begin_layout Enumerate -You also need -\begin_inset Formula $dt\times p$ -\end_inset - -, i.e. - -\family typewriter -$dtp -\family default -, at each timestep. -\end_layout - -\begin_layout Enumerate -Weight -\family typewriter -$dtp -\family default - by a SFR function: -\begin_inset Newline newline -\end_inset - - -\family typewriter -$dtp *= SFR($binary_grid::bse_options{'max_evolution_time'}-$t); -\end_layout - -\begin_layout Standard -You have to write the SFR function yourself, e.g. - -\end_layout - -\begin_layout Standard -\begin_inset Box Boxed -position "t" -hor_pos "c" -has_inner_box 1 -inner_pos "t" -use_parbox 0 -use_makebox 0 -width "100col%" -special "none" -height "1in" -height_special "totalheight" -thickness "0.4pt" -separation "3pt" -shadowsize "4pt" -framecolor "black" -backgroundcolor "none" -status open - -\begin_layout Plain Layout - -\family typewriter -sub SFR -\end_layout - -\begin_layout Plain Layout - -\family typewriter -{ -\end_layout - -\begin_layout Plain Layout - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -# SFR as a function of Galactic age in Myr -\end_layout - -\begin_layout Plain Layout - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -my $t=$_[0]; # Galactic age -\end_layout - -\begin_layout Plain Layout - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -return 1.0; # const SFR -\end_layout - -\begin_layout Plain Layout - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -return $t<1.0e3 ? 1.0 : 0.0; # const for the first Gyr -\end_layout - -\begin_layout Plain Layout - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -return exp(-$t/10e3); # exponential dropoff over 10Gyr -\end_layout - -\begin_layout Plain Layout - -\family typewriter -} -\end_layout - -\end_inset - - -\end_layout - -\begin_layout Standard -How does this work? What you're passing into the SFR function is -\begin_inset Formula $t_{\mathrm{max}}-t$ -\end_inset - -, which is effectively the time at which the star was born, assuming everything - begin -\begin_inset Formula $t_{\mathrm{max}}$ -\end_inset - - ago. -\end_layout - -\begin_layout Standard -This does not describe the overall normalization, e.g. - if you want -\begin_inset Formula $N$ -\end_inset - - stars in total. - You have to add up the statistic appropriate to -\begin_inset Formula $N$ -\end_inset - - (i.e. - the number of stars seen -\emph on -now -\emph default -) and apply this to your results. -\end_layout - -\begin_layout Subsection -Aliasing -\end_layout - -\begin_layout Standard -\begin_inset CommandInset label -LatexCommand label -name "Recipe:aliasing" - -\end_inset - -You output your histogram but it's all spiky and noisy! What's wrong? The - simple answer is that you don't have enough stars on your grid for the - bin width of your histogram. - (See e.g. - -\begin_inset Newline newline -\end_inset - - -\begin_inset CommandInset href -LatexCommand href -target "http://en.wikipedia.org/wiki/Nyquist-Shannon_sampling_theorem" -literal "false" - -\end_inset - -) Solutions are: -\end_layout - -\begin_layout Enumerate -More stars -\end_layout - -\begin_layout Enumerate -Wider bins -\end_layout - -\begin_layout Standard -Now, I hear you cry that your old Monte Carlo code gives a lovely smooth - histogram. - Yes, for the same number of stars, it might. - But it might also give you worse spikes. - With a MC code you can never guarantee resolution, and in the limit of - a large number of stars the result is the same. - At least with a grid-based solution you can -\emph on -see -\emph default - the spikes so you -\emph on -know -\emph default -the limit of your resolution. - With an MC code you're just playing dice (see the FAQ -\begin_inset CommandInset ref -LatexCommand ref -reference "FAQ:why not MC?" - -\end_inset - -). -\end_layout - -\begin_layout Standard -Usually I just run with more stars. - See also Recipe -\begin_inset space ~ -\end_inset - - -\begin_inset CommandInset ref -LatexCommand ref -reference "Recipe-SFR" - -\end_inset - - above. -\end_layout - -\begin_layout Subsection -Time-resolved mass grid -\end_layout - -\begin_layout Standard -\begin_inset CommandInset label -LatexCommand label -name "Recipe:time-resolved-mass-grid" - -\end_inset - -Some problems require a more carefully spaced grid than the simple -\begin_inset Formula $\ln M$ -\end_inset - - grid. - A good example is the calculation of stellar yields. - The yield sets are generally required to give yields out to a time of many - -\begin_inset Formula $\mathrm{Gyr}$ -\end_inset - - and with a time resolution of, say, -\begin_inset Formula $10\,\mathrm{Myr}$ -\end_inset - -. - At early times this is not a problem, but at late times the stellar lifetime - scales with the mass as -\begin_inset Formula $t\sim M^{3}$ -\end_inset - - (roughly) so in order to have good time resolution we require -\begin_inset Formula $\delta M\sim\delta t/(3M^{2})\sim t^{-2/3}\delta t$ -\end_inset - - which is rather small at late times when -\begin_inset Formula $t$ -\end_inset - - is large. - -\end_layout - -\begin_layout Standard -We could just set a normal log-mass grid and have a very large resolution. - A smarter alternative is to set up the grid to -\emph on -enforce -\emph default - -\begin_inset Formula $\delta M=f\times\delta t/(3M^{2})$ -\end_inset - - as our grid spacing (with a factor -\begin_inset Formula $f<1$ -\end_inset - - which ensures over-resolution to avoid gridding artifacts). - Implementations of this, and a fixed -\begin_inset Formula $\delta\ln t$ -\end_inset - - grid, are available in -\emph on -binary_grid -\emph default - via the -\emph on -spacing_functions -\emph default -module. -\end_layout - -\begin_layout Standard -In the HRD project with Peter Anders, I use the following: -\end_layout - -\begin_layout Standard -\begin_inset Box Boxed -position "t" -hor_pos "c" -has_inner_box 1 -inner_pos "t" -use_parbox 0 -use_makebox 0 -width "100col%" -special "none" -height "1in" -height_special "totalheight" -thickness "0.4pt" -separation "3pt" -shadowsize "4pt" -framecolor "black" -backgroundcolor "none" -status open - -\begin_layout Plain Layout - -\family typewriter -# Mass 1 -\end_layout - -\begin_layout Plain Layout - -\family typewriter -$binary_grid::grid_options{'flexigrid'}{'grid variable '.$nvar++}= -\end_layout - -\begin_layout Plain Layout - -\family typewriter -{ -\end_layout - -\begin_layout Plain Layout - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -'name'=> 'lnm1', -\end_layout - -\begin_layout Plain Layout - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -'longname'=>'Primary mass', -\end_layout - -\begin_layout Plain Layout - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -'range'=>["log(0.1)","log(80)"], -\end_layout - -\begin_layout Plain Layout - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -# const_dt spacing function options -\end_layout - -\begin_layout Plain Layout - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -'preloopcode'=>" -\end_layout - -\begin_layout Plain Layout - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -my -\backslash -$const_dt_opts= -\backslash -{ -\end_layout - -\begin_layout Plain Layout - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -max_evolution_time=>20000, -\end_layout - -\begin_layout Plain Layout - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -stellar_lifetime_table_nm=>100, -\end_layout - -\begin_layout Plain Layout - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -nthreads=>1, -\end_layout - -\begin_layout Plain Layout - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -thread_sleep=>1, -\end_layout - -\begin_layout Plain Layout - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -mmin=>0.1, -\end_layout - -\begin_layout Plain Layout - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -mmax=>80.0, -\end_layout - -\begin_layout Plain Layout - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -time_adaptive_mass_grid_log10_time=>1, -\end_layout - -\begin_layout Plain Layout - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -time_adaptive_mass_grid_log10_step=>0.05, -\end_layout - -\begin_layout Plain Layout - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -time_adaptive_mass_grid_step=>100, -\end_layout - -\begin_layout Plain Layout - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -extra_flash_resolution=>0, -\end_layout - -\begin_layout Plain Layout - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -time_adaptive_mass_grid_nlow_mass_stars=>10, -\end_layout - -\begin_layout Plain Layout - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -debugging_output_directory=>undef,#'/tmp/adaptive_mass_grid', -\end_layout - -\begin_layout Plain Layout - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -max_delta_m=>2.0, -\end_layout - -\begin_layout Plain Layout - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -savegrid=>undef, -\end_layout - -\begin_layout Plain Layout - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -vb=>0, -\end_layout - -\begin_layout Plain Layout - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\backslash -}; -\end_layout - -\begin_layout Plain Layout - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -spacing_functions::const_dt( -\backslash -$const_dt_opts,'reset');", -\end_layout - -\begin_layout Plain Layout - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -# use const_dt function -\end_layout - -\begin_layout Plain Layout - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -'spacingfunc'=>"const_dt( -\backslash -$const_dt_opts,'next')", -\end_layout - -\begin_layout Plain Layout - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -# and its resolution -\end_layout - -\begin_layout Plain Layout - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -'resolution'=>"spacing_functions::const_dt( -\backslash -$const_dt_opts,'resolution');", -\end_layout - -\begin_layout Plain Layout - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -'precode'=>'$m1=exp($lnm1); $eccentricity=0.0;', -\end_layout - -\begin_layout Plain Layout - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -'probdist'=>"Kroupa2001( -\backslash -$m1)* -\backslash -$m1", -\end_layout - -\begin_layout Plain Layout - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -'dphasevol'=>'$dlnm1', -\end_layout - -\begin_layout Plain Layout - -\family typewriter -}; -\end_layout - -\end_inset - - -\end_layout - -\begin_layout Standard -The key line is -\family typewriter -time_adaptive_mass_grid_log10_step=>0.05 -\family default - which specifies that I want ( -\begin_inset Formula $\log_{10}$ -\end_inset - -) time resolved to every -\begin_inset Formula $0.05\,\mathrm{dex}$ -\end_inset - -. - Note how I set up the -\family typewriter -$const_dt_opts anonymous -\family default - hash of options and then send it via the spacing function with the option -\family typewriter - 'reset' -\family default -. - This sets up a list of masses which are just returned for each call to - -\family typewriter -const_dt() -\family default - with the -\family typewriter -'next' -\family default - parameter. - Calling -\family typewriter -const_dt() -\family default - with the -\family typewriter -'resolution' -\family default - parameter just returns the number of masses in the list, which is trivially - the resolution. -\end_layout - -\begin_layout Subsection -Single and binary stars combined -\end_layout - -\begin_layout Standard -\begin_inset CommandInset label -LatexCommand label -name "Recipe:Single and binary stars" - -\end_inset - -You can set up a grid containing both single and binary stars quite easily. - The following code defines a grid variable -\begin_inset Quotes eld -\end_inset - - -\emph on -duplicity -\emph default - -\begin_inset Quotes erd -\end_inset - - which is either 0 or 1, and sets the grid_option -\begin_inset Quotes eld -\end_inset - -binary -\begin_inset Quotes erd -\end_inset - - appropriately. - Deeper nested grid variables can then depend on the duplicity and choose, - through the -\emph on -condition -\emph default -variable, whether to execute grids over -\begin_inset Formula $M_{2}$ -\end_inset - - and beyond. -\end_layout - -\begin_layout Standard -\begin_inset Box Boxed -position "t" -hor_pos "c" -has_inner_box 1 -inner_pos "t" -use_parbox 0 -use_makebox 0 -width "100col%" -special "none" -height "1in" -height_special "totalheight" -thickness "0.4pt" -separation "3pt" -shadowsize "4pt" -framecolor "black" -backgroundcolor "none" -status open - -\begin_layout Plain Layout - -\family typewriter -# duplicity -\end_layout - -\begin_layout Plain Layout - -\family typewriter -$binary_grid::grid_options{'flexigrid'}{'grid variable '.$nvar++}= -\end_layout - -\begin_layout Plain Layout - -\family typewriter -{ -\end_layout - -\begin_layout Plain Layout - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -'name'=>'duplicity', -\end_layout - -\begin_layout Plain Layout - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -'longname'=>'Duplicity', -\end_layout - -\begin_layout Plain Layout - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -'range'=>[0,1], -\end_layout - -\begin_layout Plain Layout - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -'resolution'=>1, -\end_layout - -\begin_layout Plain Layout - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -'spacingfunc'=>'number(1.0)', -\end_layout - -\begin_layout Plain Layout - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -'precode'=>'$binary_grid::grid_options{binary}=$duplicity;', -\end_layout - -\begin_layout Plain Layout - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -'gridtype'=>'edge', -\end_layout - -\begin_layout Plain Layout - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -'noprobdist'=>1, -\end_layout - -\begin_layout Plain Layout - -\family typewriter -}; -\end_layout - -\end_inset - - -\end_layout - -\begin_layout Subsection -Snapshots: I want to stop a grid and restart later -\end_layout - -\begin_layout Standard -\begin_inset CommandInset label -LatexCommand label -name "subsec:snapshotting" - -\end_inset - -The ability to stop and restart the grid is called -\emph on -snapshotting -\emph default -. - Note that while this currently works, it assumes that you: -\end_layout - -\begin_layout Enumerate -Use the identical grid script to restart -\end_layout - -\begin_layout Enumerate -Do not change any of your installation ( -\emph on -binary_c -\emph default -, -\emph on -binary_grid -\emph default -, etc.) between stopping and restarting, -\end_layout - -\begin_layout Standard -thus snapshotting is quite limited in its functionality but it might save - your data when your computer is about to die. -\end_layout - -\begin_layout Subsubsection -Suspending the grid -\end_layout - -\begin_layout Standard - -\emph on -Binary_grid -\emph default - looks in files, defined in -\family typewriter -$binary_grid::grid_options{'suspend_files'}=[\SpecialChar ldots -] -\family default -, and if one exists, it executes its snapshot code. - To make one exist, use the Unix command -\emph on -touch -\emph default -e.g. - -\end_layout - -\begin_layout Standard - -\family typewriter -touch /tmp/force_binary_c_suspend -\end_layout - -\begin_layout Standard -This joins all the current threads and saves their data in one file so you - can restart it later. - It may take some time to join all the threads, so please be patient. - By default, binary_grid looks at the files /tmp/force_binary_c_suspend - and -\family typewriter -./force_binary_c_suspend -\family default - (although you can add your own with -\family typewriter -push(@$binary_grid::grid_options{'suspend_files'}, -\begin_inset Quotes eld -\end_inset - -new filename -\begin_inset Quotes erd -\end_inset - -); -\family default -) -\end_layout - -\begin_layout Standard -The saved file name is defined in -\family typewriter -$binary_grid::grid_options{'snapshot_file'} -\family default - (default -\family typewriter -'/tmp/binary_c-snapshot' -\family default -). -\end_layout - -\begin_layout Standard -All the above /tmp/ are actually -\family typewriter -$binary_grid::grid_options{tmp} -\family default - so you can define your own location for all the files (which is probably - more secure, because then you can prevent anyone from touching the file - and stopping your grid). -\end_layout - -\begin_layout Subsubsection -Restarting the grid -\end_layout - -\begin_layout Standard -If -\family typewriter -$binary_grid::grid_options{starting_snapshot_file} -\family default - is defined, it is used to load in a previously saved snapshot and the grid - is restarted. - You can usually just load this on the command line, e.g. - by running your grid script as -\end_layout - -\begin_layout Standard - -\family typewriter -./src/perl/scripts/my_grid_script.pl starting_snapshot_file=my_snapshot_file -\end_layout - -\begin_layout Subsection -World Domination -\end_layout - -\begin_layout Standard -\begin_inset CommandInset label -LatexCommand label -name "subsec:World Domination" - -\end_inset - - -\end_layout - -\begin_layout Standard -I'm working on it. -\end_layout - -\begin_layout Standard -\begin_inset Newpage pagebreak -\end_inset - - -\end_layout - -\begin_layout Section -FAQ -\end_layout - -\begin_layout Standard -\begin_inset CommandInset label -LatexCommand label -name "sec:FAQ" - -\end_inset - -Frequently asked questions. - -\end_layout - -\begin_layout Subsection -Why -\begin_inset space ~ -\end_inset - -not -\begin_inset space ~ -\end_inset - -Monte -\begin_inset space ~ -\end_inset - -Carlo? -\end_layout - -\begin_layout Standard -\begin_inset CommandInset label -LatexCommand label -name "FAQ:why not MC?" - -\end_inset - -The alternative to running a grid is a Monte Carlo method, where you throw - systems in according to some initial distribution and a random number generator. - In the high number limit this should give the -\emph on -same -\emph default - -\emph on -result -\emph default -as a grid. - However, in the low-number limit, the results are probably going to be - different, and this is when you test your code. - The big advantage of a grid is that you have a good handle on -\emph on -errors -\emph default - due to the finite resolution of your sampling of the initial distribution(s) - without the smearing out of a Monte Carlo approach. - Furthermore, MC may accidentally miss part of the initial parameter space - (it is, after all, random) which you know is covered by a grid approach - (at least to within a known error e.g. - -\begin_inset Formula $\delta\ln M_{1}$ -\end_inset - -). - You are also guaranteed, on a grid, to sample even the rare systems which - would be sparsely populated (if at all) in an MC simulation. - Such systems will have a small probability per star, -\begin_inset Formula $p_{i}$ -\end_inset - -, but on the other hand these might be the systems of particular interest - to you! -\end_layout - -\begin_layout Subsection -Why -\begin_inset space ~ -\end_inset - -MC -\begin_inset space ~ -\end_inset - -SN -\begin_inset space ~ -\end_inset - -kicks? -\end_layout - -\begin_layout Standard -\begin_inset CommandInset label -LatexCommand label -name "FAQ:WhyMCSNkicks?" - -\end_inset - -Traditionally supernova (and white dwarf) kicks have had their velocity - chosen in a Monte-Carlo way, rather than on a grid. - This was left as-is because there are four dimensions for each kick, which - – given a coarse grid of -\begin_inset Formula $10\times10\times10\times10$ -\end_inset - - – means the parameter space expands by a factor of -\begin_inset Formula $1,\,000$ -\end_inset - - for stars with kicks. - The runtime increase is not worth the effort as in order to finish anything - in your lifetime you would have to either buy a supercomputer or run such - a coarse grid in the original parameters that the whole exercise becomes - pointless. - The brute force resolution test is what you need here: just keep increasing - the resolution until the numbers converge. - It helps if you are clever about it: if you're interested in supernovae - only then -\begin_inset Formula $M_{1}$ -\end_inset - - is probably the dimension that requires the most resolution, or perhaps - -\begin_inset Formula $M_{2}$ -\end_inset - -, but probably not -\begin_inset Formula $a$ -\end_inset - -. -\end_layout - -\begin_layout Subsection -Zombie -\begin_inset space ~ -\end_inset - -binary_c -\begin_inset space ~ -\end_inset - -processes -\end_layout - -\begin_layout Standard -\begin_inset CommandInset label -LatexCommand label -name "FAQ:Zombie binary_c" - -\end_inset - - -\end_layout - -\begin_layout Standard -When the grid exits abnormally, or is killed, a -\emph on -binary_c/nucsyn -\emph default - process may be left behind in an infinite loop state and as such will take - up your precious CPU time. - You will have to kill it manually -\emph on -if you are sure it is not doing anything with another grid process! -\emph default -(Be careful and do -\emph on -not -\emph default - do -\begin_inset Quotes eld -\end_inset - -killall binary_c -\begin_inset Quotes erd -\end_inset - - as root\SpecialChar ldots -) -\end_layout - -\begin_layout Subsection -Zombie -\begin_inset space ~ -\end_inset - -Perl -\begin_inset space ~ -\end_inset - -processes -\end_layout - -\begin_layout Standard -\begin_inset CommandInset label -LatexCommand label -name "FAQ:Zombie perl" - -\end_inset - -These should die naturally when the grid finishes and the Perl script exits. - They are harmless and have never been seen to consume CPU time. -\end_layout - -\begin_layout Subsection -Setting -\begin_inset space ~ -\end_inset - -functions -\begin_inset space ~ -\end_inset - -and/or -\begin_inset space ~ -\end_inset - -function -\begin_inset space ~ -\end_inset - -pointers -\end_layout - -\begin_layout Standard -\begin_inset CommandInset label -LatexCommand label -name "FAQ:functions and pointers" - -\end_inset - -In the good old days you had to set up function pointers, e.g. - -\family typewriter - -\backslash -&parse_bse -\family default -, manually when setting up your grid. - However, in the latest version of -\emph on -flexigrid -\emph default -, this is set automatically (from -\family typewriter - -\backslash -&main::parse_bse -\family default -). - However, you can override the settings. - -\end_layout - -\begin_layout Standard -As an example, if you want to set the parse_bse_function_pointer, just set -\begin_inset Newline newline -\end_inset - - -\family typewriter - $binary_grid::grid_options{parse_bse_function}='my_parse_bse'; -\family default - -\begin_inset Newline newline -\end_inset - -where -\family typewriter -my_parse_bse -\family default - is your new function name. - This will automatically be converted into -\family typewriter - -\backslash -&main::my_parse_bse -\family default - at runtime. -\end_layout - -\begin_layout Standard -This process is applied to any -\family typewriter -grid_option -\family default - whose key ends in -\family typewriter -_function -\family default -. - These include -\family typewriter -thread_precreate_function -\family default -, -\family typewriter -threads_entry_function -\family default -, -\family typewriter -threads_flush_function -\family default -, -\family typewriter -thread_postrun_function -\family default -, -\family typewriter -thread_prejoin_function -\family default -, -\family typewriter -threads_join_function -\family default -, -\family typewriter -thread_postjoin_function -\family default -. - These are all -\family typewriter -undef -\family default - by default, so are ignored (unless you override them with function names), - except -\family typewriter -threads_join_function -\family default - which is set to -\family typewriter -binary_grid::join_flexigrid_thread -\family default - as usual. -\end_layout - -\begin_layout Standard -\begin_inset Newpage pagebreak -\end_inset - - -\end_layout - -\begin_layout Section -Installation -\end_layout - -\begin_layout Standard -\begin_inset CommandInset label -LatexCommand label -name "sec:installation" - -\end_inset - -Please see the binary_c-installation.pdf document for detailed installation - instructions. -\end_layout - -\begin_layout Standard -\begin_inset Newpage pagebreak -\end_inset - - -\end_layout - -\begin_layout Section -\start_of_appendix -Grid options ( -\emph on -grid_options -\emph default - hash) -\end_layout - -\begin_layout Standard -\begin_inset CommandInset label -LatexCommand label -name "sec:grid-options" - -\end_inset - -The following summarises the -\family typewriter -%grid_options -\family default - hash elements. - Please note that some options are (perhaps) no longer used and are left - in this manual as a reference guide only. - -\end_layout - -\begin_layout Description - -\family typewriter -alarm_procedure -\family default - When a signal is captured (usually on a timeout) the alarm_procedure tells - us what to do. - If -\begin_inset Formula $0$ -\end_inset - - then the grid exits. - If -\begin_inset Formula $1$ -\end_inset - - it tries to restart on the next star (although this may be buggy it is - the default!). - Really you should fix the problem if there is a timeout because it should - not happen. -\end_layout - -\begin_layout Description - -\family typewriter -always_reopen_arg_files -\family default - If 1 then argument log files are always reopened when new arguments are - sent to binary_c. - Can be very expensive in I/O operations, i.e. - slow. - -\end_layout - -\begin_layout Description - -\family typewriter -always -\begin_inset space ~ -\end_inset - -flush -\begin_inset space ~ -\end_inset - -binary_err -\family default - Set to 1 (default) to force the flushing of the -\family typewriter -stderr -\family default - channel out of -\emph on -binary_c -\emph default -. - If you don't do this, stderr output will pile up and eventually stop the - grid from functioning. - Do not change it unless you -\emph on -know -\emph default - there will be no -\family typewriter -stderr -\family default - output from -\emph on -binary_c -\emph default -. -\end_layout - -\begin_layout Description - -\family typewriter -arg_checking -\family default - Sometimes, an argument to binary_c will not be recognised (e.g. - if you set something in a bse_option which is not compatible with your - binary_c, perhaps because you haven't enabled some feature in binary_c) - and the grid will give errors (and/or crash) which are rather cryptic. - Instead of this, you can set arg_checking to 1 to have strict checking - of each argument that is passed to binary_c. - This is, however, rather slow (because it requires a lot of I/O) so the - default is 0. - -\end_layout - -\begin_layout Description - -\family typewriter -args -\family default - Not technically an option, but is the string of arguments which is passed - to -\emph on -binary_c/nucsyn -\emph default -. - Useful for logging or debugging. -\end_layout - -\begin_layout Description - -\family typewriter -binary -\family default - The duplicity. - If binary is 1 then the grid runs binary stars, if 0 then single stars. -\end_layout - -\begin_layout Description - -\family typewriter -cache_binary_c_output -\family default - If this is 1 (the default) then output from binary_c is cached in a local - array before being processed through -\family typewriter -tbse_line() -\family default - calls. - This should be faster, because it means less switching from one process - to another, but its use means that -\emph on -binary_c -\emph default - is out of sync with -\family typewriter -tbse_line() -\family default -, so debugging is more difficult. -\end_layout - -\begin_layout Description - -\family typewriter -colour -\family default - If -\family typewriter -colour=1 -\family default - then verbose output (see -\family typewriter -vb -\family default -) is in colour, using the -\family typewriter -Term::ANSIColor -\family default - Perl module. - This is recommended. -\end_layout - -\begin_layout Description - -\family typewriter -disable_signal -\family default - You can disable a specific signal with this hash, e.g. - to disable -\family typewriter -INT -\family default - signals, set -\family typewriter -$binary_grid::grid_options{disable_signal}{INT}=1; -\end_layout - -\begin_layout Description - -\family typewriter -exit_on_eval_failure -\family default - When each star is run, it is inside a -\emph on -Perl -\emph default - -\family typewriter -eval -\family default - construct. - If there is an error (i.e. - -\family typewriter -$@ -\family default - is not undef) -\emph on -and -\emph default - -\family typewriter -exit_on_eval_failure -\family default - is defined then the grid is stopped. - Otherwise, the grid goes on in the hope that the error does not persist - (possibly dubious!). -\end_layout - -\begin_layout Description - -\family typewriter -force_local_hdd_use -\family default - Checks to see if the disks to which you are outputting data are local or - remotely mounted. - If the latter, binary_grid refuses to work. - You should (of course) always use local disks for your output – it is much - faster. - (Defaults to 1 on Unix systems.) -\end_layout - -\begin_layout Description - -\family typewriter -flexigrid -\family default - Hash used to set up the flexigrid, see Section -\begin_inset space ~ -\end_inset - - -\begin_inset CommandInset ref -LatexCommand ref -reference "sec:flexigrid" - -\end_inset - -. -\end_layout - -\begin_layout Description - -\family typewriter -grid_defaults_set -\family default - Logic control variable, set to 1 if grid_defaults has been called. -\end_layout - -\begin_layout Description - -\family typewriter -lastargs -\family default - Very similar to log_args but at a slightly different place in the code. - Should be avoided, use -\family typewriter -log_args -\family default - instead. -\end_layout - -\begin_layout Description - -\family typewriter -libpath -\family default - Path to libraries to be included in the calling of the -\emph on -binary_c/nucsyn -\emph default - executable. - This harks back to the days whens -\emph on -binary_c/nucsyn -\emph default - was built as a set of shared libraries. - These days it is built statically, so libpath is usually an empty string - (and hence is ignored). -\end_layout - -\begin_layout Description - -\family typewriter -log_args -\family default - If this is set to -\begin_inset Formula $1$ -\end_inset - - then the arguments passed to -\emph on -binary_c/nucsyn -\emph default - are saved in a file in -\family typewriter -/tmp/ -\family default - (usually -\family typewriter -/tmp/binary_c-args -\family default - or similar, with separate files for each thread). - This is very useful when the grid freezes as you can immediately see which - stellar system has caused the problem and then rerun it manually. - -\end_layout - -\begin_layout Description - -\family typewriter -maxq_per_thread -\family default - The maximum number of stars allowed to sit on the thread queue, per thread. - You do not want the thread queue to become indefinitely large because when - that happens the resources to store the queue (RAM) will become significant. - Default is 10. -\end_layout - -\begin_layout Description - -\family typewriter -newline -\family default - If -\family typewriter -vb=1 -\family default - then the value of this option is used as the end of line character. - You can use either -\family typewriter - -\begin_inset Quotes eld -\end_inset - - -\backslash -x0d -\begin_inset Quotes erd -\end_inset - - -\family default - (just a carriage return) or -\family typewriter - -\begin_inset Quotes eld -\end_inset - - -\backslash -n -\begin_inset Quotes erd -\end_inset - - -\family default - which is the carriage return with a line feed (the usual concept of -\begin_inset Quotes eld -\end_inset - -new line -\begin_inset Quotes erd -\end_inset - -). -\end_layout - -\begin_layout Description - -\family typewriter -nice -\family default - A string containing the nice command used to run -\shape italic -binary_c/nucsyn -\shape default -. - Usually no nice is used, so this is ' -\family typewriter -nice -n +0 -\family default -'. - You can leave this as it is and run ' -\family typewriter -nice grid.pl -\family default -' if you want the whole grid to be -\begin_inset Quotes eld -\end_inset - -niced -\begin_inset Quotes erd -\end_inset - -. -\end_layout - -\begin_layout Description - -\family typewriter -no_signals -\family default - Set to 1 to disable Perl signals. - Useful for working with Condor. -\end_layout - -\begin_layout Description - -\family typewriter -operating_system -\family default - Saves details of the current operating system (from -\emph on -rob_misc.pm -\emph default -) -\end_layout - -\begin_layout Description - -\family typewriter -parse_bse_function -\family default - Used to create the -\family typewriter -parse_bse_function_pointer -\family default -(see FAQ -\begin_inset space ~ -\end_inset - - -\begin_inset CommandInset ref -LatexCommand ref -reference "FAQ:functions and pointers" - -\end_inset - -). -\end_layout - -\begin_layout Description - -\family typewriter -parse_bse_function_pointer -\family default - In your grid script you need to define a subroutine (also known as a function) - to be used for data parsing. - Usually this is called -\family typewriter -parse_bse -\family default -(see FAQ -\begin_inset space ~ -\end_inset - - -\begin_inset CommandInset ref -LatexCommand ref -reference "FAQ:functions and pointers" - -\end_inset - -). -\end_layout - -\begin_layout Description - -\family typewriter -prog -\family default - The -\emph on -binary_c/nucsyn -\emph default - executable name, usually ' -\family typewriter -binary_c -\family default -'. - See also -\family typewriter -rootpath -\family default -. -\end_layout - -\begin_layout Description - -\family typewriter -progenitor -\family default - Not really a grid option, but stores the system information ( -\begin_inset Formula $M$ -\end_inset - - or -\begin_inset Formula $M_{1}$ -\end_inset - -, -\begin_inset Formula $M_{2}$ -\end_inset - -, -\begin_inset Formula $a$ -\end_inset - -, -\begin_inset Formula $P$ -\end_inset - -, -\begin_inset Formula $e$ -\end_inset - -, -\begin_inset Formula $p$ -\end_inset - - etc.) – useful for debugging or logging. -\end_layout - -\begin_layout Description - -\family typewriter -progenitor_hash -\family default - As progenitor but stores each item in a hash. - -\emph on - -\end_layout - -\begin_layout Description - -\family typewriter -repeat -\family default - The number of times -\family typewriter -\emph on -binary_c -\family default -\emph default - is called for each grid point, default is -\begin_inset Formula $1$ -\end_inset - -. - This is useful for increasing the resolution in situations where Monte-Carlo - methods are used such as the random supernova or white dwarf kicks. -\end_layout - -\begin_layout Description - -\family typewriter -rootpath -\family default - The directory in which the -\emph on -binary_c/nucsyn -\emph default - code source and executable reside. - See also -\family typewriter -prog -\family default - and -\family typewriter -srcpath -\family default -. -\end_layout - -\begin_layout Description - -\family typewriter -single_star_period -\family default - The orbital period (days) given to single stars (default -\begin_inset Formula $10^{50}\,\mathrm{d}$ -\end_inset - -). -\end_layout - -\begin_layout Description - -\family typewriter -starting_snapshot_file -\family default - Filename of a snapshot to be loaded before the grid is started. -\end_layout - -\begin_layout Description - -\family typewriter -snapshot_file -\family default - Filename used to save the status of the grid in a snapshot so it can be - restarted. - Defaults to -\family typewriter -/tmp/binary_c-snapshot -\family default - (where /tmp/ is set by the ' -\family typewriter -tmp -\family default -' grid option). - -\end_layout - -\begin_layout Description - -\family typewriter -srcpath -\family default - Location of the binary_c source files. - Usually this is just -\family typewriter -rootpath -\family default - with ' -\family typewriter -/src -\family default -' appended. - -\end_layout - -\begin_layout Description - -\family typewriter -suspend_files -\family default - An anonymous array (set with -\family typewriter -[...] -\family default -) containing filenames that should be watched. - If one exists, the grid is suspended to disk using the snapshotting mechanism - (see snapshot_file). -\end_layout - -\begin_layout Description - -\family typewriter -tmp -\family default - Location of temporary files. - Usually this is -\emph on -/tmp -\emph default - (on Unix/Linux) and certainly it should be a local disk. - If you have multiple users on one PC, they cannot -\emph on -all -\emph default - use -\emph on -/tmp -\emph default -. -\end_layout - -\begin_layout Description - -\family typewriter -thread_max_freeze_time_before_warning -\family default - The maximum time a thread loops its calls to -\family typewriter -tbse() -\family default - before a warning is issued (seconds, default 10). -\end_layout - -\begin_layout Description - -\family typewriter -thread_precreate_function -\family default - Used to create the -\family typewriter -thread_precreate_function_pointer -\family default -(see FAQ -\begin_inset space ~ -\end_inset - - -\begin_inset CommandInset ref -LatexCommand ref -reference "FAQ:functions and pointers" - -\end_inset - -). -\end_layout - -\begin_layout Description - -\family typewriter -thread_precreate_function_pointer -\family default - A pointer to a function to be called just before -\family typewriter -threads->create -\family default - is used to start a thread. - Ignored if -\family typewriter -undef -\family default -. -\end_layout - -\begin_layout Description - -\family typewriter -thread_prejoin_function -\family default - Used to create the -\family typewriter -thread_prejoin_function_pointer -\family default -(see FAQ -\begin_inset space ~ -\end_inset - - -\begin_inset CommandInset ref -LatexCommand ref -reference "FAQ:functions and pointers" - -\end_inset - -). -\end_layout - -\begin_layout Description - -\family typewriter -thread_prejoin_function_pointer -\family default - A pointer to a function called just before a thread is -\family typewriter -join -\family default -ed. - Ignored if -\family typewriter -undef -\family default -. -\end_layout - -\begin_layout Description - -\family typewriter -thread_presleep -\family default -A thread waits for this length of time (in seconds) before it starts in - order that all other threads have time to start before any output is logged - to the screen. - As such this is just to keep output pretty and should be small (default - 1 second). -\end_layout - -\begin_layout Description - -\family typewriter -thread_postjoin_function -\family default -Used to create the -\family typewriter -thread_postjoin_function_pointer -\family default -(see FAQ -\begin_inset space ~ -\end_inset - - -\begin_inset CommandInset ref -LatexCommand ref -reference "FAQ:functions and pointers" - -\end_inset - -). - Ignored if -\family typewriter -undef -\family default -. -\end_layout - -\begin_layout Description - -\family typewriter -thread_postjoin_function_pointer -\family default - A pointer to a function called just after a thread is -\family typewriter -join -\family default -ed. - Ignored if -\family typewriter -undef -\family default -. -\end_layout - -\begin_layout Description - -\family typewriter -thread_postrun_function -\family default - Used to create the -\family typewriter -thread_postrun_function_pointer -\family default -(see FAQ -\begin_inset space ~ -\end_inset - - -\begin_inset CommandInset ref -LatexCommand ref -reference "FAQ:functions and pointers" - -\end_inset - -). - Ignored if -\family typewriter -undef -\family default -. -\end_layout - -\begin_layout Description - -\family typewriter -thread_postrun_function_pointer -\family default - A pointer to a function to be called just after a -\family typewriter -thread->create -\family default - call (and just after -\family typewriter -$@ -\family default - is checked for a thread-creation error). - Ignored if -\family typewriter -undef -\family default -. -\end_layout - -\begin_layout Description - -\family typewriter -threads_entry_function -\family default - Used to create the -\family typewriter -threads_entry_function_pointer -\family default -(see FAQ -\begin_inset space ~ -\end_inset - - -\begin_inset CommandInset ref -LatexCommand ref -reference "FAQ:functions and pointers" - -\end_inset - -). - Ignored if -\family typewriter -undef -\family default -. -\end_layout - -\begin_layout Description - -\family typewriter -threads_entry_function_pointer -\family default - A pointer to a function called from inside a thread just before flexigrid() - is called. - Ignored if -\family typewriter -undef -\family default -. -\end_layout - -\begin_layout Description - -\family typewriter -threads_flush_function -\family default -Used to create the -\family typewriter -threads_flush_function_pointer -\family default -(see FAQ -\begin_inset space ~ -\end_inset - - -\begin_inset CommandInset ref -LatexCommand ref -reference "FAQ:functions and pointers" - -\end_inset - -). - Ignored if -\family typewriter -undef -\family default -. -\end_layout - -\begin_layout Description - -\family typewriter -threads_flush_function_pointer -\family default - A pointer to a function called from inside a thread just after flexigrid() - returns. - Ignored if -\family typewriter -undef -\family default -. -\end_layout - -\begin_layout Description - -\family typewriter -threads_join_function -\family default - Used to create the -\family typewriter -threads_join_function_pointer -\family default -(see FAQ -\begin_inset space ~ -\end_inset - - -\begin_inset CommandInset ref -LatexCommand ref -reference "FAQ:functions and pointers" - -\end_inset - -). - Ignored if -\family typewriter -undef -\family default -. -\end_layout - -\begin_layout Description - -\family typewriter -threads_join_function_pointer -\family default - When using a threaded grid you have to define a subroutine (also known - as a function) pointer which points to the function to be called after - each thread have finished. - This function is responsible for -\begin_inset Quotes eld -\end_inset - -joining -\begin_inset Quotes erd -\end_inset - - the threads, which means it collects the results from the thread and adds - them to the global results. - This is usually a function called -\family typewriter -join_thread -\family default - and is set with a line in grid-xxx.pl similar to: -\begin_inset Newline newline -\end_inset - - -\family typewriter -$binary_grid::grid_options{'threads_join_function_pointer'}= -\backslash -&join_thread; -\end_layout - -\begin_layout Description - -\family typewriter -threads_stack_size -\family default - The stack size (in MBytes) for each of the Perl threads. - Default is -\family typewriter -32 -\family default - (MBytes). -\end_layout - -\begin_layout Description - -\family typewriter -timeout -\family default - When possible the grid sets an alarm (a Linux/UNIX signal) which means - that warnings are given and perhaps the grid stopped after -\family typewriter -timeout -\family default - seconds. - Set to zero to ignore, usually 30 is enough. - This assumes your -\emph on - binary_c/nucsyn -\emph default - process takes less than -\family typewriter -timeout -\family default - seconds to run a system so if you have problems with this please check - your system to make sure you have the CPU time you need. -\end_layout - -\begin_layout Description - -\family typewriter -vb -\family default - Verbosity level. - With -\family typewriter -vb=1 -\family default - you get some output about the grid, i.e. - the number of stars run, the number to go, the current -\begin_inset Formula $M$ -\end_inset - -, or -\begin_inset Formula $M_{1}$ -\end_inset - -, -\begin_inset space ~ -\end_inset - - -\begin_inset Formula $M_{2}$ -\end_inset - - and -\begin_inset Formula $a$ -\end_inset - -, an estimate of the time taken, time remaining and the time at which the - grid is expected to finish. - You may also get information about memory usage (if available). - Make sure your terminal window is quite wide to accommodate the information! - If -\family typewriter -vb=2 -\family default - you will get additional information about each system. - This is very useful for determining which stellar system is causing the - code to freeze and/or crash. - See also -\family typewriter -nmod -\family default -, -\family typewriter -colour -\family default - and -\family typewriter -log_args -\family default -. - Some verbose logging is only switched on if -\family typewriter -vb=3 -\family default -, although this should be considered experimental. -\end_layout - -\begin_layout Description - -\family typewriter -weight -\family default - The probability is weighted by this value. - -\end_layout - -\begin_layout Standard -\begin_inset Newpage pagebreak -\end_inset - - -\end_layout - -\begin_layout Section -Binary_c/nucsyn options ( -\emph on -bse_options -\emph default - hash) -\end_layout - -\begin_layout Standard -\begin_inset CommandInset label -LatexCommand label -name "sec:bse-options" - -\end_inset - - The most important options are listed here, however you should consult - -\emph on -binary_c -\emph default - for the main options list because these options are (mostly) just passed - to -\emph on -binary_c -\emph default -. - The full list of options is given in -\family typewriter -src/setup/cmd_line_args.h -\family default -. - You can access a full list of arguments by running -\begin_inset Newline newline -\end_inset - - -\family typewriter -\series bold -binary_c --help -\family default -\series default - -\begin_inset Newline newline -\end_inset - - -\emph on -BSE -\emph default - refers to -\begin_inset CommandInset citation -LatexCommand citet -key "2002MNRAS_329_897H" -literal "true" - -\end_inset - -. -\end_layout - -\begin_layout Description -acc2 Bondi-Hoyle accretion rate parameter (default 1.5). - Deprecated in binary_c V2.0, please use Bondi_Hoyle_accretion_factor instead." -\end_layout - -\begin_layout Description -alpha_ce Common envelope ejection efficiency, default 1.0. -\end_layout - -\begin_layout Description -bb CRAP parameter, default 0. - Deprecated in binary_c V2.0, please use CRAP_parameter instead. -\end_layout - -\begin_layout Description -BH_prescription Black hole mass as a function of CO core mass prescription. - Default 0 ( -\emph on -BSE -\emph default -), can be 1 (Belczynski). -\end_layout - -\begin_layout Description -Bondi_Hoyle_accretion_factorBondi-Hoyle accretion rate parameter (default - 1.5). - -\end_layout - -\begin_layout Description -CRAP_parameter CRAP parameter, default 0. -\end_layout - -\begin_layout Description -delta_mcmin Shift in the core mass used to calculate the third dredge up - efficiency (default 0). -\end_layout - -\begin_layout Description -eddfac Eddington limit multiplier (default 1e6, i.e. - no Eddington limit). -\end_layout - -\begin_layout Description -extra A string which is appended to the arguments for -\emph on -binary_c -\emph default -. - You should not use this form if you can avoid it, but it might be useful - in some cases. - -\end_layout - -\begin_layout Description -lambda_ce Common envelope envelope binding energy parameter (default -1, - i.e. - set according to fitting functions). -\end_layout - -\begin_layout Description -lambda_ionisation Amount of recombination energy used to eject the common - envelope (default 0.0, only acts if lambda_ce (above) is -1). -\end_layout - -\begin_layout Description -lambda_min Minimum value of the third dredge up efficiency -\begin_inset space ~ -\end_inset - - -\begin_inset Formula $\lambda$ -\end_inset - - (default 0). -\end_layout - -\begin_layout Description -max_evolution_time Maximum time for stellar evolution, default -\begin_inset Formula $13.7\,\mathrm{Gyr}$ -\end_inset - -. -\end_layout - -\begin_layout Description -metallicity The metallicity (default -\begin_inset Formula $0.02$ -\end_inset - -). - -\end_layout - -\begin_layout Description -minimum_envelope_mass_for_third_dredgeup Minimum envelope mass for third - dredge up (default 0.5). -\end_layout - -\begin_layout Description -qcrit_GB_method Method for choosing -\begin_inset Formula $q_{\mathrm{\mathrm{crit}}}$ -\end_inset - - on the giant branch. -\end_layout - -\begin_layout Description -sn_sigma SN kick velocity dispersion. -\end_layout - -\begin_layout Description -superwind_mira_switchon Mira period at which the superwind switches on in - TPAGB stars, default is -\begin_inset Formula $500\,\mathrm{days}$ -\end_inset - - as in -\begin_inset CommandInset citation -LatexCommand citet -key "1993ApJ...413..641V" -literal "true" - -\end_inset - -. -\end_layout - -\begin_layout Description -tidal_strength_factor Modules the tidal timescale, default 1.0. -\end_layout - -\begin_layout Description -tpagbwind TPAGB wind prescription. - Default 0 is -\begin_inset CommandInset citation -LatexCommand citet -key "Parameterising_3DUP_Karakas_Lattanzio_Pols" -literal "true" - -\end_inset - -. -\end_layout - -\begin_layout Description -tpagb_reimers_eta -\begin_inset Formula $\eta$ -\end_inset - - for Reimers on the TPAGB. -\end_layout - -\begin_layout Description -vw_mira_shift Shifts the superwind Mira switchon (default 0.0). -\end_layout - -\begin_layout Description -vw_multipler Multiplier for the VW93 wind (default 0.0). -\end_layout - -\begin_layout Description -wr_wind Wolf-Rayet (massive star) wind prescription, default 0 is -\emph on -BSE -\emph default -. -\end_layout - -\begin_layout Description -wr_wind_fac Multiplier for WR winds, default 1.0. -\end_layout - -\begin_layout Description -z The metallicity (default -\begin_inset Formula $0.02$ -\end_inset - -). - Deprecated in -\emph on -binary_c V2.0 -\emph default - – please use -\begin_inset Quotes eld -\end_inset - -metallicity -\begin_inset Quotes erd -\end_inset - - instead. -\end_layout - -\begin_layout Standard -\begin_inset Newpage pagebreak -\end_inset - - -\end_layout - -\begin_layout Standard - -\size scriptsize -\begin_inset CommandInset bibtex -LatexCommand bibtex -bibfiles "references" -options "apalike" - -\end_inset - - -\end_layout - -\end_body -\end_document diff --git a/doc/deprecated/binary_grid-oldthreads.lyx b/doc/deprecated/binary_grid-oldthreads.lyx deleted file mode 100644 index a077fa1852c245a96e6bdb8c71c4e041a350ce7b..0000000000000000000000000000000000000000 --- a/doc/deprecated/binary_grid-oldthreads.lyx +++ /dev/null @@ -1,11427 +0,0 @@ -#LyX 2.0 created this file. For more info see http://www.lyx.org/ -\lyxformat 413 -\begin_document -\begin_header -\textclass scrartcl -\begin_preamble -\usepackage{eulervm} -% bibliography stuff -\def\aj{Astronomical Journal} % Astronomical Journal -\def\araa{ARA\&A} % Annual Review of Astron and Astrophys -\def\apj{Astrophysical Journal} % Astrophysical Journal -\def\apjl{Astrophysical Journal, Letters} % Astrophysical Journal, Letters -\def\apjs{Astrophysical Journal, Supplement} % Astrophysical Journal, Supplement -\def\apss{Ap\&SS} % Astrophysics and Space Science -\def\aap{Astronomy and Astrophysics} % Astronomy and Astrophysics -\def\aapr{A\&A~Rev.} % Astronomy and Astrophysics Reviews -\def\aaps{A\&AS} % Astronomy and Astrophysics, Supplement -\def\mnras{Monthly Notices of the Royal Astronomical Society} % Monthly Notices of the RAS -\def\pra{Phys.~Rev.~A} % Physical Review A: General Physics -\def\prl{Phys.~Rev.~Lett.} % Physical Review Letters -\def\pasa{PASA} % Publications of the ASP -\def\pasp{PASP} % Publications of the ASP -\def\pasj{PASJ} % Publications of the ASJ -\def\nat{Nature} % Nature -\def\aplett{Astrophys.~Lett.} % Astrophysics Letters -\def\physrep{Phys.~Rep.} % Physics Reports% - - -\usepackage{listings} -\end_preamble -\use_default_options true -\maintain_unincluded_children false -\language british -\language_package default -\inputencoding auto -\fontencoding global -\font_roman default -\font_sans helvet -\font_typewriter beramono -\font_default_family sfdefault -\use_non_tex_fonts false -\font_sc false -\font_osf false -\font_sf_scale 100 -\font_tt_scale 90 - -\graphics default -\default_output_format default -\output_sync 0 -\bibtex_command default -\index_command default -\paperfontsize default -\spacing single -\use_hyperref false -\papersize default -\use_geometry true -\use_amsmath 2 -\use_esint 1 -\use_mhchem 1 -\use_mathdots 1 -\cite_engine natbib_authoryear -\use_bibtopic false -\use_indices false -\paperorientation portrait -\suppress_date false -\use_refstyle 0 -\index Index -\shortcut idx -\color #008000 -\end_index -\leftmargin 2cm -\topmargin 3cm -\rightmargin 2cm -\bottommargin 3cm -\secnumdepth 3 -\tocdepth 3 -\paragraph_separation indent -\paragraph_indentation default -\quotes_language english -\papercolumns 1 -\papersides 1 -\paperpagestyle default -\tracking_changes false -\output_changes false -\html_math_output 0 -\html_css_as_file 0 -\html_be_strict false -\end_header - -\begin_body - -\begin_layout Title -Binary_grid -\end_layout - -\begin_layout Standard -Written by Robert Izzard, with greatly appreciated help from Fabian Schneider - and the other users of -\emph on -binary_grid -\emph default -. -\end_layout - -\begin_layout Section -Aims: what the grid does and why -\end_layout - -\begin_layout Standard -Binary population synthesis is a glorified form of accountancy, without - the huge pay but with of course much more fun! It involves modelling perhaps - millions of binary stars in a population to pick out those few that contribute - to the population of scientific interest. - The rate of formation, or number of these stars, or some other property - of them can then be examined in a -\emph on -quantitative -\emph default - and -\emph on -statistical -\emph default - manner. - This manual explains how the -\emph on -binary_grid -\emph default -module -- part of the -\emph on -binary_c/nucsyn -\emph default - code package -- can be used to model populations of single and binary stars. - -\end_layout - -\begin_layout Standard -For details about the binary stellar evolution code -\emph on -binary_c/nucsyn -\emph default - please see the nucsyn_manual document. - This guide is -\emph on -only -\emph default - concerned with the details of running grids of models, not about the details - of the models themselves. -\end_layout - -\begin_layout Subsection -Grid dimensions -\end_layout - -\begin_layout Standard -There are many parameters which can be set before running a stellar model. - The most important, for single stars, are the stellar mass -\begin_inset Formula $M$ -\end_inset - - and metallicity -\begin_inset Formula $Z$ -\end_inset - -. - It is common to set the metallicity -\begin_inset Formula $Z$ -\end_inset - - to be constant and vary the initial stellar mass -\begin_inset Formula $M$ -\end_inset - -. - In everything that follows I will assume you are working at a constant - metallicity -\begin_inset Formula $Z$ -\end_inset - -. - -\end_layout - -\begin_layout Standard -The situation is more complicated in binaries because instead of just -\begin_inset Formula $M$ -\end_inset - - there are two stellar masses -\begin_inset Formula $M_{1}$ -\end_inset - - and -\begin_inset Formula $M_{2}$ -\end_inset - -, the separation -\begin_inset Formula $a$ -\end_inset - - (or, equivalently, the period -\begin_inset Formula $P$ -\end_inset - -) and perhaps the eccentricity -\begin_inset Formula $e$ -\end_inset - -. - To run a population of binary stars then requires a grid of models in four - dimensions. - Often the eccentricity is ignored because close binaries -- which are the - ones in which you may be interested -- tend to circularise rapidly. - This reduces the problem to three dimensions. -\end_layout - -\begin_layout Standard -The number of stars on each side of the grid, i.e. - the -\emph on -resolution -\emph default - -\begin_inset Formula $n$ -\end_inset - -, roughly determines the total runtime of your simulation. - In single stars this is just -\begin_inset Formula $\Delta t\times n$ -\end_inset - -, where one model takes a time -\begin_inset Formula $\Delta t$ -\end_inset - - to run. - In the case of binaries on a three-dimensional grid, this increases to - -\begin_inset Formula $\Delta t\times n^{3}$ -\end_inset - - (see Fig. -\begin_inset space ~ -\end_inset - - -\begin_inset CommandInset ref -LatexCommand ref -reference "fig:grid-size" - -\end_inset - -). - In a typical population -\begin_inset Formula $n\sim100$ -\end_inset - - so the total runtime increases by a factor of -\begin_inset Formula $100^{2}=10^{4}$ -\end_inset - -. - This ignores the increase in -\begin_inset Formula $\Delta t$ -\end_inset - - for binaries which is unavoidable because there are two stars under considerati -on as well as smaller timesteps during mass transfer. - It is for this reason that the -\emph on -binary_c/nucsyn -\emph default - code (and its BSE ancestor) must be -- and is -- fast. - It can run a population of -\begin_inset Formula $10^{6}$ -\end_inset - - binaries in less than -\begin_inset Formula $24\,\mathrm{CPU\, hours}$ -\end_inset - -. - -\begin_inset Float figure -wide false -sideways false -status open - -\begin_layout Plain Layout -\begin_inset Graphics - filename binary_grid_images/m1_cuboid.ps - lyxscale 10 - scale 30 - rotateAngle 270 - -\end_inset - - -\begin_inset Graphics - filename binary_grid_images/m1_m2_a_cuboid.ps - lyxscale 10 - scale 30 - rotateAngle 270 - -\end_inset - - -\end_layout - -\begin_layout Plain Layout -\begin_inset Caption - -\begin_layout Plain Layout -\begin_inset CommandInset label -LatexCommand label -name "fig:grid-size" - -\end_inset - -The relative size of the single- and binary-star grids. - In single stars only one mass is required, -\begin_inset Formula $M_{1}$ -\end_inset - -, while in binaries the two masses -\begin_inset Formula $M_{1}$ -\end_inset - - and -\begin_inset Formula $M_{2}$ -\end_inset - - and separation are needed. - For a grid resolution of -\begin_inset Formula $n=100$ -\end_inset - -, the runtime for the single stars (left cuboid) is -\begin_inset Formula $100\times\Delta t$ -\end_inset - -, where -\begin_inset Formula $\Delta t$ -\end_inset - - is the runtime for one stellar system. - In binaries (right cuboid) this increases to at least -\begin_inset Formula $10^{6}\times\Delta t$ -\end_inset - - because of the extra grid dimensions. - In addition, -\begin_inset Formula $\Delta t$ -\end_inset - - will be longer for binaries because of the short timesteps required during - some phases of mass transfer, the fact that there are two stars to follow - in the evolution/nucleosynthesis algorithms and extra overhead from logging - and parsing output from both stars. - Typically, -\begin_inset Formula $\Delta t\sim0.1\,\mbox{s}$ -\end_inset - - on a -\begin_inset Formula $3\,\mbox{Ghz}$ -\end_inset - - PC. -\end_layout - -\end_inset - - -\end_layout - -\begin_layout Plain Layout - -\end_layout - -\end_inset - - -\end_layout - -\begin_layout Subsection -What to do with the grid -\end_layout - -\begin_layout Standard -What do we do once the grid of stars is set up? In most cases this involves - adding up some statistics related to each star on the grid. - There are two approaches which are commonly used, constant star formation - and a starburst. - The one that suits you depends on what you are trying to calculate and - to which observations you hope to compare. -\end_layout - -\begin_layout Subsubsection -Constant star formation rate -\end_layout - -\begin_layout Standard -In this case the formation rate or (perhaps -\begin_inset Formula $\delta t$ -\end_inset - --weighted) probabilities for each star corresponding to those in which you - are interested are simply added up. - This is why I say it is like accountancy! Because the rate of star formation - is assumed to be -\emph on -constant -\emph default - the evolution time of the stellar evolution is irrelevant. - A hybrid scheme can also be used, you might only consider stars older than - a given age (e.g. - for halo stars). -\end_layout - -\begin_layout Subsubsection -Starburst -\end_layout - -\begin_layout Standard -All stars form at time zero and you add up the (probably -\begin_inset Formula $\delta t$ -\end_inset - --weighted) number of stars in which you are interested which form or exist - in each time bin. - A good example is the delay-time distribution of type Ia supernovae. -\begin_inset Newline newline -\end_inset - - -\end_layout - -\begin_layout Standard -The statistic you wish to add up is usually output from -\emph on -binary_c/nucsyn. - -\emph default -Your -\begin_inset Quotes eld -\end_inset - -grid script -\begin_inset Quotes erd -\end_inset - - runs each star, takes the output of -\emph on -binary_c/nucsyn -\emph default - and adds up the statistic. - You can generate single numbers, histograms or arbitrarily complicated - statistical constructs for comparison with observations. - You can choose whether to do the calculations on the fly or save the progenitor - information for later data processing. -\end_layout - -\begin_layout Standard -The grid script can be used on multi-CPU machines and handles the administrative - issues regarding parallel processing. -\end_layout - -\begin_layout Standard -\begin_inset Newpage pagebreak -\end_inset - - -\end_layout - -\begin_layout Section -Grid setup (in theory) -\end_layout - -\begin_layout Standard -\begin_inset CommandInset label -LatexCommand label -name "sec:grid-setup-theory" - -\end_inset - -This section presents the -\emph on -theory -\emph default - behind the setup of a grid in -\begin_inset Formula $M$ -\end_inset - -, for single stars, or -\begin_inset Formula $M_{1}$ -\end_inset - -, -\begin_inset Formula $M_{2}$ -\end_inset - - and -\begin_inset Formula $a$ -\end_inset - - for binary stars. - In general a -\emph on -logarithmic -\emph default - spacing is chosen for the mass grid because the important relevant physical - processes are -\begin_inset Quotes eld -\end_inset - -more different -\begin_inset Quotes erd -\end_inset - - for the mass range -\begin_inset Formula $1-10\,\mathrm{M}_{\odot}$ -\end_inset - - than between -\begin_inset Formula $10-100\,\mathrm{M}_{\odot}$ -\end_inset - -. - This is rather subjective but you can chose the bounds of your grid to - reflect the stars in which your interest lies. -\end_layout - -\begin_layout Standard -Each star in the grid represents a -\emph on -phase volume -\emph default -. - This means that a star of mass -\begin_inset Formula $M$ -\end_inset - - represents stars which, in reality, have masses -\begin_inset Formula $M-\delta M/2$ -\end_inset - - to -\begin_inset Formula $M+\delta M/2$ -\end_inset - -, where -\begin_inset Formula $\delta M$ -\end_inset - - is the grid spacing. - In an ideal world -\begin_inset Formula $\delta M$ -\end_inset - - would be very small, so our simulations match reality as closely as possible. - However, this is not usually possible if the grid is to run in a reasonable - amount of time (before funding runs out). - The usual way around this is to 1) be clever and/or 2) use a brute-force - approach where the resolution is increased (in this case -\begin_inset Formula $\delta M$ -\end_inset - - decreased) until your -\begin_inset Quotes eld -\end_inset - -answer -\begin_inset Quotes erd -\end_inset - - converges. -\end_layout - -\begin_layout Standard -One concept which must be grasped is that the bounds of the -\emph on -grid -\emph default - are not necessarily the bounds of the -\emph on -initial distributions -\emph default - you will be using (e.g. - the initial mass function, IMF). - This is a critical point which can lead to confusion, it is best explained - with an example. - Say you wish to calculate the ratio of type II to type Ib/c supernovae. - You would do this by adding up the number of stars that explode as type - IIs and divide by the number of stars that explode as type Ib/cs. - You -\emph on -could -\emph default - do this with a grid from -\begin_inset Formula $0.1$ -\end_inset - - to -\begin_inset Formula $100\,\mathrm{M}_{\odot}$ -\end_inset - - and, given enough stars, you would come up with the correct answer. - This is easy for single stars, because -\begin_inset Formula $10^{4}$ -\end_inset - - single stars are easily run on a modern PC. - However, for binaries this is difficult, because even with only -\begin_inset Formula $100$ -\end_inset - - stars in the -\begin_inset Formula $M_{2}$ -\end_inset - - and -\begin_inset Formula $a$ -\end_inset - - dimensions, there would be -\begin_inset Formula $10^{8}$ -\end_inset - - stars in your simulation and the runtime would be huge. - You can, however, be smarter and reduce the grid bounds and resolution. - You know in advance that at solar metallicity ( -\begin_inset Formula $Z=0.02$ -\end_inset - -) type II and Ib/c supernovae occur in -\emph on -single stars -\emph default - with -\begin_inset Formula $M\gtrsim8\mathrm{M}_{\odot}$ -\end_inset - -. - If you choose -\begin_inset Formula $M_{1}$ -\end_inset - - to run between (say) -\begin_inset Formula $4$ -\end_inset - - and -\begin_inset Formula $100\,\mathrm{M}_{\odot}$ -\end_inset - - you know you will record the supernovae from mass transfer (as -\begin_inset Formula $M_{2}\le M_{1}$ -\end_inset - - so the minimum mass of merged stars is the required -\begin_inset Formula $8\,\mathrm{M}_{\odot}$ -\end_inset - -) as well as all the others at higher masses. - So, you will get the -\emph on -same answer -\emph default - from a grid between -\begin_inset Formula $4$ -\end_inset - - and -\begin_inset Formula $100\,\mathrm{M}_{\odot}$ -\end_inset - - as with a grid between -\begin_inset Formula $0.1$ -\end_inset - - and -\begin_inset Formula $100\,\mathrm{M}_{\odot}$ -\end_inset - -. - Note that the -\emph on -grid -\emph default - has changed, but the result has not. - This is because the initial distributions have fixed bounds independent - of the grid bounds. - See Section -\begin_inset space ~ -\end_inset - - -\begin_inset CommandInset ref -LatexCommand ref -reference "sec:initial-dists" - -\end_inset - - for more details on initial distributions. - -\end_layout - -\begin_layout Standard -This process requires some knowledge in advance, which you may not have. - In that case, run a low resolution grid, find suitable grid bounds and - then repeat at higher resolution until you are happy. - The downside to the process is that you may well miss small parts of the - parameter space which contain interesting systems. - In practice this is often a compromise worth making and, if in doubt, test - your model runs at low resolution but then crank the resolution to the - maximum you think is possible for the final model run. -\end_layout - -\begin_layout Standard -Another advantage of choosing the grid bounds is that sub-grids can be run - on different computers or CPU cores and the results combined. - This is discussed further in Section -\begin_inset space ~ -\end_inset - - -\begin_inset CommandInset ref -LatexCommand ref -reference "sec:threads" - -\end_inset - -. -\end_layout - -\begin_layout Subsection -Phase Volume -\end_layout - -\begin_layout Standard -\begin_inset CommandInset label -LatexCommand label -name "sub:phase-volume" - -\end_inset - -Given a chosen set of these distributions a logarithmic grid is set up in - one-dimensional -\begin_inset Formula $M$ -\end_inset - - space for single stars or 3D -\begin_inset Formula $M_{1}$ -\end_inset - --- -\begin_inset Formula $M_{2}$ -\end_inset - --- -\begin_inset Formula $a$ -\end_inset - - space for binary stars. - The grid is split into -\begin_inset Formula $n$ -\end_inset - - stars per dimension such that each star represents the centre of a logarithmic - grid-cell of size -\begin_inset Formula $\delta V$ -\end_inset - - where -\end_layout - -\begin_layout Standard -\begin_inset Formula -\begin{equation} -\delta V=\left\{ \begin{array}{cc} -\delta\ln M & \textrm{single stars}\\ -\delta\ln M_{1}\,\delta\ln M_{2}\,\delta\ln a & \textrm{binary stars} -\end{array}\right. -\end{equation} - -\end_inset - -and -\begin_inset Formula -\begin{equation} -\delta\ln x=\frac{\ln x_{\textrm{max}}-\ln x_{\textrm{min}}}{n}\,, -\end{equation} - -\end_inset - -where -\begin_inset Formula $x$ -\end_inset - - represents -\begin_inset Formula $M$ -\end_inset - -, -\begin_inset Formula $M_{1}$ -\end_inset - -, -\begin_inset Formula $M_{2}$ -\end_inset - - or -\begin_inset Formula $a$ -\end_inset - - and -\begin_inset Formula $x_{\textrm{max}}$ -\end_inset - - and -\begin_inset Formula $x_{\textrm{min}}$ -\end_inset - - are the grid limits. - The total number of stars is denoted by -\begin_inset Formula $N$ -\end_inset - - such that -\begin_inset Formula $N=n$ -\end_inset - - for single stars and -\begin_inset Formula $N=n^{3}$ -\end_inset - - for binary stars. -\end_layout - -\begin_layout Standard -The probability of existence of star -\begin_inset Formula $i$ -\end_inset - - is given by -\end_layout - -\begin_layout Standard -\begin_inset Formula -\begin{equation} -\delta p_{i}=\Psi\delta V_{i}=\Psi\delta V\,, -\end{equation} - -\end_inset - -because -\begin_inset Formula $\delta V$ -\end_inset - - is a constant. - The function -\begin_inset Formula $\Psi$ -\end_inset - - is discussed in Section -\begin_inset space ~ -\end_inset - - -\begin_inset CommandInset ref -LatexCommand ref -reference "sec:initial-dists" - -\end_inset - -. - -\end_layout - -\begin_layout Standard -The probability, -\begin_inset Formula $\delta p_{i}$ -\end_inset - -, is sometimes the quantity you wish to add up, although commonly you want - -\begin_inset Formula $\delta p_{\mathrm{i}}\times\delta t$ -\end_inset - - where -\begin_inset Formula $\delta t$ -\end_inset - - is the time spent in the phase of interest. - This is usually the case when comparing the number of stars which go through - a particular phase of evolution because the -\emph on -time -\emph default -in the phase of evolution is as important as the -\emph on -probability -\emph default - of the star existing in the first place. - -\emph on - -\emph default -However, for -\emph on -event rates -\emph default - (e.g. - supernovae) the time involved is zero, they are instantaneous events on - a stellar evolution timescale, so you have to sum up the -\begin_inset Formula $\delta p_{i}$ -\end_inset - -. - You have to be careful to calculate the appropriate statistics for comparison - with the observations. -\end_layout - -\begin_layout Subsection -Grid loops -\end_layout - -\begin_layout Standard -\begin_inset CommandInset label -LatexCommand label -name "sub:grid-loops" - -\end_inset - -In binary systems, the secondary mass -\begin_inset Formula $M_{2}$ -\end_inset - - typically depends on the primary mass -\begin_inset Formula $M_{2}$ -\end_inset - -, and the separation, -\begin_inset Formula $a$ -\end_inset - -, or period -\begin_inset Formula $P$ -\end_inset - -, may depend on both. - This means that usually the grid must be constructed in a series of nested - loops and statistics must be added in order as follows: -\end_layout - -\begin_layout Standard -\begin_inset Formula -\begin{equation} -{\displaystyle \sum}_{M_{1}=M_{\mathrm{1,min}}}^{M_{1,\mathrm{max}}}\left(\sum_{M_{2}=M_{2}}^{M_{2\mathrm{,max}}}\left\{ \sum_{a=a_{\mathrm{min}}}^{a_{\mathrm{max}}}\left[\dots\right]\right\} \right)\,.\label{eq:grid-loops} -\end{equation} - -\end_inset - -In the default grid, -\begin_inset Formula $M_{2}$ -\end_inset - - depends on -\begin_inset Formula $M_{1}$ -\end_inset - - through the -\begin_inset Formula $q=M_{2}/M_{1}$ -\end_inset - - distribution. - The default is a flat- -\begin_inset Formula $q$ -\end_inset - - distribution (see Section -\begin_inset space ~ -\end_inset - - -\begin_inset CommandInset ref -LatexCommand ref -reference "sec:initial-dists" - -\end_inset - -), with which stars only exist if -\begin_inset Formula $0.1\,\mathrm{M}_{\odot}\leq M_{2}\leq M_{1}$ -\end_inset - -. - As such it generally makes sense to have -\begin_inset Formula $M_{2,\mathrm{min}}=0.1\,\mathrm{M}_{\odot}$ -\end_inset - - and -\begin_inset Formula $M_{2,\mathrm{max}}=M_{1}$ -\end_inset - - because secondary stars with mass greater than the primary do not exist - (by definition of the secondary and primary). -\end_layout - -\begin_layout Standard -The default separation distribution does not depend on the masses, but it - may if the -\family typewriter -adapt_sepdist -\family default - option is used (see Section -\begin_inset space ~ -\end_inset - - -\begin_inset CommandInset ref -LatexCommand ref -reference "sec:grid-options" - -\end_inset - -). -\end_layout - -\begin_layout Subsection -Resolution -\end_layout - -\begin_layout Standard -\begin_inset CommandInset label -LatexCommand label -name "sub:resolution" - -\end_inset - -The choice of grid resolution depends very much on the problem you wish - to address and what you are trying to calculate. - As a general rule, assuming you are modelling stars from -\begin_inset Formula $M_{\mathrm{min}}=0.1\,\mathrm{M}_{\odot}$ -\end_inset - - to -\begin_inset Formula $M_{\mathrm{max}}=100\,\mathrm{M}_{\odot}$ -\end_inset - - you probably want at least -\begin_inset Formula $100$ -\end_inset - - stars in the -\begin_inset Formula $M$ -\end_inset - - (or -\begin_inset Formula $M_{1}$ -\end_inset - -) dimension. - -\end_layout - -\begin_layout Standard -However, before rushing off to run millions of stars, run some low-resolution - test models and gradually increase the number of stars. - The best way to determine the required resolution is simply the brute force - method: keep increasing the resolution until your answers converge. -\end_layout - -\begin_layout Standard -You can roughly estimate the -\emph on -statistical -\emph default -error by counting the number of stars that satisfy your criterion (say -\begin_inset Formula $k$ -\end_inset - - stars) and then use Poisson statistics (i.e. - the error on a value -\begin_inset Formula $x$ -\end_inset - - is -\begin_inset Formula $x/\sqrt{k}$ -\end_inset - -). - -\series bold -Be warned that this is -\emph on -not -\emph default - the error due to the use of a grid. - -\series default - If your data calculation binning is -\emph on -over -\emph default --resolved you may see problems with artifacts and aliasing. - These may or may not affect your results. - If in doubt, increase the resolution until the problem goes away (if it - goes away!). - In some cases this may not be possible because your computer is not fast - enough. - You could always buy a time machine\SpecialChar \ldots{} - but then you wouldn't be doing astrophysics -! -\end_layout - -\begin_layout Standard -Sometimes you can choose a better mass grid than the default -\begin_inset Formula $\ln M$ -\end_inset - - grid to obtain better resolution where required for the same number of - stars, as described in the next section. -\end_layout - -\begin_layout Subsection -Alternative grid spacing -\end_layout - -\begin_layout Standard -\begin_inset CommandInset label -LatexCommand label -name "sub:alternative-grid-spacing" - -\end_inset - -Some problems require a more carefully spaced grid than the simple -\begin_inset Formula $\ln M$ -\end_inset - - grid. - A good example is the calculation of stellar yields. - The yield sets are generally required to give yields out to a time of many - -\begin_inset Formula $\mathrm{Gyr}$ -\end_inset - - and with a time resolution of, say, -\begin_inset Formula $10\,\mathrm{Myr}$ -\end_inset - -. - At early times this is not a problem, but at late times the stellar lifetime - scales with the mass as -\begin_inset Formula $t\sim M^{3}$ -\end_inset - - (roughly) so in order to have good time resolution we require -\begin_inset Formula $\delta M\sim\delta t/(3M^{2})\sim t^{-2/3}\delta t$ -\end_inset - - which is rather small at late times when -\begin_inset Formula $t$ -\end_inset - - is large. - -\end_layout - -\begin_layout Standard -An alternative is to set up the grid to -\emph on -enforce -\emph default - -\begin_inset Formula $\delta M=f\times\delta t/(3M^{2})$ -\end_inset - - as our grid spacing (with a factor -\begin_inset Formula $f<1$ -\end_inset - - which ensures over-resolution to avoid gridding artifacts). - Implementations of this, and a fixed -\begin_inset Formula $\delta\ln t$ -\end_inset - - grid, are available in -\emph on -binary_grid -\emph default -. - -\end_layout - -\begin_layout Standard -\begin_inset Newpage pagebreak -\end_inset - - -\end_layout - -\begin_layout Section -Grid setup (in practice) -\end_layout - -\begin_layout Standard -\begin_inset CommandInset label -LatexCommand label -name "sec:grid-setup-practice" - -\end_inset - -This section describes a typical grid setup with the default grid options. - Alternative grid setups are discussed in Section -\begin_inset space ~ -\end_inset - - -\begin_inset CommandInset ref -LatexCommand ref -reference "sec:grid-options" - -\end_inset - - which lists the grid options in detail. -\end_layout - -\begin_layout Standard -The grid is set up by use of a Perl module called -\emph on -binary_grid -\emph default -. - This is usually installed with -\emph on -binary_c/nucsyn -\emph default - (see the -\emph on -binary_c/nucsyn -\emph default - manual). - In any case, you need it! You will also need the -\emph on -IMF -\emph default - perl module (to calculate initial stellar distribution functions, see Section -\begin_inset space ~ -\end_inset - - -\begin_inset CommandInset ref -LatexCommand ref -reference "sec:initial-dists" - -\end_inset - -) and -\emph on -rob_misc -\emph default - (Rob's miscellaneous function library). -\end_layout - -\begin_layout Standard -You should copy the grid.pl script provided with -\emph on -binary_c/nucsyn -\emph default - and work on your -\emph on -copy -\emph default -. - The -\emph on -grid.pl -\emph default - script is a template for a minimal grid setup -- you will need to change - it to reflect whatever you output from the -\emph on -binary_c/nucsyn -\emph default - code. - It will be referred to as -\begin_inset Quotes eld -\end_inset - -your grid script -\begin_inset Quotes erd -\end_inset - - in what follows. -\end_layout - -\begin_layout Subsection -The Perl Module -\end_layout - -\begin_layout Standard -The -\emph on -binary_grid -\emph default - Perl module contains (almost) all the code to set up, manage and run the - grid, as well as the interface to the -\emph on -binary_c/nucsyn -\emph default -. - This should be (almost) completely transparent to you, the user, and the - process is as automated as possible. - -\end_layout - -\begin_layout Subsubsection -Variables -\end_layout - -\begin_layout Standard -There are many global variables (sorry) but let's face it, this is written - in Perl, not C, so it doesn't matter. - You should not access most of them, except for the two hashes: -\end_layout - -\begin_layout Description - -\family typewriter -%bse_options -\family default - are those that are passed to the -\emph on -binary_c/nucsyn -\emph default - code and are discussed in detail in the -\emph on -binary_c/nucsyn -\emph default - manual. - They usually affect the -\emph on -physics -\emph default - being implemented in the simulation. -\end_layout - -\begin_layout Description - -\family typewriter -%grid_options -\family default - are variables which control details of the -\emph on -grid -\emph default - and the processing of the output. -\end_layout - -\begin_layout Standard -To access the variables in your grid script, you should use something like - the following: -\begin_inset Newline newline -\end_inset - - -\end_layout - -\begin_layout Standard - -\family typewriter -$binary_grid::bse_options{'max_evolution_time'}=10.0; -\end_layout - -\begin_layout Standard - -\family typewriter -$binary_grid::grid_options{'imf1'}='ktg93'; -\begin_inset Newline newline -\end_inset - - -\end_layout - -\begin_layout Standard -The -\family typewriter -$binary_grid:: -\family default - tells Perl that you want to change the hash in the -\family typewriter -binary_grid -\family default - module rather than a local variable with the same name which may exist - in your grid script. -\end_layout - -\begin_layout Subsubsection -Important Subroutines -\end_layout - -\begin_layout Standard -The most important subroutines involved in setting up the grid, some of - which you have to call from your grid script (see Section -\begin_inset space ~ -\end_inset - - -\begin_inset CommandInset ref -LatexCommand ref -reference "sec:grid.pl" - -\end_inset - -) are the following: -\end_layout - -\begin_layout Description - -\family typewriter -grid_defaults -\family default - This sets up the default values for the two main hashes of options: -\family typewriter -%grid_options -\family default - and -\family typewriter -%bse_options -\family default -. - Note that in the case where a -\family typewriter -bse_option -\family default - is -\emph on -not -\emph default - given default, you may still set it in your grid script, but if it is -\emph on -not -\emph default - set the default -\emph on -binary_c/nucsyn -\emph default - value is used. -\end_layout - -\begin_layout Description - -\family typewriter -parse_grid_args -\family default - Arguments given on the command line in the form -\emph on -x -\family typewriter -\emph default -= -\family default -\emph on -y -\emph default - are parsed in turn. - If -\emph on -x -\emph default - matches any of the keys of the -\family typewriter -%grid_options -\family default - or -\family typewriter -%bse_options hashes -\family default -, the value of the hash item is set to that given by -\emph on -y -\emph default -. - If the key is not matched it is ignored. - A good example of the use of this function is the use of -\family typewriter -vb=1 -\family default - to turn on verbose log output from the grid. - This verbose output is often very useful as it gives you an estimate of - the fraction of the grid that is complete, the time remaining and the estimated - time at which the grid will finish. -\end_layout - -\begin_layout Description - -\family typewriter -setup_binary_grid -\family default - This should be called just before running your grid. - It initialises the initial distributions, sets up the timeout feature, - opens some log files etc. -\end_layout - -\begin_layout Description - -\family typewriter -test_grid -\family default - This was originally used to run the grid without running -\emph on -binary_c/nucsyn -\emph default -. - There are uses for this, such as calculating the mass that goes into stars - for a given initial distribution, but you probably do not need it. -\end_layout - -\begin_layout Description - -\family typewriter -grid -\family default - This runs the old-fashioned, single-thread grid. -\end_layout - -\begin_layout Description - -\family typewriter -threaded_grid -\family default - This is the threaded version of the -\family typewriter -grid() -\family default - subroutine (see Section -\begin_inset space ~ -\end_inset - - -\begin_inset CommandInset ref -LatexCommand ref -reference "sec:threads" - -\end_inset - -). - It runs the grid, by splitting it into chunks and allocating each chunk - to a different processor/core. - Note that this should -\emph on -no longer be used. -\end_layout - -\begin_layout Description - -\family typewriter -flexigrid -\family default - This runs the latest version of the grid with perfect load balancing and - code built on the fly. - If you are running a grid of stars for the first time, you should use this. -\end_layout - -\begin_layout Description - -\family typewriter -tbse_line -\family default - This is called to retrieve data from calls to -\emph on -binary_c/nucsyn -\emph default -: see Section -\begin_inset space ~ -\end_inset - - -\begin_inset CommandInset ref -LatexCommand ref -reference "sec:data-parsing" - -\end_inset - -. -\end_layout - -\begin_layout Subsection -Less important subroutines -\end_layout - -\begin_layout Standard -If you really care about the structure of the -\family typewriter -binary_grid module -\family default -, rather than how to use it, you have come to the right place. - Almost everything in -\family typewriter -binary_grid -\family default - not mentioned above is dedicated to the running and management of the grid - loops (see Eq. -\begin_inset space ~ -\end_inset - - -\begin_inset CommandInset ref -LatexCommand ref -reference "eq:grid-loops" - -\end_inset - -). -\end_layout - -\begin_layout Standard -The grid subroutine does a number of things in turn, of which the most important - are listed below: -\end_layout - -\begin_layout Enumerate -The -\family typewriter -%masshash -\family default - is set up. - The -\family typewriter -%masshash -\family default - contains as its keys the (single- or binary-star) masses -\begin_inset Formula $M$ -\end_inset - - (or -\begin_inset Formula $M_{1}$ -\end_inset - -) and as values the width in -\emph on -log mass space -\begin_inset Formula $\delta\ln M$ -\end_inset - - -\emph default -(or -\begin_inset Formula $\delta\ln M_{1}$ -\end_inset - -) -\emph on -. - -\emph default - This is done with the -\family typewriter -setup_masshash -\family default - subroutine. - This also creates a numerically sorted list of masses in the hash, stored - in -\family typewriter -@mlist -\family default -. -\end_layout - -\begin_layout Enumerate -The -\family typewriter -tbse_launch -\family default - subroutine is called to start -\emph on -binary_c/nucsyn -\emph default -. -\end_layout - -\begin_layout Enumerate -A loop is made over the -\family typewriter -@mlist -\family default - masses. - Note that the loop is -\emph on -not necessarily -\emph default - over the whole list! In a threaded grid only a part of the list is looped - over -- if threads are not being used, the whole list is looped. - -\end_layout - -\begin_layout Enumerate -If -\family typewriter -$binary_grid::grid_options{'binary'} -\family default - is -\emph on -zero -\emph default -(i.e. - we want single stars only) then a loop over the masses is performed. - For each mass: -\end_layout - -\begin_deeper -\begin_layout Enumerate -The -\family typewriter -$binary_grid::progenitor -\family default - variables are set (see Section -\begin_inset space ~ -\end_inset - - -\begin_inset CommandInset ref -LatexCommand ref -reference "sec:debugging" - -\end_inset - -). - These save the values of the masses, period, separation and eccentricity - for each star and so are useful for debugging/logging. -\end_layout - -\begin_layout Enumerate -The probability of existence of the star is calculated with -\family typewriter -calc_prob -\family default - (from the IMF Perl module) -\end_layout - -\begin_layout Enumerate -The -\family typewriter -tbse() -\family default - subroutine is called for each mass. -\end_layout - -\end_deeper -\begin_layout Enumerate -If -\family typewriter -$binary_grid::grid_options{'binary'} -\family default - is -\emph on -one -\emph default -(i.e. - we want binary stars) the list of masses is looped over as in single stars - but things are then done a little differently: -\end_layout - -\begin_deeper -\begin_layout Enumerate -For each primary mass -\begin_inset Formula $M_{1}$ -\end_inset - - a call is made to the -\family typewriter -populate_m2list -\family default - subroutine. - This makes a list of secondary star masses -\begin_inset Formula $M_{2}$ -\end_inset - - which is looped over. -\end_layout - -\begin_layout Enumerate -For each -\begin_inset Formula $M_{2}$ -\end_inset - - the third loop is called. - This is usually call to the -\family typewriter -separation_loop -\family default - subroutine, but if you are using an initial distribution which is based - on the orbital period rather than the separation then -\family typewriter -period_loop -\family default - is called. -\end_layout - -\begin_layout Enumerate -The separation (or period) loop then sets -\family typewriter -$binary_grid::progenitor -\family default -, calculates the probability with -\family typewriter -calc_prob -\family default - and calls -\family typewriter -tbse() -\family default - for each combination of -\begin_inset Formula $M_{1}$ -\end_inset - -, -\begin_inset Formula $M_{2}$ -\end_inset - - and -\begin_inset Formula $a$ -\end_inset - - (or -\begin_inset Formula $P$ -\end_inset - -). -\end_layout - -\end_deeper -\begin_layout Enumerate -The -\family typewriter -tbse_land() -\family default - subroutine is called to stop -\emph on -binary_c/nucsyn -\emph default -. -\end_layout - -\begin_layout Standard -There are numerous other subroutines in binary_grid, some of which are not - really used anymore and many shouldn't -- in an ideal world -- be there. - However, you should not remove them because backward compatibility is vital - to some old codes (and perhaps the GCE code). -\end_layout - -\begin_layout Standard -\begin_inset Newpage pagebreak -\end_inset - - -\end_layout - -\begin_layout Section -Data parsing (Accountancy without the salary) -\end_layout - -\begin_layout Standard -\begin_inset CommandInset label -LatexCommand label -name "sec:data-parsing" - -\end_inset - -The previous sections describe how to set up a grid. - Before you actually run your own grid you have to think about what you - want to discover from your stellar models. - A few standard cases are outlined here. - You may, of course, want a combination of all these methods. -\end_layout - -\begin_layout Standard -This section describes the theory, the practical aspects of combining -\emph on -binary_c/nucsyn -\emph default - with your grid script are described in Section -\begin_inset space ~ -\end_inset - - -\begin_inset CommandInset ref -LatexCommand ref -reference "sec:grid.pl" - -\end_inset - -. -\end_layout - -\begin_layout Subsection -Rates of things -\end_layout - -\begin_layout Standard -\begin_inset CommandInset label -LatexCommand label -name "sub:rates-of-things" - -\end_inset - -The simplest thing to calculate is the rate of formation of some type of - star, or alternatively the rate of stellar death (e.g. - the supernova rate), merger rate, etc. - These are -\emph on -events -\emph default -which have no duration so the important thing to log is the -\emph on -time at which the event happened -\emph default -, -\emph on - -\begin_inset Formula $t_{i}$ -\end_inset - - -\emph default -, and -\emph on -the probability of existence of the stellar system, -\emph default - -\begin_inset Formula $p_{i}$ -\end_inset - -. -\end_layout - -\begin_layout Standard -You will probably want to count the number of systems that explode in a - given time bin, i.e. - between time -\begin_inset Formula $t$ -\end_inset - - and -\begin_inset Formula $t+\Delta t$ -\end_inset - -, where -\begin_inset Formula $\Delta t$ -\end_inset - - is the time bin width ( -\emph on -not -\emph default - the -\emph on -binary_c/nucsyn -\emph default - timestep!). - The formation rate is the product of the star formation rate -\begin_inset Formula $S$ -\end_inset - - and the summed probability of the stars that do whatever it is that is - interesting in time -\begin_inset Formula $t$ -\end_inset - - to -\begin_inset Formula $t+\Delta t$ -\end_inset - -, -\begin_inset Formula $\sum p_{i}$ -\end_inset - -. - You have to somehow calculate -\begin_inset Formula $S$ -\end_inset - - (see e.g. - -\begin_inset CommandInset citation -LatexCommand citealp -key "2002MNRAS_329_897H" - -\end_inset - - for a simple prescription). - You would be better comparing the relative rates of two types of event, - in which case -\begin_inset Formula $S$ -\end_inset - - (and its associated uncertainty) cancels. -\end_layout - -\begin_layout Standard -This is all correct for a starburst at time -\begin_inset Formula $t=0$ -\end_inset - -. - If you want to use a more realistic star formation history you have to - convolve the results of many starbursts. - You can do this manually (and it is easy if, say, the metallicity and other - physics is not a function of -\begin_inset Formula $t$ -\end_inset - -) or use a pre-existing code such as Rob's Galactic Chemical Evolution (GCE) - code. - The latter has the advantage that it already exists and is well tested. - You will, however, have to ask Rob about it because it is not (yet) a part - of the standard -\emph on -binary_c/nucsyn -\emph default - distribution. - -\end_layout - -\begin_layout Subsection -Numbers of things -\end_layout - -\begin_layout Standard -\begin_inset CommandInset label -LatexCommand label -name "sub:numbers-of-things" - -\end_inset - - -\end_layout - -\begin_layout Standard -Alternatively, perhaps you wish to calculate the number of stars of a certain - type e.g. - the number of carbon stars or the number of K-type stars. - In this case you have to count both the probability of the existence of - the star -\begin_inset Formula $p_{i}$ -\end_inset - - and the time the star spends in the evolutionary phase of interest. - If we assume -\begin_inset Formula $S=1$ -\end_inset - - (i.e. - constant star formation) you should then count -\begin_inset Formula $\sum p_{i}\,\delta t\,\bar{\delta}$ -\end_inset - - where -\begin_inset Formula $\bar{\delta}=1$ -\end_inset - - if the star is interesting to you, but zero otherwise. -\end_layout - -\begin_layout Standard -As in the previous example, if -\begin_inset Formula $S$ -\end_inset - - is not simply a constant things get tricky. - But usually a constant star formation rate is -\begin_inset Quotes eld -\end_inset - -good enough -\begin_inset Quotes erd -\end_inset - - for e.g. - Galactic stellar population studies of anything but the youngest stars. - In other cases a starburst is more appropriate and you will have to factor - in a check on the time -\begin_inset Formula $t$ -\end_inset - - into -\begin_inset Formula $\bar{\delta}$ -\end_inset - - to match the present-day age of the population. - -\end_layout - -\begin_layout Subsection -GCE and the ensemble -\end_layout - -\begin_layout Standard -\begin_inset CommandInset label -LatexCommand label -name "sub:gce" - -\end_inset - -As already mentioned, Rob has written a Galactic Chemical Evolution code - to do much of the work described above for you. - In addition to (sort of!) self-consistently calculating the nucleosynthesis - and hence metallicity evolution in a Galaxy for arbitrary star formation, - gas infall and outflow rates, you can enable the -\begin_inset Quotes eld -\end_inset - -stellar ensemble -\begin_inset Quotes erd -\end_inset - - in -\emph on -binary_c/nucsyn -\emph default -. - This simply enables a large piece of logging code to output e.g. - stellar types, spectral types, explosion counts, etc. - Rob's GCE code is designed to follow these and do the convolution for you. - It runs in two modes. - The first is to use saved starburst data from previous grid runs. - This is fast but not entirely self-consistent (although often it is good - enough). - The second technique is to run the binary grids at each timestep of the - GCE code. - This is better, in that the metallicity is more self-consistent, but can - be very slow because the GCE code runtime is limited by the time it takes - to run an entire binary grid (which is usually hours). - In future it is hoped that the GCE code will be run on a cluster of machines - with sufficient CPU power to reduce the overhead of running a binary grid. - This will require some effort to reliably automate the process. -\end_layout - -\begin_layout Standard -\begin_inset Newpage pagebreak -\end_inset - - -\end_layout - -\begin_layout Section -Your grid-xxx.pl script -\end_layout - -\begin_layout Standard -\begin_inset CommandInset label -LatexCommand label -name "sec:grid.pl" - -\end_inset - -Before you start: you should copy the -\family typewriter -grid.pl -\family default - script in the -\family typewriter -binary_c -\family default - directory to a script of your own naming (usually grid- -\emph on -xxx -\emph default -.pl where you choose a suitable label to replace -\emph on -xxx -\emph default -). - Work on your copy, not the original! -\end_layout - -\begin_layout Subsection -Logging in -\emph on -binary_c -\end_layout - -\begin_layout Standard -When -\emph on -binary_c -\emph default - is run for one star with the -\family typewriter -tbse -\family default - script the output is dumped to the screen (known in -\emph on -UNIX -\emph default - as -\family typewriter -stdout -\family default -). - A standard build of -\emph on -binary_c -\emph default - outputs very little information because it does not know what you wish - to know. - Every line that is output is expensive in terms of CPU time, and CPU time - is critical when running millions of stars. - This means you have to think carefully about what you will output from - -\emph on -binary_c -\emph default - and when. - Too much information slows things down, too little is useless -- you have - to decide. -\end_layout - -\begin_layout Standard -You will probably want to output one line of information per -\emph on - binary_c -\emph default -timestep. - This should be done in the -\family typewriter -iteration_logging -\family default - subroutine which is called every timestep. - Your logging code should look something like: -\end_layout - -\begin_layout Standard - -\family typewriter -printf( -\begin_inset Quotes eld -\end_inset - -MYLOG %g %g %g %i -\backslash -n -\begin_inset Quotes erd -\end_inset - -, -\end_layout - -\begin_layout Standard - -\family typewriter -stardata->model.model_time, -\end_layout - -\begin_layout Standard - -\family typewriter -stardata->model.probability, -\end_layout - -\begin_layout Standard - -\family typewriter -stardata->model.dt, -\end_layout - -\begin_layout Standard - -\family typewriter -stardata->star[1].mass, -\end_layout - -\begin_layout Standard - -\family typewriter -stardata->star[1].stellar_type); -\end_layout - -\begin_layout Standard -The string -\family typewriter -MYLOG -\family default - is critical: this is what will be recognised and used by the grid. - You should have a think (and consult Section -\begin_inset space ~ -\end_inset - - -\begin_inset CommandInset ref -LatexCommand ref -reference "sec:data-parsing" - -\end_inset - -) to determine whether you want to output either the probability ( -\family typewriter -stardata-> model.probability -\family default -) or both the probability and timestep ( -\family typewriter -stardata->model.dt -\family default -). -\end_layout - -\begin_layout Subsection -Coupling your -\emph on -binary_c/nucsyn -\emph default - and your grid -\end_layout - -\begin_layout Standard -Now you know how to make lines of logging information come out of the -\emph on -binary_c -\emph default - program. - It remains to couple this to the grid. - This is done through the -\family typewriter -tbse_line -\family default - subroutine in the -\family typewriter -parse_bse -\family default - function (see the example -\family typewriter -grid.pl -\family default -). - Each time -\family typewriter -tbse_line -\family default - is called it gets a line of output from -\emph on -binary_c -\emph default - and loads returns it (usually to -\family typewriter -$_ -\family default - the Perl default variable). - It is then up to you to decide what to with the data from -\family typewriter -tbse_line -\family default -. - -\end_layout - -\begin_layout Standard -There may be many lines of data pumped into -\family typewriter -tbse_line -\family default -, so you have to choose those labelled with your header string -- in the - above example this is -\family typewriter -MYLOG -\family default -. - This is best done with a Perl substitution-regular expression: the regular - expression matches -\family typewriter -MYLOG -\family default -, the substitution removes it (because it is not data). - In the following example note that the check for ' -\family typewriter -fin -\family default -' -\emph on -must -\emph default - be there. - -\emph on -binary_c -\emph default - returns a ' -\family typewriter -fin -\family default -' when the star has finished its evolution. - Without this it would be stuck in an infinite loop, so avoid removing the - -\family typewriter -$brk -\family default - stuff. - -\begin_inset Newline newline -\end_inset - - -\end_layout - -\begin_layout Standard - -\family typewriter -while($brk==0) -\end_layout - -\begin_layout Standard - -\family typewriter -{ -\end_layout - -\begin_layout Standard - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -$_=tbse_line(); chomp; # get line of data from binary_c -\end_layout - -\begin_layout Standard - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -if($_ eq 'fin') -\end_layout - -\begin_layout Standard - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -{ -\end_layout - -\begin_layout Standard - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -$brk=1; # the end of output -\end_layout - -\begin_layout Standard - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -} -\end_layout - -\begin_layout Standard - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -elsif(s/^MYLOG //) # regular expression to match and remove MYLOG -\end_layout - -\begin_layout Standard - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -{ -\end_layout - -\begin_layout Standard - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -split; # convert data string to array -\end_layout - -\begin_layout Standard - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -#... - do stuff with @_ ... -\end_layout - -\begin_layout Standard - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -# e.g. - $_[0] is the time, $_[1] is the probability etc. -\end_layout - -\begin_layout Standard - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -} -\end_layout - -\begin_layout Standard -} -\end_layout - -\begin_layout Subsection -Adding things up -\end_layout - -\begin_layout Standard -So you have the probabilities (and maybe the timesteps) for each timestep - of -\emph on -binary_c -\emph default - and for each star. - What do you do now? Well, you have to create meaningful statistics by summing - up the results. - The easiest way to do this is to use a global hash as in the following - example which counts the number of different types of -\begin_inset Quotes eld -\end_inset - -low mass -\begin_inset Quotes erd -\end_inset - - and -\begin_inset Quotes eld -\end_inset - -high mass -\begin_inset Quotes erd -\end_inset - - stars: -\begin_inset Newline newline -\end_inset - - -\end_layout - -\begin_layout Standard - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -elsif(s/^MYLOG //) # regular expression to match and remove MYLOG -\end_layout - -\begin_layout Standard - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -{ -\end_layout - -\begin_layout Standard - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -split; # convert data string to array -\end_layout - -\begin_layout Standard - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -my $dtp=$_[1]*$_[2];# calculate dt * p -\end_layout - -\begin_layout Standard - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -if($_[3]>8.0) -\end_layout - -\begin_layout Standard - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -{ -\end_layout - -\begin_layout Standard - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -# high mass star -\end_layout - -\begin_layout Standard - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -$results{'high-mass'}+=$dtp; -\end_layout - -\begin_layout Standard - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -} -\end_layout - -\begin_layout Standard - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -else -\end_layout - -\begin_layout Standard - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -{ -\end_layout - -\begin_layout Standard - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -# low mass star -\end_layout - -\begin_layout Standard - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -$results{'low-mass'}+=$dtp; -\end_layout - -\begin_layout Standard - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\family default -} -\end_layout - -\begin_layout Standard - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -} -\begin_inset Newline newline -\end_inset - - -\end_layout - -\begin_layout Standard -At the end of the first section of the grid.pl script it says -\begin_inset Quotes eld -\end_inset - -put your output here -\begin_inset Quotes erd -\end_inset - -. - This is where you should output the results, e.g. - -\end_layout - -\begin_layout Standard - -\family typewriter -# put output here -\end_layout - -\begin_layout Standard - -\family typewriter -printf -\begin_inset Quotes eld -\end_inset - -Ratio of the number of high to low mass stars = %g -\backslash -n -\begin_inset Quotes erd -\end_inset - -, -\end_layout - -\begin_layout Standard - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -$results{'high-mass'}/$results{'low-mass'}; -\end_layout - -\begin_layout Subsection -More advanced accountancy -\end_layout - -\begin_layout Standard -Consider the previous example. - Perhaps instead of simply having -\begin_inset Quotes eld -\end_inset - -low -\begin_inset Quotes erd -\end_inset - - and -\begin_inset Quotes eld -\end_inset - -high -\begin_inset Quotes erd -\end_inset - - mass stars you actually want to calculate a histogram of number of stars - as a function of mass at a certain time. -\end_layout - -\begin_layout Standard -The problem of how to force -\emph on -binary_c -\emph default - to output at given times is a tricky one which is not dealt with here. - However, you should consider following the -\family typewriter -VROT_LOGGING -\family default - code in -\emph on -binary_c -\emph default - (see -\family typewriter -deltat.c -\family default -) which does just this. - Let us assume you have fixed -\emph on -binary_c/nucsyn -\emph default - so it outputs the mass of each star every -\begin_inset Formula $1\,\mathrm{Myr}$ -\end_inset - -. - You want to bin the masses at each timestep, so you will have a series - of histograms. - Note that -\family typewriter -$dtp -\family default - is not required because you are not counting the number of stars in a given - -\emph on -phase -\emph default - but rather an instantaneous property of the stars at a given time -\family typewriter -$t -\family default -. -\end_layout - -\begin_layout Standard -Something like this will do it: -\begin_inset Newline newline -\end_inset - - -\end_layout - -\begin_layout Standard - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -elsif(s/^MYLOG //) # regular expression to match and remove MYLOG -\end_layout - -\begin_layout Standard - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -{ -\end_layout - -\begin_layout Standard - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -split; # convert data string to array -\end_layout - -\begin_layout Standard - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -my $t=$_[0]; # time (an integer number of Myr since the starburst) -\end_layout - -\begin_layout Standard - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -my $p=$_[1]; # probability -\end_layout - -\begin_layout Standard - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -my $m=$_[3]; # stellar mass -\end_layout - -\begin_layout Standard - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\end_layout - -\begin_layout Standard - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -# bin stellar mass in 1Msun bins -\end_layout - -\begin_layout Standard - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -$m = int(0.5+$m); -\end_layout - -\begin_layout Standard - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\end_layout - -\begin_layout Standard - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -$results{'mass histogram'}{$t}{$m}+=$p; # construct histogram -\end_layout - -\begin_layout Standard - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -} -\end_layout - -\begin_layout Standard -Things to note include: -\end_layout - -\begin_layout Itemize -The mass is binned to the nearest integer. - You can construct a similar expression for an arbitrary bin width. - Why do we do this? Well, if we take the instantaneous mass of each star - in a population at a given time there will be a huge number of different - masses because mass loss may be effective. - This would give a histogram with -\begin_inset Formula $N\times N_{t}=n_{\mathrm{M1}}\times n_{\mathrm{M2}}\times n_{\mathrm{a}}\times N_{t}$ -\end_inset - - bins where -\begin_inset Formula $N_{t}$ -\end_inset - - is the number of timesteps of -\emph on -binary_c -\emph default - output. - This is too much data to deal with and negates the whole purpose of making - a histogram! Bin your data: it makes life a lot easier -\end_layout - -\begin_layout Itemize -We could have similarly binned the time to include stars at an age -\begin_inset Formula $t$ -\end_inset - - to -\begin_inset Formula $t+\Delta t$ -\end_inset - - (in this case -\begin_inset Formula $\Delta t$ -\end_inset - - would be -\begin_inset Formula $1\,\mathrm{Myr}$ -\end_inset - -) but that smears out the results into -\begin_inset Formula $1\,\mathrm{Myr}$ -\end_inset - - bins. - In our case we have -\emph on -snapshots -\emph default -at a given time instead. -\end_layout - -\begin_layout Itemize -The time and mass are integers in this case, so we could have used arrays - (which have integer index) instead of hashes for the output, but if you - want finer resolution they will not be and hashes are -\emph on -required -\emph default -. - It is good to get into the habit. - -\end_layout - -\begin_layout Itemize -The 'mass histogram' hash label is not required in this simple example, - but in a real grid you may be constructing many different histograms, each - with different labels. -\end_layout - -\begin_layout Itemize -The results are saved in hash of hashes of hashes. - This is a typical example of a Perl nested variable, help for how to deal - with (and output) hashes of hashes is easily found with a simple web search - (or consult the excellent -\emph on -Programming Perl -\emph default -). -\end_layout - -\begin_layout Itemize -Beware resolution! Always test different resolutions and beware binning - and aliasing effects. -\end_layout - -\begin_layout Subsection -Save your data -- or process on the fly? -\end_layout - -\begin_layout Standard -Before running a grid you have to make the big decision: do you save your - data or process it all on the fly? There are advantages and disadvantages - to both, as described below. -\end_layout - -\begin_layout Subsubsection -Saving data -\end_layout - -\begin_layout Standard -\begin_inset CommandInset label -LatexCommand label -name "sub:saving_data" - -\end_inset - -In this case you run a grid and tag the initial parameters of each system - of interest (i.e. - the -\begin_inset Formula $M_{1}$ -\end_inset - -, -\begin_inset Formula $M_{2}$ -\end_inset - -, -\begin_inset Formula $a$ -\end_inset - - and -\begin_inset Formula $\delta V=\delta\ln M_{1}\,\delta\ln M_{2}\,\delta a$ -\end_inset - -). - -\emph on -You save these initial parameters into a large datafile. - -\emph default - The big advantage of this technique is that you can rerun the saved grid - -\emph on -from the datafile, -\emph default -possibly -\emph on - -\emph default -without running -\emph on -binary_c/nucsyn -\emph default - again, and with a different initial distribution function (e.g. - initial mass function) or very slightly different physics (on the assumption - that changing the physics will not change the systems which were saved). - -\end_layout - -\begin_layout Standard -You could save, as well as the initial parameters of the systems, the time - spent in the phase of interest, -\begin_inset Formula $\Delta t$ -\end_inset - -. - Each time the grid is rerun you would then calculate the probability -\begin_inset Formula $p_{i}$ -\end_inset - - for each system again, hence you know -\begin_inset Formula $p_{i}\Delta t$ -\end_inset - - which is your required -\begin_inset Quotes eld -\end_inset - -number of stars -\begin_inset Quotes erd -\end_inset - -. - You can either -\end_layout - -\begin_layout Enumerate -Change -\begin_inset Formula $p_{i}$ -\end_inset - - and recalculate your statistics. - This does -\emph on -not -\emph default -require the running of -\emph on -binary_c/nucsyn -\emph default - and is the fast option. -\end_layout - -\begin_layout Enumerate -Change -\begin_inset Formula $p_{i}$ -\end_inset - - and some physics, which requires rerunning of -\emph on -binary_c/nucsyn -\emph default -. - This is slower, but still faster than running the full grid. -\end_layout - -\begin_layout Standard -Saving the progenitor data set is a very useful way of saving time after - an initial high-resolution grid run. -\end_layout - -\begin_layout Subsubsection -On the fly data processing -\end_layout - -\begin_layout Standard -\begin_inset CommandInset label -LatexCommand label -name "sub:on-the-fly" - -\end_inset - - -\end_layout - -\begin_layout Standard -If you do not want to recalculate your answer with different initial functions, - you might be better off calculating the results you require -\begin_inset Quotes eld -\end_inset - -on the fly -\begin_inset Quotes erd -\end_inset - -. - This means you do your data processing -\emph on -in your grid script -\emph default -. - The main advantages to this are speed and data storage. - For example, if you have -\begin_inset Formula $10^{6}$ -\end_inset - - -\begin_inset space ~ -\end_inset - -stars in your grid, that is -\begin_inset Formula $10^{6}$ -\end_inset - - -\begin_inset space ~ -\end_inset - -lines of data -- this might be a lot of data. -\end_layout - -\begin_layout Standard -In some cases you -\emph on -must -\emph default - do this. - If you are looking at data which is time dependent then you will have -\begin_inset Formula $10^{6}\times N_{t}$ -\end_inset - - -\begin_inset space ~ -\end_inset - -lines of data, where -\begin_inset Formula $N_{t}$ -\end_inset - - is the number of timesteps during which your system is of interest. - -\begin_inset Formula $N_{t}$ -\end_inset - - may be many hundreds for a given system, hence the total number of lines - of data is of the order of -\begin_inset Formula $10^{8}$ -\end_inset - - and the data storage requirements become quite ridiculous. - For example, a typical line of data has about 200 characters, so -\begin_inset Formula $200\times10^{8}=2\times10^{10}\,\mathrm{bytes}$ -\end_inset - - of data, or -\begin_inset Formula $20\,\mbox{GB}$ -\end_inset - -. - The time it takes to process all this data may be longer than the time - to -\emph on -rerun -\emph default - -\emph on -binary_c/nucsyn -\emph default -for each system, especially if your data storage is non-local (e.g. - on an NFS (network) partition). - Furthermore, you might not have 20 -\begin_inset space ~ -\end_inset - -GB available to you\SpecialChar \ldots{} - -\end_layout - -\begin_layout Standard -You can save some space by outputting data every, say, Myr, but this may - not be the time resolution you require to catch systems of interest. -\end_layout - -\begin_layout Standard -\begin_inset Newpage pagebreak -\end_inset - - -\end_layout - -\begin_layout Section -Grid options -\end_layout - -\begin_layout Standard -\begin_inset CommandInset label -LatexCommand label -name "sec:grid-options" - -\end_inset - -The following summarises the -\family typewriter -%grid_options -\family default - hash elements: -\end_layout - -\begin_layout Description - -\family typewriter -adapt_sepdist -\family default - The default separation distribution runs from -\begin_inset Formula $3\,\mathrm{R}_{\odot}$ -\end_inset - - to -\begin_inset Formula $10^{4}\,\mathrm{R}_{\odot}$ -\end_inset - - but the lower limit may be too close to avoid immediate Roche-lobe overflow - (and contact/merger) in massive stars. - Use -\family typewriter -adapt_sepdist=1 -\family default - to avoid this situation by adaptively increasing the lower limit to avoid - instantaneous mergers. - (See -\family typewriter -sepdist_min -\family default -.) -\end_layout - -\begin_layout Description - -\family typewriter -alarm_procedure -\family default - When a signal is captured (usually on a timeout) the alarm_procedure tells - us what to do. - If -\begin_inset Formula $0$ -\end_inset - - then the grid exits. - If -\begin_inset Formula $1$ -\end_inset - - it tries to restart on the next star (although this may be buggy it is - the default!). - Really you should fix the problem if there is a timeout because it should - not happen. -\end_layout - -\begin_layout Description - -\family typewriter -args -\family default - Not technically an option, but is the string of arguments which is passed - to -\emph on -binary_c/nucsyn -\emph default -. - Useful for logging or debugging. -\end_layout - -\begin_layout Description - -\family typewriter -binary -\family default - The duplicity. - If binary is 1 then the grid runs binary stars, if 0 then single stars. -\end_layout - -\begin_layout Description - -\family typewriter -colour -\family default - If -\family typewriter -colour=1 -\family default - then verbose output (see -\family typewriter -vb -\family default -) is in colour, using the -\family typewriter -Term::ANSIColor -\family default - Perl module. - This is recommended. -\end_layout - -\begin_layout Description - -\family typewriter -compatibility_mode -\family default - An old (probably now deprecated) option which deletes the -\family typewriter -nucsyn_metallicity -\family default - from -\family typewriter -bse_options -\family default -. - Should no longer be required, so set it to zero. -\end_layout - -\begin_layout Description - -\family typewriter -dm -\family default - Not really a grid option, but stores the current -\begin_inset Formula $\delta M=M\delta\ln M$ -\end_inset - -. - (Was once) useful for debugging. -\end_layout - -\begin_layout Description - -\family typewriter -exit_on_eval_failure -\family default - When each star is run, it is inside a -\emph on -Perl -\emph default - -\family typewriter -eval -\family default - construct. - If there is an error (i.e. - -\family typewriter -$@ -\family default - is not undef) -\emph on -and -\emph default - -\family typewriter -exit_on_eval_failure -\family default - is defined then the grid is stopped. - Otherwise, the grid goes on in the hope that the error does not persist - (possibly dubious!). -\end_layout - -\begin_layout Description - -\family typewriter -extra_flash_resolution -\family default - Use this option to provide extra mass resolution around -\begin_inset Formula $1.9\,\mathrm{M}_{\odot}$ -\end_inset - - (the upper mass of the helium flash) in the lookup table used for the -\family typewriter -time_adaptive_mass_grid -\family default - (see that option and -\family typewriter -stellar_lifetime_table_nm -\family default -). -\end_layout - -\begin_layout Description - -\family typewriter -fixed_m1 -\family default - Set to -\begin_inset Formula $1$ -\end_inset - - if there is only one -\begin_inset Formula $M_{1}$ -\end_inset - - in the binary grid, otherwise keep set to zero. -\end_layout - -\begin_layout Description - -\family typewriter -imf1 -\family default - The primary star initial mass, -\begin_inset Formula $M$ -\end_inset - - or -\begin_inset Formula $M_{1}$ -\end_inset - -, function/distribution, usually -\begin_inset Quotes eld -\end_inset - -ktg93 -\begin_inset Quotes erd -\end_inset - -. - See -\emph on -IMF.pm -\emph default - (Section -\begin_inset space ~ -\end_inset - - -\begin_inset CommandInset ref -LatexCommand ref -reference "sec:initial-dists" - -\end_inset - -). -\end_layout - -\begin_layout Description - -\family typewriter -imf2 -\family default - The secondary star mass (or mass ratio -\begin_inset Formula $q=M_{2}/M_{1}$ -\end_inset - -) function/distribution, usually -\begin_inset Quotes eld -\end_inset - -flatq -\begin_inset Quotes erd -\end_inset - -. - See -\emph on -IMF.pm -\emph default - (Section -\begin_inset space ~ -\end_inset - - -\begin_inset CommandInset ref -LatexCommand ref -reference "sec:initial-dists" - -\end_inset - -). -\end_layout - -\begin_layout Description - -\family typewriter -imf2_exponent -\family default - The exponent in the secondary star -\begin_inset Formula $q$ -\end_inset - - distribution if it is a power law (0 is flat). -\end_layout - -\begin_layout Description - -\family typewriter -imf2_minm -\family default - The minimum mass in the secondary star -\begin_inset Formula $q$ -\end_inset - - distribution, usually -\begin_inset Formula $0.1$ -\end_inset - -( -\begin_inset Formula $\mathrm{M}_{\odot}$ -\end_inset - -). -\end_layout - -\begin_layout Description - -\family typewriter -imf2_maxm -\family default - The maximum mass in the secondary star -\begin_inset Formula $q$ -\end_inset - - distribution, usually -\begin_inset Quotes eld -\end_inset - -auto -\begin_inset Quotes erd -\end_inset - - (which means use -\begin_inset Formula $M_{1}$ -\end_inset - - as the maximum). - You can, alternatively, set this to an actual number, in which case you'll - be running a square ( -\begin_inset Formula $M_{2}\leq M_{2,\mathrm{max}}$ -\end_inset - -) rather than triangular ( -\begin_inset Formula $M_{2}\leq M_{1}$ -\end_inset - -) grid so you'll be needlessly repeating systems and reducing the grid resolutio -n in -\begin_inset Formula $M_{2}$ -\end_inset - -. -\end_layout - -\begin_layout Description - -\family typewriter -imf2_minq -\family default - The minimum -\begin_inset Formula $q$ -\end_inset - - value allowed on the grid, usually -\family typewriter -undef -\family default - and ignored (overrides -\family typewriter -imf2_minq -\family default -). -\end_layout - -\begin_layout Description - -\family typewriter -imf2_maxq -\family default - The maximum -\begin_inset Formula $q$ -\end_inset - - value allowed on the grid, usually -\begin_inset Formula $1$ -\end_inset - -. - (Overrides -\family typewriter -imf2_maxm -\family default -) -\end_layout - -\begin_layout Description - -\family typewriter -lastargs -\family default - Very similar to log_args but at a slightly different place in the code. - Should be avoided, use -\family typewriter -log_args -\family default - instead. -\end_layout - -\begin_layout Description - -\family typewriter -libpath -\family default - Path to libraries to be included in the calling of the -\emph on -binary_c/nucsyn -\emph default - executable. - This harks back to the days when -\emph on -binary_c/nucsyn -\emph default - was built as a set of shared libraries. - These days it is built statically, so libpath is usually an empty string - (and hence is ignored). -\end_layout - -\begin_layout Description - -\family typewriter -log_args -\family default - If this is set to -\begin_inset Formula $1$ -\end_inset - - then the arguments passed to -\emph on -binary_c/nucsyn -\emph default - are saved in a file in -\family typewriter -/tmp/ -\family default - (usually -\family typewriter -/tmp/binary_c-args -\family default - or similar, with separate files for each thread). - This is very useful when the grid freezes as you can immediately see which - stellar system has caused the problem and then rerun it manually. - -\end_layout - -\begin_layout Description - -\family typewriter -log_normal_median -\family default - The median value of a log-normal mass distribution (see -\emph on -IMF -\emph default -.pm, Section -\begin_inset space ~ -\end_inset - - -\begin_inset CommandInset ref -LatexCommand ref -reference "sec:initial-dists" - -\end_inset - -). -\end_layout - -\begin_layout Description - -\family typewriter -log_normal_dispersion -\family default - The dispersion of a log-normal mass distribution (see -\emph on -IMF -\emph default -.pm, Section -\begin_inset space ~ -\end_inset - - -\begin_inset CommandInset ref -LatexCommand ref -reference "sec:initial-dists" - -\end_inset - -). -\end_layout - -\begin_layout Description - -\family typewriter -masshash_function -\family default - This can be set to an alternative function to make the -\begin_inset Formula $M$ -\end_inset - - or -\begin_inset Formula $M_{1}$ -\end_inset - - -\family typewriter -%masshash -\family default -. - (The default is -\family typewriter -undef -\family default - so it is ignored.) -\end_layout - -\begin_layout Description - -\family typewriter -mmax -\family default - The maximum mass at which the single -\begin_inset Formula $M$ -\end_inset - - or primary mass -\begin_inset Formula $M_{1}$ -\end_inset - - grid ends (in -\begin_inset Formula $M_{\odot}$ -\end_inset - -, default -\begin_inset Formula $80$ -\end_inset - -). - -\family typewriter - -\end_layout - -\begin_layout Description - -\family typewriter -m2max -\family default - The maximum mass at which the secondary mass -\begin_inset Formula $M_{2}$ -\end_inset - - grid ends (in -\begin_inset Formula $M_{\odot}$ -\end_inset - -, default -\begin_inset Formula $80$ -\end_inset - -). -\end_layout - -\begin_layout Description - -\family typewriter -mmin -\family default - The minimum mass at which the single -\begin_inset Formula $M$ -\end_inset - - or primary -\begin_inset Formula $M_{1}$ -\end_inset - - mass grid begins (in -\begin_inset Formula $M_{\odot}$ -\end_inset - -, default -\begin_inset Formula $0.1$ -\end_inset - -). -\end_layout - -\begin_layout Description - -\family typewriter -m2min -\family default - The minimum mass at which the secondary mass -\begin_inset Formula $M_{2}$ -\end_inset - - grid begins (in -\begin_inset Formula $M_{\odot}$ -\end_inset - -, default -\begin_inset Formula $0.1$ -\end_inset - -). -\end_layout - -\begin_layout Description - -\family typewriter -m2zoom -\family default - If set to 1 then for -\begin_inset Formula $M_{2}/M_{1}=q>$ -\end_inset - -m2q_zoom_q the resolution is set to m2q_zoom_n. - This can be used to increase the number of stars in the high -\begin_inset Formula $q$ -\end_inset - - -\end_layout - -\begin_layout Description - -\family typewriter -necc -\family default - The number of stars in the eccentricity -\begin_inset Formula $e$ -\end_inset - - dimension of the grid. - If -\begin_inset Formula $1$ -\end_inset - - then the eccentricity is constant (usually zero, depends on the -\family typewriter -bse_option -\family default -). -\end_layout - -\begin_layout Description - -\family typewriter -newline -\family default - If -\family typewriter -vb=1 -\family default - then the value of this option is used as the end of line character. - You can use either -\family typewriter - -\begin_inset Quotes eld -\end_inset - - -\backslash -x0d -\begin_inset Quotes erd -\end_inset - - -\family default - (just a carriage return) or -\family typewriter - -\begin_inset Quotes eld -\end_inset - - -\backslash -n -\begin_inset Quotes erd -\end_inset - - -\family default - which is the carriage return with a line feed (the usual concept of -\begin_inset Quotes eld -\end_inset - -new line -\begin_inset Quotes erd -\end_inset - -). -\end_layout - -\begin_layout Description - -\family typewriter -nice -\family default - A string containing the nice command used to run -\shape italic -binary_c/nucsyn -\shape default -. - Usually no nice is used, so this is ' -\family typewriter -nice -n +0 -\family default -'. - You can leave this as it is and run ' -\family typewriter -nice grid.pl -\family default -' if you want the whole grid to be -\begin_inset Quotes eld -\end_inset - -niced -\begin_inset Quotes erd -\end_inset - -. -\end_layout - -\begin_layout Description - -\family typewriter -nmlow -\family default - The grid uses the values in the -\family typewriter -@mlist -\family default - between index -\family typewriter -nmlow -\family default - and -\family typewriter -nmhigh -\family default -. - If zero then all stars are used. -\end_layout - -\begin_layout Description - -\family typewriter -nmhigh -\family default - See -\family typewriter -nmlow -\family default -. -\end_layout - -\begin_layout Description - -\family typewriter -nm -\family default - The number of single star masses -\begin_inset Formula $M$ -\end_inset - - used in the grid. -\end_layout - -\begin_layout Description - -\family typewriter -nm1 -\family default - The number of primary star masses -\begin_inset Formula $M_{1}$ -\end_inset - - used in the grid. -\end_layout - -\begin_layout Description - -\family typewriter -nmod -\family default - When -\family typewriter -vb=1 -\family default - information on the grid is output every -\family typewriter -nmod -\family default - models or, if -\family typewriter -nmod -\family default - is zero, once every second. -\end_layout - -\begin_layout Description - -\family typewriter -nper -\family default - The number of stars in the period -\begin_inset Formula $P$ -\end_inset - - dimension. -\end_layout - -\begin_layout Description - -\family typewriter -nsep -\family default - The number of stars in the separation -\begin_inset Formula $a$ -\end_inset - - dimension. -\end_layout - -\begin_layout Description - -\family typewriter -parse_bse_function_pointer -\family default - In your grid script you need to define a subroutine (also known as a function) - to be used for data parsing. - Usually this is called -\family typewriter -parse_bse -\family default -. - and is set with a line in -\emph on -grid-xxx.pl -\emph default - like this: -\begin_inset Newline newline -\end_inset - - -\family typewriter -$binary_grid::grid_options{'parse_bse_function_pointer'}= -\backslash -&parse_bse; -\family default - -\begin_inset Newline newline -\end_inset - -You have to provide a pointer to this function in order that the grid software - knows where to send the output of -\emph on -binary_c/nucsyn -\emph default -. -\end_layout - -\begin_layout Description - -\family typewriter -period_dist -\family default - You may want to use a period-based initial distribution instead of the - default separation distribution, e.g. - for the -\begin_inset CommandInset citation -LatexCommand citet -key "1991A&A...248..485D" - -\end_inset - - initial distribution. - In this case set -\family typewriter -sepdist -\family default - to -\family typewriter - -\begin_inset Quotes eld -\end_inset - -period -\begin_inset Quotes erd -\end_inset - - -\family default - and choose -\family typewriter -period_dist= -\begin_inset Quotes erd -\end_inset - -gaussian -\begin_inset Quotes erd -\end_inset - - -\family default -. - (See -\emph on -IMF.pm -\emph default - for options.) Note that a Gaussian distribution requires a given minimum - and maximum period to be specified (in order that it normalises to -\begin_inset Formula $1$ -\end_inset - -). -\end_layout - -\begin_layout Description - -\family typewriter -period_dist_log_min -\family default - Minimum log period ( -\begin_inset Formula $\log_{10}P$ -\end_inset - -) of the initial distribution in days. - -\end_layout - -\begin_layout Description - -\family typewriter -period_dist_log_max -\family default - Maximum log period ( -\begin_inset Formula $\log_{10}P$ -\end_inset - -) of the initial distribution in days. -\end_layout - -\begin_layout Description - -\family typewriter -period_dist_mean_log -\family default - (log) Mean of the Gaussian period distribution in days. -\end_layout - -\begin_layout Description - -\family typewriter -period_dist_sigma -\family default - The width of the period distribution Gaussian (log days). -\end_layout - -\begin_layout Description - -\family typewriter -period_log_min -\family default - The minimum log period (days) in the period grid (not the initial distribution). -\end_layout - -\begin_layout Description - -\family typewriter -period_log_max -\family default - The maximum log period (days) in the period grid (not the initial distribution). -\end_layout - -\begin_layout Description - -\family typewriter -plaw_m0 -\family default - Minimum mass of the three-part power law -\begin_inset CommandInset citation -LatexCommand citet* -key "KTG1993MNRAS-262-545K" - -\end_inset - - initial mass function ( -\begin_inset Formula $0.1\,\mathrm{M}_{\odot}$ -\end_inset - -). -\end_layout - -\begin_layout Description - -\family typewriter -plaw_m1 -\family default - Mass break 1 of the three-part power law -\begin_inset CommandInset citation -LatexCommand citet* -key "KTG1993MNRAS-262-545K" - -\end_inset - - initial mass function ( -\begin_inset Formula $0.5\,\mathrm{M}_{\odot}$ -\end_inset - -). -\end_layout - -\begin_layout Description - -\family typewriter -plaw_m2 -\family default - Mass break 2 of the three-part power law -\begin_inset CommandInset citation -LatexCommand citet* -key "KTG1993MNRAS-262-545K" - -\end_inset - - initial mass function ( -\begin_inset Formula $1.0\,\mathrm{M}_{\odot}$ -\end_inset - -). -\end_layout - -\begin_layout Description - -\family typewriter -plaw_mmax -\family default - Maximum mass of the three-part power law -\begin_inset CommandInset citation -LatexCommand citet* -key "KTG1993MNRAS-262-545K" - -\end_inset - - initial mass function ( -\begin_inset Formula $80\,\mathrm{M}_{\odot}$ -\end_inset - -). -\end_layout - -\begin_layout Description - -\family typewriter -plaw_p -\family default - Slope of the (single) power-law initial mass function (e.g. - -\begin_inset Formula $-2.35$ -\end_inset - - for Salpeter). -\end_layout - -\begin_layout Description - -\family typewriter -plaw_p1 -\family default - Slope 1 of the three-part power law -\begin_inset CommandInset citation -LatexCommand citet* -key "KTG1993MNRAS-262-545K" - -\end_inset - - initial mass function ( -\begin_inset Formula $-1.3$ -\end_inset - -). -\end_layout - -\begin_layout Description - -\family typewriter -plaw_p2 -\family default - Slope 2 of the three-part power law -\begin_inset CommandInset citation -LatexCommand citet* -key "KTG1993MNRAS-262-545K" - -\end_inset - - initial mass function ( -\begin_inset Formula $-2.2$ -\end_inset - -). -\end_layout - -\begin_layout Description - -\family typewriter -plaw_p3 -\family default - Slope 3 of the three-part power law -\begin_inset CommandInset citation -LatexCommand citet* -key "KTG1993MNRAS-262-545K" - -\end_inset - - initial mass function ( -\begin_inset Formula $-2.7$ -\end_inset - -). -\end_layout - -\begin_layout Description - -\family typewriter -prob1 -\family default - If this is set to -\begin_inset Formula $1$ -\end_inset - - then all probabilities are -\begin_inset Formula $1.0$ -\end_inset - - (i.e. - -\family typewriter -calc_prob -\family default - is ignored). -\end_layout - -\begin_layout Description - -\family typewriter -prog -\family default - The -\emph on -binary_c/nucsyn -\emph default - executable name, usually ' -\family typewriter -binary_c -\family default -'. - See also -\family typewriter -rootpath -\family default -. -\end_layout - -\begin_layout Description - -\family typewriter -progenitor -\family default - Not really a grid option, but stores the system information ( -\begin_inset Formula $M$ -\end_inset - - or -\begin_inset Formula $M_{1}$ -\end_inset - -, -\begin_inset Formula $M_{2}$ -\end_inset - -, -\begin_inset Formula $a$ -\end_inset - -, -\begin_inset Formula $P$ -\end_inset - -, -\begin_inset Formula $e$ -\end_inset - -, -\begin_inset Formula $p$ -\end_inset - - etc.) -- useful for debugging or logging. -\end_layout - -\begin_layout Description - -\family typewriter -progenitor_hash -\family default - As progenitor but stores each item in a hash. -\end_layout - -\begin_layout Description - -\family typewriter -qmax -\family default - The maximum value of -\begin_inset Formula $q=M_{1}/M_{2}$ -\end_inset - - allowed in the grid, usually -\begin_inset Formula $1$ -\end_inset - -. -\end_layout - -\begin_layout Description - -\family typewriter -q_mean -\family default - When using a -\family typewriter -imf2= -\begin_inset Quotes erd -\end_inset - -gaussian -\begin_inset Quotes erd -\end_inset - - -\family default - the secondary mass ratio -\begin_inset Formula $q$ -\end_inset - - distribution is a Gaussian with centre -\family typewriter -q_mean -\family default - and width -\family typewriter -q_sigma -\family default -. - Useful for setting up a secondary mass distribution according to -\begin_inset CommandInset citation -LatexCommand citet -key "1991A&A...248..485D" - -\end_inset - -. - See also Section -\begin_inset space ~ -\end_inset - - -\begin_inset CommandInset ref -LatexCommand ref -reference "sec:initial-dists" - -\end_inset - -. -\end_layout - -\begin_layout Description - -\family typewriter -q_sigma -\family default - See -\family typewriter -q_mean -\family default -. -\end_layout - -\begin_layout Description - -\family typewriter -ref_tick_file -\family default - File from which timer (tick count) information is loaded. - See -\family typewriter -tick_counts -\family default -. -\end_layout - -\begin_layout Description - -\family typewriter -repeat -\family default - The number of times -\family typewriter -tbse() -\family default - is called for each grid point, default is -\begin_inset Formula $1$ -\end_inset - -. - This is useful for increasing the resolution in situations where Monte-Carlo - methods are used such as the random supernova or white dwarf kicks. -\end_layout - -\begin_layout Description - -\family typewriter -rootpath -\family default - The directory in which the -\emph on -binary_c/nucsyn -\emph default - code source and executable reside. - See also -\family typewriter -prog -\family default -. -\end_layout - -\begin_layout Description - -\family typewriter -runtime_function_pointer -\family default - A custom function which returns the time it takes (in CPU seconds) to run - a star of a given mass, used to split the single/primary mass range into - chunks and hence for load balancing in the threaded grid. - This is the old way of doing things, newer grids should use the tick counts - to time the runs of a test grid. - -\end_layout - -\begin_layout Description - -\family typewriter -runtime_lowmass -\family default - The runtime for a low-mass star that would otherwise never be run. - -\begin_inset Newline newline -\end_inset - -See -\family typewriter -runtime_function_pointer -\family default -. -\end_layout - -\begin_layout Description - -\family typewriter -secondary_mass_generator_function -\family default - Function to generate the list of secondary masses. - Usually this is set to the default function -\family typewriter - -\backslash -&populate_m2list -\family default -. -\end_layout - -\begin_layout Description - -\family typewriter -sepdist -\family default - The initial separation distribution, usually -\family typewriter - -\begin_inset Quotes eld -\end_inset - -flat -\begin_inset Quotes erd -\end_inset - - -\family default -, see -\emph on -IMF.pm -\emph default - (Section -\begin_inset space ~ -\end_inset - - -\begin_inset CommandInset ref -LatexCommand ref -reference "sec:initial-dists" - -\end_inset - -). -\end_layout - -\begin_layout Description - -\family typewriter -sepdist_exponent -\family default - If the separation distribution is a power law, the exponent is given by - this option. -\end_layout - -\begin_layout Description - -\family typewriter -sepdist_min -\family default - The minimum initial separation (solar radii) in the initial separation - distribution (but -\emph on -not -\emph default - the grid). -\end_layout - -\begin_layout Description - -\family typewriter -sepdist_max -\family default - The maximum initial separation (solar radii) in the initial separation - distribution (but -\emph on -not -\emph default - the grid). -\end_layout - -\begin_layout Description - -\family typewriter -sepmax -\family default - The maximum separation -\begin_inset Formula $a$ -\end_inset - - of the grid (solar radii). - -\end_layout - -\begin_layout Description - -\family typewriter -sepmin -\family default - The minimum separation -\begin_inset Formula $a$ -\end_inset - - of the grid (solar radii). -\end_layout - -\begin_layout Description - -\family typewriter -stellar_lifetime_table_nm -\family default - When the time adaptive mass grid is used (see -\family typewriter -time_adaptive_mass_grid -\family default -) a function is required to convert from stellar mass to stellar lifetimes. - This is interpolated from a (small) table of (single-star) models run at - the beginning of the grid. - -\family typewriter -stellar_lifetime_table_nm -\family default - is (approximately) the number of stars in this table, although -\family typewriter -time_adaptive_mass_grid_nlow _mass_stars -\family default - is the number of stars at low-mass in the table (because this probably - requires extra resolution due to -\begin_inset Formula $t\sim M^{3}$ -\end_inset - -) and there can also be extra stars around the helium flash lifetime (see - -\family typewriter -extra_flash_resolution -\family default -). -\end_layout - -\begin_layout Description - -\family typewriter -test -\family default - If test is set to 1 then the grid is run without calling tbse for each - system. - This is useful for testing the grid or calculating the total mass in stars. -\end_layout - -\begin_layout Description - -\family typewriter -test_grid_function_pointer -\family default - A pointer to a function which is called for each star in a test grid. - Ignored if -\family typewriter -undef -\family default -. -\end_layout - -\begin_layout Description - -\family typewriter -test_grid_mmax -\family default - The maximum single/primary mass used when running the test grid. -\end_layout - -\begin_layout Description - -\family typewriter -test_grid_mmin -\family default - The minimum single/primary mass used when running the test grid. -\end_layout - -\begin_layout Description - -\family typewriter -test_grid_only -\family default - If 1 then the code exits immediately after running the test grid. -\end_layout - -\begin_layout Description - -\family typewriter -thread_max_freeze_time_before_warning -\family default - The maximum time a thread loops its calls to -\family typewriter -tbse() -\family default - before a warning is issued (seconds, default 10). -\end_layout - -\begin_layout Description - -\family typewriter -thread_num -\family default - Not really an option, but stores the thread number of the current grid, - or -\family typewriter -undef -\family default - if threads are not being used. -\end_layout - -\begin_layout Description - -\family typewriter -thread_precreate_function_pointer -\family default - A pointer to a function to be called just before -\family typewriter -threads->create -\family default - is used to start a thread. - Ignored if -\family typewriter -undef -\family default -. -\end_layout - -\begin_layout Description - -\family typewriter -thread_prejoin_function_pointer -\family default - A pointer to a function called just before a thread is -\family typewriter -join -\family default -ed. - Ignored if -\family typewriter -undef -\family default -. -\end_layout - -\begin_layout Description - -\family typewriter -thread_presleep -\family default -A thread waits for this length of time (in seconds) before it starts in - order that all other threads have time to start before any output is logged - to the screen. - As such this is just to keep output pretty and should be small (default - 1 second). -\end_layout - -\begin_layout Description - -\family typewriter -thread_postjoin_function_pointer -\family default - A pointer to a function called just after a thread is -\family typewriter -join -\family default -ed. - Ignored if -\family typewriter -undef -\family default -. -\end_layout - -\begin_layout Description - -\family typewriter -thread_postrun_function_pointer -\family default - A pointer to a function to be called just after a -\family typewriter -thread->create -\family default - call (and just after -\family typewriter -$@ -\family default - is checked for a thread-creation error). - Ignored if -\family typewriter -undef -\family default -. -\end_layout - -\begin_layout Description - -\family typewriter -threads_entry_fun -\family default - A pointer to a function called from inside a thread just before grid() - is called. -\end_layout - -\begin_layout Description - -\family typewriter -threads_flush_fun -\family default - A pointer to a function called from inside a thread just after grid() returns. -\end_layout - -\begin_layout Description - -\family typewriter -threads_join_function_pointer -\family default - When using a threaded grid you have to define a subroutine (also known - as a function) pointer which points to the function to be called after - each thread have finished. - This function is responsible for -\begin_inset Quotes eld -\end_inset - -joining -\begin_inset Quotes erd -\end_inset - - the threads, which means it collects the results from the thread and adds - them to the global results. - This is usually a function called -\family typewriter -join_thread -\family default - and is set with a line in grid-xxx.pl similar to: -\begin_inset Newline newline -\end_inset - - -\family typewriter -$binary_grid::grid_options{'threads_join_function_pointer'}= -\backslash -&join_thread; -\end_layout - -\begin_layout Description - -\family typewriter -threads_stack_size -\family default - The stack size (in MBytes) for each of the Perl threads launched when -\family typewriter - -\begin_inset Newline newline -\end_inset - -threaded_grid -\family default - is used (see Section -\begin_inset space ~ -\end_inset - - -\begin_inset CommandInset ref -LatexCommand ref -reference "sec:threads" - -\end_inset - -). - Default is 32 (MBytes). -\end_layout - -\begin_layout Description - -\family typewriter -tick_counts -\family default - When threaded grids are used, the time it takes to run a system can be - computed using the tick_counts method. - With sufficiently accurate timing the load of each thread can be calculated - in advance and the mass grid split up accordingly. - This currently works only on CPUs which support the -\emph on -binary_c/nucsyn -\emph default - code options (see -\family typewriter -code_options.h -\family default -) -\family typewriter -RDTSC -\family default - and -\family typewriter -RDTSC_TIMER_PER_SYSTEM -\family default - (i.e. - Intel/AMD and compatible x86 architectures). - Note that if -\family typewriter -tick_counts -\family default - is 1 then tick clounts are merely saved, to -\emph on -use -\emph default -them you have to set -\family typewriter -use_ref_tick_counts -\family default - to 1. - This means you can rerun the grid without rerunning the tick count test - grid (instead the file is used, -\begin_inset Newline newline -\end_inset - -see -\family typewriter -tick_counts_file -\family default -). -\end_layout - -\begin_layout Description - -\family typewriter -tick_counts_file -\family default - File in which the timer (tick count) information is saved. -\end_layout - -\begin_layout Description - -\family typewriter -time_adaptive_mass_grid -\family default - This activates the time-adaptive mass grid such that the initial single/primary - masses -\begin_inset Formula $M_{1}$ -\end_inset - - are chosen to given equal -\begin_inset Quotes eld -\end_inset - -output -\begin_inset Quotes erd -\end_inset - - per unit time. - In this case -\begin_inset Quotes eld -\end_inset - -output -\begin_inset Quotes erd -\end_inset - - means stellar yield (i.e. - mass ejected) but this mostly comes at the end of the stellar evolution, - so the -\family typewriter -time_adaptive_mass_grid -\family default - can be used for other things such as supernovae which also occur then. - See the other -\family typewriter -time_adaptive_mass_grid -\family default - options and -\family typewriter -stellar_lifetime_table_nm -\family default -. -\end_layout - -\begin_layout Description - -\family typewriter -time_adaptive_mass_grid_step -\family default - The step in time -\begin_inset Formula $\Delta t$ -\end_inset - - which is converted to a corresponding -\begin_inset Formula $\Delta M_{1}$ -\end_inset - - in the -\family typewriter -time_adaptive_mass_grid -\family default - (see previous). -\end_layout - -\begin_layout Description - -\family typewriter -time_adaptive_mass_grid_log10_time -\family default - If this is true then instead of -\begin_inset Formula $\Delta M_{1}$ -\end_inset - - giving equal spacing in time -\begin_inset Formula $t$ -\end_inset - - instead equal spacing is calculated in -\begin_inset Formula $\log t$ -\end_inset - -. -\end_layout - -\begin_layout Description - -\family typewriter -time_adaptive_mass_grid_log10_step -\family default - -\begin_inset Formula $\Delta\log t$ -\end_inset - - for the previous entry. -\end_layout - -\begin_layout Description - -\family typewriter -time_adaptive_mass_grid_nlow_mass_stars -\family default - The number of low-mass stars run in the test grid which calculates stellar - lifetimes. - See -\family typewriter -stellar_lifetime_table_nm -\family default -. -\end_layout - -\begin_layout Description - -\family typewriter -timeout -\family default - When possible the grid sets an alarm (a Linux/UNIX signal) which means - that warnings are given and perhaps the grid stopped after -\family typewriter -timeout -\family default - seconds. - Set to zero to ignore, usually 30 is enough. - This assumes your -\emph on - binary_c/nucsyn -\emph default - process takes less than -\family typewriter -timeout -\family default - seconds to run a system so if you have problems with this please check - your system to make sure you have the CPU time you need. -\end_layout - -\begin_layout Description - -\family typewriter -use_ref_tick_counts -\family default - Switches on the use of tick count information for load balancing. - See -\family typewriter -tick_counts -\family default -. -\end_layout - -\begin_layout Description - -\family typewriter -vb -\family default - Verbosity level. - With -\family typewriter -vb=1 -\family default - you get some output about the grid, i.e. - the number of stars run, the number to go, the current -\begin_inset Formula $M$ -\end_inset - -, or -\begin_inset Formula $M_{1}$ -\end_inset - -, -\begin_inset space ~ -\end_inset - - -\begin_inset Formula $M_{2}$ -\end_inset - - and -\begin_inset Formula $a$ -\end_inset - -, an estimate of the time taken, time remaining and the time at which the - grid is expected to finish. - You may also get information about memory usage (if available). - Make sure your terminal window is quite wide to accommodate the information! - If -\family typewriter -vb=2 -\family default - you will get additional information about each system. - This is very useful for determining which stellar system is causing the - code to freeze and/or crash. - See also -\family typewriter -nmod -\family default -, -\family typewriter -colour -\family default - and -\family typewriter -log_args -\family default -. - Some verbose logging is only switched on if -\family typewriter -vb=3 -\family default -, although this should be considered experimental. -\end_layout - -\begin_layout Standard -\begin_inset Newpage pagebreak -\end_inset - - -\end_layout - -\begin_layout Section -Initial distributions (IMF etc.) -\end_layout - -\begin_layout Standard -\begin_inset CommandInset label -LatexCommand label -name "sec:initial-dists" - -\end_inset - -The initial distributions of stellar masses, mass ratios, separations and - periods are handled by the -\emph on -IMF.pm -\emph default - Perl module. - The general idea is that given a set of stellar parameters -\begin_inset Formula $M_{1}$ -\end_inset - -, -\begin_inset Formula $M_{2}$ -\end_inset - - and -\begin_inset Formula $a$ -\end_inset - - (or -\begin_inset Formula $P$ -\end_inset - -) and phase volume -\begin_inset Formula $\delta\ln M_{1}$ -\end_inset - -, -\begin_inset Formula $\delta\ln M_{2}$ -\end_inset - - and -\begin_inset Formula $\delta\ln a$ -\end_inset - - (or -\begin_inset Formula $\delta\ln P$ -\end_inset - -) the probability of existence of star -\begin_inset Formula $i$ -\end_inset - - is calculated from -\end_layout - -\begin_layout Standard -\begin_inset Formula -\begin{eqnarray} -p_{i} & = & \Psi(M_{1})\Phi(M_{2})\chi(a)\,\delta\ln M_{1}\,\delta\ln M_{2}\,\delta\ln a\nonumber \\ - & = & \Psi\Phi\chi\delta\ln V\label{eq:prob-eq} -\end{eqnarray} - -\end_inset - -where -\begin_inset Formula $\delta\ln V$ -\end_inset - - is the 'logphasevol' (as stored in the progenitor hash, see Section -\begin_inset space ~ -\end_inset - - -\begin_inset CommandInset ref -LatexCommand ref -reference "sec:grid-options" - -\end_inset - -). - The functions -\begin_inset Formula $\Psi$ -\end_inset - -, -\begin_inset Formula $\Phi$ -\end_inset - - and -\begin_inset Formula $\chi$ -\end_inset - - are not necessarily independent (e.g. - -\begin_inset Formula $\Phi(M_{2})$ -\end_inset - - may actually be -\begin_inset Formula $\Phi(q=M_{2}/M_{1})$ -\end_inset - - in which case it depends on -\begin_inset Formula $M_{1}$ -\end_inset - -) but the assumption we make is that -\begin_inset Formula $p_{i}$ -\end_inset - - is separable. - Note that -\begin_inset Formula $\sum p_{i}$ -\end_inset - - must add to one, i.e. - -\begin_inset Formula $\int p\, dV=1$ -\end_inset - -. - In general, each of the distributions must also satisfy -\begin_inset Formula $\int\Psi(M_{1})dM_{1}=\int\Psi(M_{2})dM_{2}=\int\chi(a)da=1$ -\end_inset - - where the integrals are from -\begin_inset Formula $-\infty$ -\end_inset - - to -\begin_inset Formula $+\infty$ -\end_inset - -. -\end_layout - -\begin_layout Standard -There are many forms for each initial distributions and they depend on which - authors you believe and/or which stars you are looking at (e.g. - low- or high-mass stars). - There is no one true answer -- yet! Below are sketched the options -\emph on -IMF.pm -\emph default - provides for you. -\end_layout - -\begin_layout Subsection -Definitions -\end_layout - -\begin_layout Standard -In what follows, if code variables are references they are in -\family typewriter -typewriter -\family default - font and usually stored in the -\family typewriter -%binary_grid::grid_options -\family default - hash. -\end_layout - -\begin_layout Subsection -Setup -\end_layout - -\begin_layout Standard -\begin_inset CommandInset label -LatexCommand label -name "sub:init_IMF" - -\end_inset - -To set up your initial distribution you must call the -\family typewriter -init_IMF -\family default - function, although this is usually done for you in the -\family typewriter -grid() -\family default - function. - An example call is the following, note that the arguments must be in the - correct order so it is best to copy-paste the function call: -\begin_inset Newline newline -\end_inset - - -\end_layout - -\begin_layout Standard - -\family typewriter -# initialise IMF parameters -\end_layout - -\begin_layout Standard - -\family typewriter -init_IMF($binary_grid::grid_options{'imf1'}, -\end_layout - -\begin_layout Standard - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -$binary_grid::grid_options{'imf2'}, -\end_layout - -\begin_layout Standard - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -$binary_grid::grid_options{'sepdist'}, -\end_layout - -\begin_layout Standard - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -$binary_grid::grid_options{'plaw_m0'}, -\end_layout - -\begin_layout Standard - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -$binary_grid::grid_options{'plaw_m1'}, -\end_layout - -\begin_layout Standard - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -$binary_grid::grid_options{'plaw_m2'}, -\end_layout - -\begin_layout Standard - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -$binary_grid::grid_options{'plaw_mmax'}, -\end_layout - -\begin_layout Standard - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -$binary_grid::grid_options{'plaw_p1'}, -\end_layout - -\begin_layout Standard - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -$binary_grid::grid_options{'plaw_p2'}, -\end_layout - -\begin_layout Standard - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -$binary_grid::grid_options{'plaw_p3'}, -\end_layout - -\begin_layout Standard - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -$binary_grid::grid_options{'plaw_p'}, -\end_layout - -\begin_layout Standard - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -$binary_grid::grid_options{'sepdist_min'}, -\end_layout - -\begin_layout Standard - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -$binary_grid::grid_options{'sepdist_max'}, -\end_layout - -\begin_layout Standard - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -$binary_grid::grid_options{'log_normal_median'}, -\end_layout - -\begin_layout Standard - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -$binary_grid::grid_options{'log_normal_dispersion'} -\end_layout - -\begin_layout Standard - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -); -\end_layout - -\begin_layout Subsection -Initial Mass Function -\end_layout - -\begin_layout Standard -\begin_inset CommandInset label -LatexCommand label -name "sub:IMF" - -\end_inset - -The initial mass function governs single-star masses, -\begin_inset Formula $M$ -\end_inset - -, or primary-star masses in binary systems, -\begin_inset Formula $M_{1}$ -\end_inset - -. - It is usually represented by a power law or a multi-part power law. - You have the following options for -\family typewriter -$binary_grid::grid_options{'imf1'} -\family default -: -\end_layout - -\begin_layout Description -ktg93 The default IMF is that of -\begin_inset CommandInset citation -LatexCommand citet -key "KTG1993MNRAS-262-545K" - -\end_inset - -. - It is a three-part power law. - The mass breaks and slopes are specified in the -\family typewriter -%grid_options -\family default - with keys -\family typewriter -plaw_m0 -\family default -, -\family typewriter -plaw_m1 -\family default -, -\family typewriter -plaw_m2 -\family default -, -\family typewriter -plaw_mmax -\family default -, -\family typewriter -plaw_p1 -\family default -, -\family typewriter -plaw_p2 -\family default - and -\family typewriter -plaw_p3 -\family default -. -\end_layout - -\begin_layout Description -plaw Single power law function, slope given by -\family typewriter -plaw_p -\family default -, mass limits -\family typewriter -plaw_m0 -\family default - and -\family typewriter -plaw_mmax -\family default -. - You could use this for the -\begin_inset CommandInset citation -LatexCommand citet -key "1955ApJ...121..161S" - -\end_inset - - mass function. -\end_layout - -\begin_layout Description -chabrier The IMF of -\begin_inset CommandInset citation -LatexCommand citet -key "2003PASP..115..763C" - -\end_inset - -. -\end_layout - -\begin_layout Description -tinsley1980 The IMF of -\begin_inset CommandInset citation -LatexCommand citet -key "1980FCPh....5..287T" - -\end_inset - - which is a broken power law with mass breaks at -\begin_inset Formula $2$ -\end_inset - - and -\begin_inset Formula $10\,\mathrm{M}_{\odot}$ -\end_inset - -, slopes -\begin_inset Formula $-2$ -\end_inset - -, -\begin_inset Formula $-2.3$ -\end_inset - - and -\begin_inset Formula $-3.3$ -\end_inset - -. -\end_layout - -\begin_layout Description -scalo1986 The IMF of -\begin_inset CommandInset citation -LatexCommand citet -key "1986FCPh...11....1S" - -\end_inset - - which is a broken power law with mass breaks at -\begin_inset Formula $1$ -\end_inset - - and -\begin_inset Formula $10\,\mathrm{M_{\odot}}$ -\end_inset - -, slopes -\begin_inset Formula $-2.35$ -\end_inset - -, -\begin_inset Formula $-2.35$ -\end_inset - - and and -\begin_inset Formula $-2.7$ -\end_inset - -. -\end_layout - -\begin_layout Description -lognormal An IMF using a log-normal distribution (i.e. - a Gaussian of -\begin_inset Formula $\log M$ -\end_inset - -). -\end_layout - -\begin_layout Description -1 A constant IMF is used with a value -\begin_inset Formula $1.0$ -\end_inset - -, useful for testing other distributions. -\end_layout - -\begin_layout Subsection -Secondary star mass function -\end_layout - -\begin_layout Standard -\begin_inset CommandInset label -LatexCommand label -name "sub:q-dist" - -\end_inset - -In the following: -\end_layout - -\begin_layout Itemize -\begin_inset Formula $q_{\mbox{min}}=M_{2}/0.1\,\mbox{M}_{\odot}$ -\end_inset - - unless -\family typewriter -imf2_minq -\family default - is defined, in which case the given value is used. -\end_layout - -\begin_layout Standard -Your options for -\family typewriter -$binary_grid::grid_options{'imf2'} -\family default - are the following: -\end_layout - -\begin_layout Description -flatq The default, a distribution flat in -\begin_inset Formula $q=M_{2}/M_{1}$ -\end_inset - - (where -\begin_inset Formula $q\leq1$ -\end_inset - -) between -\begin_inset Formula $q_{\mbox{min}}$ -\end_inset - - and -\begin_inset Formula $1$ -\end_inset - - (the lower limit is necessary otherwise you will make planets). -\end_layout - -\begin_layout Description -ktg93 This chooses -\begin_inset Formula $M_{2}$ -\end_inset - - from the -\begin_inset CommandInset citation -LatexCommand citet -key "KTG1993MNRAS-262-545K" - -\end_inset - - IMF, -\emph on - independent of -\begin_inset Formula $M_{1}$ -\end_inset - -. -\end_layout - -\begin_layout Description -imf1 This uses the same IMF as for star -\begin_inset Formula $1$ -\end_inset - -. - Not recommended! -\end_layout - -\begin_layout Description -plawm This applies a power law between -\family typewriter -imf2_mmin -\family default - and -\family typewriter -imf2_mmax -\family default - (or -\begin_inset Formula $M_{1}$ -\end_inset - - if -\family typewriter -imf2_mmax='auto' -\family default -), of slope -\family typewriter -imf2_exponent -\family default -. -\end_layout - -\begin_layout Description -plawq This applies a power law in -\begin_inset Formula $q$ -\end_inset - - between -\begin_inset Formula $q_{\mbox{min}}$ -\end_inset - - and -\family typewriter -imf2_maxq -\family default -. -\end_layout - -\begin_layout Description -gaussian A Gaussian distribution in -\begin_inset Formula $q$ -\end_inset - - between -\begin_inset Formula $q_{\mbox{min}}$ -\end_inset - - and -\family typewriter -imf2_maxq -\family default -. - Mean is -\family typewriter -q_mean -\family default -, width is -\family typewriter -q_sigma -\family default -. -\end_layout - -\begin_layout Subsection -Separation distribution -\end_layout - -\begin_layout Standard -\begin_inset CommandInset label -LatexCommand label -name "sub:sep-dist" - -\end_inset - -You have only two options for -\family typewriter -$binary_grid::grid_options{'sepdist'} -\family default -: -\end_layout - -\begin_layout Description -flat The default, a flat distribution in -\begin_inset Formula $\ln a$ -\end_inset - - between -\family typewriter -sepdist_min -\family default - and -\family typewriter -sepdist_max -\end_layout - -\begin_layout Description -plaw A power law between -\family typewriter -sepdist_min -\family default - and -\family typewriter -sepdist_max -\family default - with slope -\family typewriter -sepdist_exponent -\end_layout - -\begin_layout Standard -Should you instead wish to use a -\emph on -period -\emph default - distribution, you have to use ' -\family typewriter -period -\family default -' for your separation distribution. -\end_layout - -\begin_layout Subsection -Period distribution -\end_layout - -\begin_layout Standard -\begin_inset CommandInset label -LatexCommand label -name "sub:period-dist" - -\end_inset - -If you wish to use the period rather than the separation to define your - binary-star initial distribution, you have to set ' -\family typewriter -period -\family default -' into the -\family typewriter -sepdist -\family default - option. - Currently only the option of a Gaussian distribution is available (c.f. - -\begin_inset CommandInset citation -LatexCommand citealp -key "1991A&A...248..485D" - -\end_inset - -) between (log) period limits -\family typewriter -period_dist_log_min -\family default - and -\family typewriter -period_dist_log_max -\family default -. - -\end_layout - -\begin_layout Standard -The mean is given by -\family typewriter -period_dist_mean_log -\family default - and dispersion by -\family typewriter -period_dist_sigma -\family default -. -\end_layout - -\begin_layout Standard -\begin_inset Newpage pagebreak -\end_inset - - -\end_layout - -\begin_layout Section -Debugging options -\end_layout - -\begin_layout Standard -\begin_inset CommandInset label -LatexCommand label -name "sec:debugging" - -\end_inset - -This section provides a summary of debugging options and suggestions for - ways to fix your code (or -\emph on -binary_grid -\emph default -!). - -\end_layout - -\begin_layout Itemize - -\family typewriter -$binary_grid::grid_options{'vb'} -\family default - controls the amount of grid output to the screen, usually lines showing - the number of stars evolved, the total number in the grid, the current - time, -\begin_inset Formula $M_{1}$ -\end_inset - -, -\begin_inset Formula $M_{2}$ -\end_inset - -, -\begin_inset Formula $a$ -\end_inset - -, -\begin_inset Formula $P$ -\end_inset - - and -\begin_inset Formula $Z$ -\end_inset - -, the probability, the total grid probability, -\begin_inset Formula $\%$ -\end_inset - - grid completion, estimated time until arrival (finish) i.e. - -\emph on -ETA -\emph default -, -\emph on -tpr -\emph default - (time per run), ETF (estimated time at which it will finish) and memory - usage. - If set to 1 it shows output every second or every -\family typewriter -$binary_grid::grid_options{'nmod'} -\family default - models. - If -\family typewriter -vb -\family default - is set to -\family typewriter -2 -\family default - then more output, showing the arguments sent to -\emph on -binary_c/nucsyn -\emph default -, will be dumped onto the screen for each model. - This is only useful for small grids, for large grids it will overwhelm - you. - It is possible to set -\family typewriter -vb=3 -\family default - but this is experimental. -\end_layout - -\begin_layout Itemize - -\family typewriter -$binary_grid::grid_options{'log_args'} -\family default - will output the arguments sent to -\emph on -binary_c/nucsyn -\emph default - in files in -\family typewriter -/tmp/ -\family default -. - In unthreaded grids these go in -\family typewriter -/tmp/binary_c.lastargs -\family default - while in threaded grids -\family typewriter -/tmp/binary_c.thread_$n.lastargs -\family default - where -\family typewriter -$n -\family default - is the thread number. - This is a more practical approach to debugging individual systems in large - grids than -\family typewriter -vb=2 -\family default -. - It is also useful in the case where your code freezes, because as long - as the code is frozen you can access the final model (for each thread) - in the files and then rerun them with -\family typewriter -tbse -\family default - to see where it went wrong. -\end_layout - -\begin_layout Itemize - -\family typewriter -$binary_grid::grid_options{'args'} -\family default - stores a single string with the raw arguments that were passed into -\emph on -binary_c/nucsyn -\emph default -. - This is useful if you want to do some debugging in the parse_bse function - (which has access to this variable). -\end_layout - -\begin_layout Itemize - -\family typewriter -$binary_grid::grid_options{'progenitor'} -\family default - stores the progenitor information in a single string, in the following - order: binarity, -\begin_inset Formula $M_{1}$ -\end_inset - -, -\begin_inset Formula $M_{2}$ -\end_inset - -, -\begin_inset Formula $P$ -\end_inset - -, -\begin_inset Formula $a$ -\end_inset - -, -\begin_inset Formula $e$ -\end_inset - -, -\begin_inset Formula $Z$ -\end_inset - -, -\begin_inset Formula $P$ -\end_inset - - and -\begin_inset Formula $\delta\ln V$ -\end_inset - - (the ' -\family typewriter -logphasevol -\family default -'= -\begin_inset Formula $\delta\ln M_{1}\delta\ln M_{2}\delta a$ -\end_inset - -). - If the star is a single star ( -\family roman -binarity -\family typewriter -==0 -\family default -) then -\begin_inset Formula $M_{2}$ -\end_inset - -, -\begin_inset Formula $P$ -\end_inset - -, -\begin_inset Formula $a$ -\end_inset - - and -\begin_inset Formula $e$ -\end_inset - - are omitted and -\begin_inset Formula $\delta\ln V=\delta\ln M$ -\end_inset - -. - This data is accessible from -\family typewriter -parse_bse -\family default -. -\end_layout - -\begin_layout Itemize -The hash-in-a-hash -\family typewriter - -\begin_inset Newline newline -\end_inset - -%binary_grid::grid_options{'progenitor_hash'}{ -\begin_inset Formula $\dots$ -\end_inset - -} -\family default - -\begin_inset Newline newline -\end_inset - -contains the same information as the progenitor string (above) in a more - accessible form: the hash -\emph on -keys -\emph default - are binarity, -\begin_inset Formula $M_{1}$ -\end_inset - -, -\begin_inset Formula $M_{2}$ -\end_inset - -, -\begin_inset Formula $P$ -\end_inset - -, -\begin_inset Formula $a$ -\end_inset - -, -\begin_inset Formula $e$ -\end_inset - -, -\begin_inset Formula $Z$ -\end_inset - -, -\begin_inset Formula $P$ -\end_inset - - and -\begin_inset Formula $\delta\ln V$ -\end_inset - -, and the values contain the appropriate data. - Again, this is accessible from -\family typewriter -parse_bse -\family default -. -\end_layout - -\begin_layout Itemize -Use the -\family typewriter -test_grid -\family default - if you are running a full grid and want to test if your initial distributions - integrate such that -\begin_inset Formula $\sum_{i}p_{i}=1$ -\end_inset - -. -\end_layout - -\begin_layout Itemize -Use the -\family typewriter -timeout -\family default - feature if your code is freezing. - This is -\emph on -not -\emph default - the same as fixing your problem, but you may be able to stop the code from - using all your CPU when it freezes! -\end_layout - -\begin_layout Standard -\begin_inset Newpage pagebreak -\end_inset - - -\end_layout - -\begin_layout Section -Flexigrid -\end_layout - -\begin_layout Standard -\begin_inset CommandInset label -LatexCommand label -name "sec:flexigrid" - -\end_inset - -As of summer 2011, the -\begin_inset Quotes eld -\end_inset - -flexigrid -\begin_inset Quotes erd -\end_inset - - was developed. - This is an attempt to replace much of the old grid framework with a new, - dynamic set of instructions which are much more flexible. - The key concepts are the following: -\end_layout - -\begin_layout Itemize -When a flexigrid is run, it sets up -\begin_inset Formula $n$ -\end_inset - - threads each of which runs a star (or group of stars) at a time. - This is done -\emph on -as soon as a thread is free -\emph default - so load balancing is as good as it is possible to be. -\end_layout - -\begin_layout Itemize -Flexigrid sets up its -\begin_inset Formula $M_{1}-M_{2}-a$ -\end_inset - - etc. - grid -\emph on -dynamically -\emph default -. - It does this by writing the grid code itself and then compiling it with - Perl's -\emph on -eval -\emph default - command. - This means it is truly flexible, you can add or remove -\emph on -any variable you like -\emph default - to the grid and do not have to write any new code in the -\emph on -binary_grid -\emph default - module! -\end_layout - -\begin_layout Itemize -The standard version of flexigrid uses a multithreaded, local binary_c model. - However, in development is a binary_c-daemon which distributes the load - across remote machines on a network. -\end_layout - -\begin_layout Itemize -The grid spacing is now given by a Perl function and hence is -\emph on -not -\emph default - fixed. - -\end_layout - -\begin_layout Itemize -Probabilities are calculated more efficiently in an attempt to phase out - the -\emph on -IMF -\emph default - module in favour of the -\emph on -distribution_functions -\emph default - module. -\end_layout - -\begin_layout Subsection -Setup in your grid script -\end_layout - -\begin_layout Standard -You need to do two things: -\end_layout - -\begin_layout Enumerate -Call -\family typewriter -flexigrid( -\emph on -n -\emph default -); -\family default - instead of -\family typewriter -threaded_grid( -\emph on -n -\emph default -); -\end_layout - -\begin_layout Enumerate -Set up the grid in the -\family typewriter -grid_options -\family default -hash -\end_layout - -\begin_layout Standard -The call to -\family typewriter -flexigrid -\family default - is simple enough, where the argument is (as with -\family typewriter -threaded_grid -\family default -) the number of threads. - Next, some variables must be set in the grid_options hash in order that - the grid can be created. -\end_layout - -\begin_layout Subsubsection -Grid variables: 1D example -\end_layout - -\begin_layout Standard -Setting up which variables you use is best defined by example. - Let's start with -\begin_inset Formula $M_{1}$ -\end_inset - - which you will usually require. - First, define the grid resolution as $n -\begin_inset Formula $\times$ -\end_inset - -$n -\begin_inset Formula $\times$ -\end_inset - -$n (here -\begin_inset Formula $10\times10\times10$ -\end_inset - -) -\end_layout - -\begin_layout Standard - -\family typewriter -$n=10; -\family default - -\begin_inset Newline newline -\end_inset - -Next, set up the variable number corresponding to the grid variable. - Each grid variable must have a unique number, starting with 0 and working - upward. - -\end_layout - -\begin_layout Standard - -\family typewriter -my $nvar=0; -\family default - -\begin_inset Newline newline -\end_inset - -Set up IMF options: -\end_layout - -\begin_layout Standard - -\family typewriter -\begin_inset Box Frameless -position "t" -hor_pos "c" -has_inner_box 1 -inner_pos "t" -use_parbox 0 -use_makebox 0 -width "100col%" -special "none" -height "1in" -height_special "totalheight" -status open - -\begin_layout Plain Layout - -\family typewriter -my $ktgopts=join(',', -\end_layout - -\begin_layout Plain Layout - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -$binary_grid::grid_options{'plaw_m0'}, -\end_layout - -\begin_layout Plain Layout - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -$binary_grid::grid_options{'plaw_m1'}, -\end_layout - -\begin_layout Plain Layout - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -$binary_grid::grid_options{'plaw_m2'}, -\end_layout - -\begin_layout Plain Layout - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -$binary_grid::grid_options{'plaw_mmax'}, -\end_layout - -\begin_layout Plain Layout - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -$binary_grid::grid_options{'plaw_p1'}, -\end_layout - -\begin_layout Plain Layout - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -$binary_grid::grid_options{'plaw_p2'}, -\end_layout - -\begin_layout Plain Layout - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -$binary_grid::grid_options{'plaw_p3'}); -\end_layout - -\end_inset - - -\end_layout - -\begin_layout Standard -(These are required for the -\emph on -ktg93 -\emph default - function in the -\emph on -distribution_functions -\emph default - module.) -\begin_inset Newline newline -\end_inset - -Now use an -\emph on -anonymous hash -\emph default - in the grid option {'flexigrid'}{'grid variable '.$nvar} to give the options: -\begin_inset Newline newline -\end_inset - - -\end_layout - -\begin_layout Standard - -\family typewriter -\begin_inset Box Frameless -position "t" -hor_pos "c" -has_inner_box 1 -inner_pos "t" -use_parbox 0 -use_makebox 0 -width "100col%" -special "none" -height "1in" -height_special "totalheight" -status open - -\begin_layout Plain Layout - -\family typewriter -# Mass 1 -\end_layout - -\begin_layout Plain Layout - -\family typewriter -$binary_grid::grid_options{'flexigrid'}{'grid variable '.$nvar++}= -\end_layout - -\begin_layout Plain Layout - -\family typewriter -{ -\end_layout - -\begin_layout Plain Layout - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -'name'=>'lnm1', -\end_layout - -\begin_layout Plain Layout - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -'longname'=>'Primary_Mass', -\end_layout - -\begin_layout Plain Layout - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -'range' => ["log($binary_grid::grid_options{'mmin'})", -\end_layout - -\begin_layout Plain Layout - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -"log($binary_grid::grid_options{'mmax'})"], -\end_layout - -\begin_layout Plain Layout - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -'resolution'=>$n, -\end_layout - -\begin_layout Plain Layout - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -'spacingfunc'=>"const(log($binary_grid::grid_options{'mmin'}),log($binary_grid:: -grid_options{'mmax'}),$n)", -\end_layout - -\begin_layout Plain Layout - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -'precode'=>"my -\backslash -$m1=exp( -\backslash -$lnm1);my -\backslash -$eccentricity=0.0;", -\end_layout - -\begin_layout Plain Layout - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -'probdist'=>"ktg93( -\backslash -$m1,$ktgopts)* -\backslash -$m1", -\end_layout - -\begin_layout Plain Layout - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -'dphasevol'=>" -\backslash -$dlnm1 " -\end_layout - -\begin_layout Plain Layout - -\family typewriter -}; -\end_layout - -\begin_layout Plain Layout - -\end_layout - -\end_inset - - -\family default -(Note the -\family typewriter -++ -\family default - after -\family typewriter -$nvar -\family default - which raises the variable number for the next variable. -\family typewriter -) -\begin_inset Newline newline -\end_inset - - -\end_layout - -\begin_layout Standard -What does this mean? -\end_layout - -\begin_layout Labeling -\labelwidthstring 00.00.0000 -name -\begin_inset space ~ -\end_inset - - -\emph on -string -\emph default - This is the variable name. - It should be parsable in Perl, e.g. - in the above case it is expanded to -\family typewriter -$lnm1 -\family default - in the gridcode. -\end_layout - -\begin_layout Labeling -\labelwidthstring 00.00.0000 -longname -\begin_inset space ~ -\end_inset - - -\emph on -string -\emph default - This is a long (human-readable) name used in logging. - It should contain no spaces (use underscores). -\end_layout - -\begin_layout Labeling -\labelwidthstring 00.00.0000 -range -\begin_inset space ~ -\end_inset - - -\emph on -x -\emph default - -\begin_inset space ~ -\end_inset - - -\emph on -y -\emph default - This defines the range of the grid, from -\emph on -x -\emph default - to -\emph on -y. - -\emph default - In the above case from -\family typewriter -log(0.1) -\family default - to -\family typewriter -log(80.0) -\family default -. - (We are using a grid in -\emph on -log -\emph default - -\begin_inset Formula $M_{1}$ -\end_inset - -.) Note that this is an -\emph on -anonymous array -\emph default -. - which must be declared with -\family typewriter -[ -\emph on -min -\emph default -, -\emph on -max -\emph default -] -\family default -. -\end_layout - -\begin_layout Labeling -\labelwidthstring 00.00.0000 -resolution -\begin_inset space ~ -\end_inset - - -\emph on -n -\emph default -This is the grid resolution, given above by -\family typewriter -$n -\family default -. -\end_layout - -\begin_layout Labeling -\labelwidthstring 00.00.0000 -spacingfunc -\begin_inset space ~ -\end_inset - - -\emph on -func -\emph default -This defines the spacing function which should be in the -\emph on -spacing_functions -\emph default - Perl module. - In the above example the spacing is constant between -\family typewriter -log(0.1) -\family default -and -\family typewriter - log(80.0) -\family default -with -\family typewriter - $n -\family default -steps. -\end_layout - -\begin_layout Labeling -\labelwidthstring 00.00.0000 -precode -\begin_inset space ~ -\end_inset - - -\emph on -code -\emph default -This is code executed before the next part of the grid is set up. - In our case we have to specify -\family typewriter -$m1 -\family default - because we have only calculated -\family typewriter -$lnm1 -\family default -. - We also set up the eccentricity because there is no grid for this and it - is required. - -\end_layout - -\begin_layout Labeling -\labelwidthstring 00.00.0000 -postcode -\begin_inset space ~ -\end_inset - - -\emph on -code -\emph default -This is code executed after the next part of the grid is set up. - (In our case there is no -\emph on -postcode -\emph default -). -\end_layout - -\begin_layout Labeling -\labelwidthstring 00.00.0000 -probdist -\begin_inset space ~ -\end_inset - - -\emph on -func -\emph default -This is a probability distribution function as given in the -\emph on -distribution_functions -\emph default - Perl module. - In the above we use the -\family typewriter -ktg93 -\family default - (Kroupa, Tout, Gilmore 1993 IMF) function. - -\end_layout - -\begin_layout Labeling -\labelwidthstring 00.00.0000 -dphasevol -\begin_inset space ~ -\end_inset - - -\emph on -expression -\emph default -This defines the contribution to the phase volume from this variable. - In general this is just -\family typewriter -$dlnm1 -\family default - (i.e. - should be -\family typewriter -$d -\emph on -name -\family default -\emph default -) but you can set it to whatever you like. - -\end_layout - -\begin_layout Subsection -3D grid example -\end_layout - -\begin_layout Standard -The next step is to set up the further grid variables. - Usually these are -\begin_inset Formula $M_{2}$ -\end_inset - - and -\begin_inset Formula $a$ -\end_inset - -, as defined in the code below. -\end_layout - -\begin_layout Standard - -\family typewriter -\begin_inset Box Frameless -position "t" -hor_pos "c" -has_inner_box 1 -inner_pos "t" -use_parbox 0 -use_makebox 0 -width "100col%" -special "none" -height "1in" -height_special "totalheight" -status open - -\begin_layout Plain Layout - -\family typewriter -# Binary stars: Mass 2 and Separation -\end_layout - -\begin_layout Plain Layout - -\family typewriter -if($binary_grid::grid_options{'binary'}) -\end_layout - -\begin_layout Plain Layout - -\family typewriter -{ -\end_layout - -\begin_layout Plain Layout - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -$binary_grid::grid_options{'flexigrid'}{'grid variable '.$nvar++}= -\end_layout - -\begin_layout Plain Layout - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -{ -\end_layout - -\begin_layout Plain Layout - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -'name'=>'m2', -\end_layout - -\begin_layout Plain Layout - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -'longname'=>'Secondary_mass', -\end_layout - -\begin_layout Plain Layout - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -'range'=>[$binary_grid::grid_options{'m2min'},'$m1'], -\end_layout - -\begin_layout Plain Layout - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -'resolution'=>$n, -\end_layout - -\begin_layout Plain Layout - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -'spacingfunc'=>"const($binary_grid::grid_options{'m2min'}, -\backslash -$m1,$n)", -\end_layout - -\begin_layout Plain Layout - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -'probdist'=>"const($binary_grid::grid_options{'m2min'}, -\backslash -$m1)", -\end_layout - -\begin_layout Plain Layout - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -'dphasevol','$dm2' -\end_layout - -\begin_layout Plain Layout - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -}; -\end_layout - -\begin_layout Plain Layout - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -$binary_grid::grid_options{'flexigrid'}{'grid variable '.$nvar++}= -\end_layout - -\begin_layout Plain Layout - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -{ -\end_layout - -\begin_layout Plain Layout - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -'name'=>'lnsep', -\end_layout - -\begin_layout Plain Layout - -\family typewriter -'longname'=>'ln(Orbital_Separation)', -\end_layout - -\begin_layout Plain Layout - -\family typewriter -'range'=>['log(3.0)','log(1e4)'], -\end_layout - -\begin_layout Plain Layout - -\family typewriter -'resolution',$n, -\end_layout - -\begin_layout Plain Layout - -\family typewriter -'spacingfunc',"const(log(3.0),log(1e4),$n)", -\end_layout - -\begin_layout Plain Layout - -\family typewriter -'precode'=>"my -\backslash -$sep=exp( -\backslash -$lnsep);my -\backslash -$per=calc_period_from_sep( -\backslash -$m1, -\backslash -$m2, -\backslash -$sep);", -\end_layout - -\begin_layout Plain Layout - -\family typewriter -'probdist'=>'const(log(3.0),log(1e4))', -\end_layout - -\begin_layout Plain Layout - -\family typewriter -'dphasevol'=>'$dlnsep' -\end_layout - -\begin_layout Plain Layout - -\family typewriter -} -\end_layout - -\begin_layout Plain Layout - -\family typewriter -} -\end_layout - -\end_inset - - -\end_layout - -\begin_layout Standard -The above setup has the same general form as for -\begin_inset Formula $M_{1}$ -\end_inset - - but with different spacing functions (the -\emph on -const -\emph default - spacing function is used, for -\begin_inset Formula $M_{2}$ -\end_inset - - in the range -\begin_inset Formula $0.1$ -\end_inset - - to -\begin_inset Formula $M_{1}$ -\end_inset - - and for -\begin_inset Formula $\ln a$ -\end_inset - - in the range -\begin_inset Formula $3$ -\end_inset - - to -\begin_inset Formula $10^{4}$ -\end_inset - -). -\end_layout - -\begin_layout Subsection -Gridcode -\end_layout - -\begin_layout Standard -The complete example from the above is -\begin_inset Newline newline -\end_inset - - -\begin_inset Newline newline -\end_inset - - -\begin_inset Box Frameless -position "t" -hor_pos "c" -has_inner_box 1 -inner_pos "t" -use_parbox 0 -use_makebox 0 -width "100col%" -special "none" -height "1in" -height_special "totalheight" -status open - -\begin_layout Plain Layout - -\family typewriter -$n=10; # grid resolution -\begin_inset Newline newline -\end_inset - -my $nvar=0; # variable number -\begin_inset Newline newline -\end_inset - -# set up IMF options -\end_layout - -\begin_layout Plain Layout - -\family typewriter -my $ktgopts=join(',', -\end_layout - -\begin_layout Plain Layout - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -$binary_grid::grid_options{'plaw_m0'}, -\end_layout - -\begin_layout Plain Layout - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -$binary_grid::grid_options{'plaw_m1'}, -\end_layout - -\begin_layout Plain Layout - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -$binary_grid::grid_options{'plaw_m2'}, -\end_layout - -\begin_layout Plain Layout - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -$binary_grid::grid_options{'plaw_mmax'}, -\end_layout - -\begin_layout Plain Layout - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -$binary_grid::grid_options{'plaw_p1'}, -\end_layout - -\begin_layout Plain Layout - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -$binary_grid::grid_options{'plaw_p2'}, -\end_layout - -\begin_layout Plain Layout - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -$binary_grid::grid_options{'plaw_p3'}); -\end_layout - -\begin_layout Plain Layout - -\family typewriter -# Mass 1 -\end_layout - -\begin_layout Plain Layout - -\family typewriter -$binary_grid::grid_options{'flexigrid'}{'grid variable '.$nvar++}= -\end_layout - -\begin_layout Plain Layout - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -"name lnm1 longname Primary_Mass range log(0.1) log(80.0) resolution $n spacingfun -c const(log(0.1),log(80.0),$n) precode my -\backslash -$m1=exp( -\backslash -$lnm1);my -\backslash -$eccentricity=0.0; probdist ktg93( -\backslash -$m1,$ktgopts) dphasevol -\backslash -$dlnm1 "; -\end_layout - -\begin_layout Plain Layout - -\family typewriter -# Binary stars: Mass 2 and Separation -\end_layout - -\begin_layout Plain Layout - -\family typewriter -if($binary_grid::grid_options{'binary'}) -\end_layout - -\begin_layout Plain Layout - -\family typewriter -{ -\end_layout - -\begin_layout Plain Layout - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -$binary_grid::grid_options{'flexigrid'}{'grid variable '.$nvar++}= -\end_layout - -\begin_layout Plain Layout - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -"name m2 longname Secondary_mass range 0.1 -\backslash -$m1 resolution $n spacingfunc const(0.1, -\backslash -$m1,$n) probdist const(0.1/ -\backslash -$m1,1.0) dphasevol -\backslash -$dm2 "; -\end_layout - -\begin_layout Plain Layout - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -$binary_grid::grid_options{'flexigrid'}{'grid variable '.$nvar++}= -\end_layout - -\begin_layout Plain Layout - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -"name lnsep longname ln(Orbital_Separation) range log(3.0) log(1e4) resolution - $n spacingfunc const(log(3.0),log(1e4),$n) precode my -\backslash -$sep=exp( -\backslash -$lnsep);my -\backslash -$per=calc_period_from_sep( -\backslash -$m1, -\backslash -$m2, -\backslash -$sep); probdist const(log(3.0),log(1e4)) dphasevol -\backslash -$dlnsep "; -\end_layout - -\begin_layout Plain Layout - -\family typewriter -} -\end_layout - -\end_inset - - -\begin_inset Newline newline -\end_inset - -When you run -\family typewriter -flexigrid(2); -\family default - in your grid script, a (flexi)grid with two threads will be run. - You can find the code that is constructed by the -\emph on -binary_grid -\emph default - module in the file -\family typewriter -/tmp/gridcode -\family default - (view it with -\emph on -less -\emph default - or some other tool that can parse ANSI colours, or set -\family typewriter -$binary_grid::grid_options{'colour'}=0; -\family default -). -\end_layout - -\begin_layout Subsection -Technical details -\end_layout - -\begin_layout Standard -This code is, of course, still under development. - Please use it with care! -\end_layout - -\begin_layout Itemize -I have replaced calls to tbse with calls to run_binary_c which is a more - flexible function (and will be used by the binary_c daemon once the remote-mach -ine version is complete). -\end_layout - -\begin_layout Itemize -$starcount should equal the number of stars run on the grid. - -\end_layout - -\begin_layout Itemize -@starcount stores the number of stars run in each subgrid. -\end_layout - -\begin_layout Itemize -The array @prob stores the contribution to the probability from each variable - separately (except the final variable, for which $prob is calculated). - This assumes, as always, that the probability density functions are separable. -\end_layout - -\begin_layout Standard -\begin_inset Newpage pagebreak -\end_inset - - -\end_layout - -\begin_layout Section -Future Plans -\end_layout - -\begin_layout Standard -\begin_inset CommandInset label -LatexCommand label -name "sec:future-plans" - -\end_inset - - -\end_layout - -\begin_layout Itemize -The period and separation grid functions could be extended to include other - distributions. -\end_layout - -\begin_layout Itemize -A graphical frontend would be good! -\end_layout - -\begin_layout Itemize -There once was an adaptive grid which zoomed into areas of special interest, - should this be resurrected? -\end_layout - -\begin_layout Standard -\begin_inset Newpage pagebreak -\end_inset - - -\end_layout - -\begin_layout Section -FAQ -\end_layout - -\begin_layout Standard -\begin_inset CommandInset label -LatexCommand label -name "sec:FAQ" - -\end_inset - - -\end_layout - -\begin_layout Description -Why -\begin_inset space ~ -\end_inset - -not -\begin_inset space ~ -\end_inset - -Monte -\begin_inset space ~ -\end_inset - -Carlo? The alternative to running a grid is a Monte Carlo method, where - you throw systems in according to some initial distribution and a random - number generator. - In the high number limit this should give the -\emph on -same -\emph default - -\emph on -result -\emph default -as a grid. - However, in the low-number limit, the results are probably going to be - different, and this is when you test your code. - The big advantage of a grid is that you have a good handle on -\emph on -errors -\emph default - due to the finite resolution of your sampling of the initial distribution(s) - without the smearing out of a Monte Carlo approach. - Furthermore, MC may accidentally miss part of the initial parameter space - (it is, after all, random) which you know is covered by a grid approach - (at least to within a known error e.g. - -\begin_inset Formula $\delta\ln M_{1}$ -\end_inset - -). - You are also guaranteed, on a grid, to sample even the rare systems which - would be sparsely populated (if at all) in an MC simulation. - Such systems will have a small probability per star, -\begin_inset Formula $p_{i}$ -\end_inset - -, but on the other hand these might be the systems of particular interest - to you! -\end_layout - -\begin_layout Description -Why -\begin_inset space ~ -\end_inset - -MC -\begin_inset space ~ -\end_inset - -SN -\begin_inset space ~ -\end_inset - -kicks? Traditionally supernova (and white dwarf) kicks have had their velocity - chosen in a Monte-Carlo way, rather than on a grid. - This was left as-is because there are four dimensions for each kick, which - -- given a coarse grid of -\begin_inset Formula $10\times10\times10\times10$ -\end_inset - - -- means the parameter space expands by a factor of -\begin_inset Formula $1,\,000$ -\end_inset - - for stars with kicks. - The runtime increase is not worth the effort as in order to finish anything - in your lifetime you would have to either buy a supercomputer or run such - a coarse grid in the original parameters that the whole exercise becomes - pointless. - The brute force resolution test is what you need here: just keep increasing - the resolution until the numbers converge. - It helps if you are clever about it: if you're interested in supernovae - only then -\begin_inset Formula $M_{1}$ -\end_inset - - is probably the dimension that requires the most resolution, or perhaps - -\begin_inset Formula $M_{2}$ -\end_inset - -, but probably not -\begin_inset Formula $a$ -\end_inset - -. -\end_layout - -\begin_layout Description -Zombie -\begin_inset space ~ -\end_inset - -binary_c -\begin_inset space ~ -\end_inset - -processes When the grid exits abnormally, or is killed, a -\emph on -binary_c/nucsyn -\emph default - process may be left behind in an infinite loop state and as such will take - up your precious CPU time. - You will have to kill it manually -\emph on -if you are sure it is not doing anything with another grid process! -\emph default -(Be careful and do -\emph on -not -\emph default - do -\begin_inset Quotes eld -\end_inset - -killall binary_c -\begin_inset Quotes erd -\end_inset - - as root\SpecialChar \ldots{} -) -\end_layout - -\begin_layout Description -Zombie -\begin_inset space ~ -\end_inset - -Perl -\begin_inset space ~ -\end_inset - -processes These should die naturally when the grid finishes and the Perl - script exits. - They are harmless and have never been seen to consume CPU time. -\end_layout - -\begin_layout Standard -\begin_inset Newpage pagebreak -\end_inset - - -\end_layout - -\begin_layout Section -Threaded grids -\end_layout - -\begin_layout Standard - -\emph on -This section is deprecated. - You should use the flexigrid as described above in Section -\begin_inset space ~ -\end_inset - - -\begin_inset CommandInset ref -LatexCommand ref -reference "sec:flexigrid" - -\end_inset - - -\end_layout - -\begin_layout Standard -\begin_inset CommandInset label -LatexCommand label -name "sec:threads" - -\end_inset - -When -\emph on -binary_grid -\emph default - was originally developed, multi-core CPUs were unheard of and multi-CPU - systems rare. - However, these days they are common, so a simple technique was developed - to make the grid function on multi-CPU/core systems. - The grid over single-star masses, -\begin_inset Formula $M$ -\end_inset - -, or primary-star masses, -\begin_inset Formula $M_{1}$ -\end_inset - -, is now split into chunks and each chunk given to a CPU via a native Perl - -\begin_inset Quotes eld -\end_inset - -thread -\begin_inset Quotes erd -\end_inset - - (see e.g. - -\begin_inset Flex URL -status collapsed - -\begin_layout Plain Layout - -http://search.cpan.org/~jdhedden/threads-1.79/lib/threads.pm -\end_layout - -\end_inset - -, you will need to have a thread-capable Perl and install the -\family typewriter -threads-shared -\family default - module). - The difficult trick is to make the chunks equal in runtime and to perform - the accounting when -\begin_inset Quotes eld -\end_inset - -joining -\begin_inset Quotes erd -\end_inset - - the results of the threads. -\end_layout - -\begin_layout Subsection -The threaded grid -\end_layout - -\begin_layout Standard -\begin_inset CommandInset label -LatexCommand label -name "sub:threaded-grid" - -\end_inset - -From the perspective of the user, only a few things have to change in order - to use a threaded grid. - In -\emph on -grid-xxx.pl -\emph default - you just have to set -\family typewriter -$usethreads=1 -\family default -. - This calls the following code: -\begin_inset Newline newline -\end_inset - - -\end_layout - -\begin_layout Standard - -\family typewriter -if($usethreads) -\end_layout - -\begin_layout Standard - -\family typewriter -{ -\end_layout - -\begin_layout Standard - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -use threads; -\end_layout - -\begin_layout Standard - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -threaded_grid(); -\end_layout - -\begin_layout Standard - -\family typewriter -} -\begin_inset Newline newline -\end_inset - - -\family default - -\begin_inset Newline newline -\end_inset - -The -\family typewriter -threaded_grid -\family default - function takes an argument which is the number of threads. - If no argument is given the number of threads is automatically allocated - (usually from the number of CPUs, if that information is available). - -\end_layout - -\begin_layout Standard -Nothing else needs to change, except that you have to save data in a specific - format in -\family typewriter -parse_bse -\family default - and set up a -\family typewriter -join -\family default - function. - These are described in the following sections. -\end_layout - -\begin_layout Standard -A good example of a threaded grid is provided in the -\emph on -grid-hrd.pl -\emph default - script which was used to make multi-dimensional HR diagrams (also in time - and -\begin_inset Formula $\log g$ -\end_inset - -). - -\end_layout - -\begin_layout Subsection -Setting up your parse_bse -\end_layout - -\begin_layout Standard -\begin_inset CommandInset label -LatexCommand label -name "sub:parse-bse-threads" - -\end_inset - -The -\family typewriter -parse_bse -\family default - function is basically the same as with a single-thread grid, except that - you -\emph on -must -\emph default - save your results in a hash -\family typewriter -%h -\family default -. - Once the thread has run its sub-grid, it sends the results to the join - function (see the next section) which takes the -\family typewriter -%h -\family default - hash and adds it to the global results. -\end_layout - -\begin_layout Standard -The hash -\family typewriter -%h -\family default - can be used to store multi-dimensional data, e.g. - distributions (histograms). - In some cases you'll want to store numbers of stars, something like: -\begin_inset Newline newline -\end_inset - - -\end_layout - -\begin_layout Standard - -\family typewriter -$dtp = $p * $dt; -\end_layout - -\begin_layout Standard - -\family typewriter -$h{'R star'} += $dtp; -\family default - -\begin_inset Newline newline -\end_inset - - -\begin_inset Newline newline -\end_inset - -Perhaps you want to make histograms, e.g. - a luminosity function: -\begin_inset Newline newline -\end_inset - - -\end_layout - -\begin_layout Standard - -\family typewriter -$h{'Luminosity function'}{'10-20'}+=$dtp; -\family default - -\begin_inset Newline newline -\end_inset - - -\begin_inset Newline newline -\end_inset - -Perhaps you want to make histograms at given times: -\begin_inset Newline newline -\end_inset - - -\end_layout - -\begin_layout Standard - -\family typewriter -$h{'Luminosity function'}{'20 Myr'}{'30-40'}+=$dtp; -\family default - -\begin_inset Newline newline -\end_inset - - -\begin_inset Newline newline -\end_inset - - -\end_layout - -\begin_layout Standard -Similarly you can make -\begin_inset Formula $n$ -\end_inset - --dimensional hashes of hashes of hashes (or arrays!). - Perl is good for that. -\end_layout - -\begin_layout Subsection -Joining the results -\end_layout - -\begin_layout Standard -\begin_inset CommandInset label -LatexCommand label -name "sub:thread-join" - -\end_inset - -Once your thread has finished running its stars, it calls the join thread - function. - This is set in your grid-xxx.pl with a line like the following: -\begin_inset Newline newline -\end_inset - - -\end_layout - -\begin_layout Standard - -\family typewriter -$binary_grid::grid_options{'threads_join_function_pointer'}= -\backslash -&join_thread; -\family default - -\begin_inset Newline newline -\end_inset - - -\begin_inset Newline newline -\end_inset - -You have to write join_thread yourself. - It should take a pointer to a hash ( -\family typewriter -%h -\family default - in the thread, which must be dereferenced as -\family typewriter -%$h -\family default - in the join function). - It should look something like the following: -\begin_inset Newline newline -\end_inset - - -\end_layout - -\begin_layout Standard - -\family typewriter -sub join_thread -\end_layout - -\begin_layout Standard - -\family typewriter -{ -\end_layout - -\begin_layout Standard - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -# function which is called when a thread is joined: -\end_layout - -\begin_layout Standard - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -# Note that $h is a hash pointer which is used by binary_c threads -\end_layout - -\begin_layout Standard - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -# to collect data. - It dies when it goes out of scope, probably -\end_layout - -\begin_layout Standard - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -# after this function. -\begin_inset Newline newline -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\end_layout - -\begin_layout Standard - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -my $h=shift; -\begin_inset Newline newline -\end_inset - - -\end_layout - -\begin_layout Standard - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -# save the results -\begin_inset Newline newline -\end_inset - - -\end_layout - -\begin_layout Standard - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -foreach my $k (keys %$h) -\end_layout - -\begin_layout Standard - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -{ -\end_layout - -\begin_layout Standard - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -# add the data from %$h into a global hash -\end_layout - -\begin_layout Standard - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -} -\end_layout - -\begin_layout Standard - -\family typewriter -} -\family default - -\begin_inset Newline newline -\end_inset - - -\begin_inset Newline newline -\end_inset - -At present you will have to determine whether the hash is a simple hash, - hash of hashes, etc. - from the value of the string in -\family typewriter -$k -\family default -. - It may well be possible to automate this process, but so far that level - of sophistication has not proven necessary. - One way to do it may be to prepend the hash keys with a (e.g.) 'scalar', - 'array' or 'hash' string. -\end_layout - -\begin_layout Standard -Once all your threads have finished, control is restored to your -\emph on -grid-xxx.pl -\emph default - script and you can output the results from global hash. -\end_layout - -\begin_layout Subsection -Load balancing -\end_layout - -\begin_layout Standard -\begin_inset CommandInset label -LatexCommand label -name "sub:load-balancing" - -\end_inset - -The other difficulty with running threaded grids is to spread the workload - equally over the different CPUs/cores. - Because the grid is split according to primary/single-star mass -\begin_inset Formula $M_{1}$ -\end_inset - - we really need the workload for a given -\emph on -stellar mass -\emph default -. - There are two methods to doing this. - Both assume that the runtime as a function of -\begin_inset Formula $M_{1}$ -\end_inset - - is representative of the runtime of systems with parameters -\begin_inset Formula $M_{1}$ -\end_inset - -, -\begin_inset Formula $M_{2}$ -\end_inset - - and -\begin_inset Formula $a$ -\end_inset - -, i.e. - that single-star runtimes are representative of binary-star systems with - the same primary mass. - This seems to work well enough for the technique to work. -\end_layout - -\begin_layout Subsubsection -The function approximation -\end_layout - -\begin_layout Standard -You can provide a -\emph on -function -\emph default - which returns the runtime (in arbitrary units) as a function of -\begin_inset Formula $\log_{10}M$ -\end_inset - -. - This is not recommended but if you want to give it a try you can set -\family typewriter - -\begin_inset Newline newline -\end_inset - -$binary_grid::grid_options{'runtime_function_pointer'} -\family default - -\begin_inset Newline newline -\end_inset - -to point to the -\family typewriter -MS_lifetime -\family default - function in -\emph on -binary_grid -\emph default -, or write your own function. - Of course, this function has to be bug-free and accurate for your choice - of input physics. - -\family typewriter -MS_lifetime -\family default - takes into account (roughly) changes in metallicity, but that is all. -\end_layout - -\begin_layout Subsubsection -The timed-run approach -\end_layout - -\begin_layout Standard -The alternative approach is more accurate and takes into account changes - in the physics of your simulation. - To determine the runtime as a function of mass, a number of test models - are run. - The runtimes are put into a table which is then interpolated in order to - find the runtime as a function of mass for any mass. -\end_layout - -\begin_layout Standard -In order to use the timed-run approach, -\emph on -binary_c/nucsyn -\emph default - must be equipped to tell -\emph on -binary_grid -\emph default - the runtime of each star that it evolves. - The most common way to do this is to build in support for the -\family typewriter -RDTSC_TIMER -\family default - (and -\family typewriter -RDTSC_TIMER_PER_SYSTEM -\family default -) in -\family typewriter -code_options.h -\family default -. - This uses the Intel tick counter to tell you how many cycles have passed - for each system that is evolved, the -\begin_inset Quotes eld -\end_inset - -tick count -\begin_inset Quotes erd -\end_inset - -. - On running a single system with tbse you should see something like: -\begin_inset Newline newline -\end_inset - - -\end_layout - -\begin_layout Standard - -\family typewriter -Tick count 275804808, ~ runtime = 0.108842 repeat=1 -\family default - -\begin_inset Newline newline -\end_inset - - -\begin_inset Newline newline -\end_inset - - -\emph on -Binary_grid -\emph default - can use this information to construct a table of runtimes and then interpolate - on this to balance the loads equally across the threads. - Note that -\family typewriter -CPUFREQ -\family default - must be defined (in MHz, usually at code -\emph on -configure -\emph default - time) for a true runtime to be output, otherwise only the -\begin_inset Quotes eld -\end_inset - -tick count -\begin_inset Quotes erd -\end_inset - - will be available. -\end_layout - -\begin_layout Standard -On CPUs other than the Intel-compatibles you will have to use a different - timer. - You could try the virtual timer ( -\family typewriter -CC_TIMER -\family default - in -\family typewriter -code_options.h -\family default -) or write your own code for it (see the code in -\family typewriter -main.c -\family default -). -\end_layout - -\begin_layout Subsection -Thread timeout -\end_layout - -\begin_layout Standard -If a thread should appear to be -\begin_inset Quotes eld -\end_inset - -stuck -\begin_inset Quotes erd -\end_inset - - (i.e. - it contributes no output) after -\begin_inset Newline newline -\end_inset - - -\family typewriter -$binary_grid::grid_options{'thread_max_freeze_time_before_warning'} -\family default - seconds, a warning will be sent to the screen. -\end_layout - -\begin_layout Subsection -Thread flushing -\end_layout - -\begin_layout Standard -If you define a function pointed to by -\family typewriter -$binary_grid::grid_options{'threads_flush_func'} -\family default - this will be called at the end of the run of each thread (the -\begin_inset Quotes eld -\end_inset - -flush -\begin_inset Quotes erd -\end_inset - - stage) with a pointer to the -\family typewriter -%h -\family default - data hash passed as the only argument. -\end_layout - -\begin_layout Standard -\begin_inset Newpage pagebreak -\end_inset - - -\end_layout - -\begin_layout Standard - -\size scriptsize -\begin_inset CommandInset bibtex -LatexCommand bibtex -bibfiles "references" -options "apalike" - -\end_inset - - -\end_layout - -\end_body -\end_document diff --git a/doc/deprecated/binary_grid.lyx b/doc/deprecated/binary_grid.lyx deleted file mode 100644 index 907c1a737192a7203da5934f8f7b704fbb2fb73e..0000000000000000000000000000000000000000 --- a/doc/deprecated/binary_grid.lyx +++ /dev/null @@ -1,10622 +0,0 @@ -#LyX 2.0 created this file. For more info see http://www.lyx.org/ -\lyxformat 413 -\begin_document -\begin_header -\textclass scrartcl -\begin_preamble -\usepackage{eulervm} -% bibliography stuff -\def\aj{Astronomical Journal} % Astronomical Journal -\def\araa{ARA\&A} % Annual Review of Astron and Astrophys -\def\apj{Astrophysical Journal} % Astrophysical Journal -\def\apjl{Astrophysical Journal, Letters} % Astrophysical Journal, Letters -\def\apjs{Astrophysical Journal, Supplement} % Astrophysical Journal, Supplement -\def\apss{Ap\&SS} % Astrophysics and Space Science -\def\aap{Astronomy and Astrophysics} % Astronomy and Astrophysics -\def\aapr{A\&A~Rev.} % Astronomy and Astrophysics Reviews -\def\aaps{A\&AS} % Astronomy and Astrophysics, Supplement -\def\mnras{Monthly Notices of the Royal Astronomical Society} % Monthly Notices of the RAS -\def\pra{Phys.~Rev.~A} % Physical Review A: General Physics -\def\prl{Phys.~Rev.~Lett.} % Physical Review Letters -\def\pasa{PASA} % Publications of the ASP -\def\pasp{PASP} % Publications of the ASP -\def\pasj{PASJ} % Publications of the ASJ -\def\nat{Nature} % Nature -\def\aplett{Astrophys.~Lett.} % Astrophysics Letters -\def\physrep{Phys.~Rep.} % Physics Reports% - - -\usepackage{listings} -\end_preamble -\use_default_options true -\maintain_unincluded_children false -\language british -\language_package default -\inputencoding auto -\fontencoding global -\font_roman default -\font_sans helvet -\font_typewriter beramono -\font_default_family sfdefault -\use_non_tex_fonts false -\font_sc false -\font_osf false -\font_sf_scale 100 -\font_tt_scale 90 - -\graphics default -\default_output_format default -\output_sync 0 -\bibtex_command default -\index_command default -\paperfontsize default -\spacing single -\use_hyperref false -\papersize default -\use_geometry true -\use_amsmath 2 -\use_esint 1 -\use_mhchem 1 -\use_mathdots 1 -\cite_engine natbib_authoryear -\use_bibtopic false -\use_indices false -\paperorientation portrait -\suppress_date false -\use_refstyle 0 -\index Index -\shortcut idx -\color #008000 -\end_index -\leftmargin 2cm -\topmargin 3cm -\rightmargin 2cm -\bottommargin 3cm -\secnumdepth 3 -\tocdepth 3 -\paragraph_separation indent -\paragraph_indentation default -\quotes_language english -\papercolumns 1 -\papersides 1 -\paperpagestyle default -\tracking_changes false -\output_changes false -\html_math_output 0 -\html_css_as_file 0 -\html_be_strict false -\end_header - -\begin_body - -\begin_layout Title -Binary_grid -\end_layout - -\begin_layout Standard -Written by Robert Izzard, with greatly appreciated help from Fabian Schneider - and the other users of -\emph on -binary_grid -\emph default -. -\begin_inset Newline newline -\end_inset - - -\begin_inset Newline newline -\end_inset - -Warning: This document describes the old -\emph on -binary_grid -\emph default -, -\emph on -grid() -\emph default - and -\emph on -threaded_grid(). -\begin_inset Newline newline -\end_inset - - -\begin_inset Newline newline -\end_inset - - -\emph default -These are no longer supported and have been replaced by -\emph on -flexigrid() -\emph default -. -\begin_inset Newline newline -\end_inset - - -\begin_inset Newline newline -\end_inset - -Please see the binary_grid-flexigrid.pdf file for the newer documentation. -\begin_inset Newline newline -\end_inset - - -\begin_inset Newline newline -\end_inset - - -\begin_inset Newline newline -\end_inset - - -\begin_inset Newline newline -\end_inset - - -\begin_inset Newpage pagebreak -\end_inset - - -\end_layout - -\begin_layout Section -Aims: what the grid does and why -\end_layout - -\begin_layout Standard -Binary population synthesis is a glorified form of accountancy, without - the huge pay but with of course much more fun! It involves modelling perhaps - millions of binary stars in a population to pick out those few that contribute - to the population of scientific interest. - The rate of formation, or number of these stars, or some other property - of them can then be examined in a -\emph on -quantitative -\emph default - and -\emph on -statistical -\emph default - manner. - This manual explains how the -\emph on -binary_grid -\emph default -module -- part of the -\emph on -binary_c/nucsyn -\emph default - code package -- can be used to model populations of single and binary stars. - -\end_layout - -\begin_layout Standard -For details about the binary stellar evolution code -\emph on -binary_c/nucsyn -\emph default - please see the nucsyn_manual document. - This guide is -\emph on -only -\emph default - concerned with the details of running grids of models, not about the details - of the models themselves. -\end_layout - -\begin_layout Subsection -Grid dimensions -\end_layout - -\begin_layout Standard -There are many parameters which can be set before running a stellar model. - The most important, for single stars, are the stellar mass -\begin_inset Formula $M$ -\end_inset - - and metallicity -\begin_inset Formula $Z$ -\end_inset - -. - It is common to set the metallicity -\begin_inset Formula $Z$ -\end_inset - - to be constant and vary the initial stellar mass -\begin_inset Formula $M$ -\end_inset - -. - In everything that follows I will assume you are working at a constant - metallicity -\begin_inset Formula $Z$ -\end_inset - -. - -\end_layout - -\begin_layout Standard -The situation is more complicated in binaries because instead of just -\begin_inset Formula $M$ -\end_inset - - there are two stellar masses -\begin_inset Formula $M_{1}$ -\end_inset - - and -\begin_inset Formula $M_{2}$ -\end_inset - -, the separation -\begin_inset Formula $a$ -\end_inset - - (or, equivalently, the period -\begin_inset Formula $P$ -\end_inset - -) and perhaps the eccentricity -\begin_inset Formula $e$ -\end_inset - -. - To run a population of binary stars then requires a grid of models in four - dimensions. - Often the eccentricity is ignored because close binaries -- which are the - ones in which you may be interested -- tend to circularise rapidly. - This reduces the problem to three dimensions. -\end_layout - -\begin_layout Standard -The number of stars on each side of the grid, i.e. - the -\emph on -resolution -\emph default - -\begin_inset Formula $n$ -\end_inset - -, roughly determines the total runtime of your simulation. - In single stars this is just -\begin_inset Formula $\Delta t\times n$ -\end_inset - -, where one model takes a time -\begin_inset Formula $\Delta t$ -\end_inset - - to run. - In the case of binaries on a three-dimensional grid, this increases to - -\begin_inset Formula $\Delta t\times n^{3}$ -\end_inset - - (see Fig. -\begin_inset space ~ -\end_inset - - -\begin_inset CommandInset ref -LatexCommand ref -reference "fig:grid-size" - -\end_inset - -). - In a typical population -\begin_inset Formula $n\sim100$ -\end_inset - - so the total runtime increases by a factor of -\begin_inset Formula $100^{2}=10^{4}$ -\end_inset - -. - This ignores the increase in -\begin_inset Formula $\Delta t$ -\end_inset - - for binaries which is unavoidable because there are two stars under considerati -on as well as smaller timesteps during mass transfer. - It is for this reason that the -\emph on -binary_c/nucsyn -\emph default - code (and its BSE ancestor) must be -- and is -- fast. - It can run a population of -\begin_inset Formula $10^{6}$ -\end_inset - - binaries in less than -\begin_inset Formula $24\,\mathrm{CPU\, hours}$ -\end_inset - -. - -\begin_inset Float figure -wide false -sideways false -status open - -\begin_layout Plain Layout -\begin_inset Graphics - filename binary_grid_images/m1_cuboid.ps - lyxscale 10 - scale 30 - rotateAngle 270 - -\end_inset - - -\begin_inset Graphics - filename binary_grid_images/m1_m2_a_cuboid.ps - lyxscale 10 - scale 30 - rotateAngle 270 - -\end_inset - - -\end_layout - -\begin_layout Plain Layout -\begin_inset Caption - -\begin_layout Plain Layout -\begin_inset CommandInset label -LatexCommand label -name "fig:grid-size" - -\end_inset - -The relative size of the single- and binary-star grids. - In single stars only one mass is required, -\begin_inset Formula $M_{1}$ -\end_inset - -, while in binaries the two masses -\begin_inset Formula $M_{1}$ -\end_inset - - and -\begin_inset Formula $M_{2}$ -\end_inset - - and separation are needed. - For a grid resolution of -\begin_inset Formula $n=100$ -\end_inset - -, the runtime for the single stars (left cuboid) is -\begin_inset Formula $100\times\Delta t$ -\end_inset - -, where -\begin_inset Formula $\Delta t$ -\end_inset - - is the runtime for one stellar system. - In binaries (right cuboid) this increases to at least -\begin_inset Formula $10^{6}\times\Delta t$ -\end_inset - - because of the extra grid dimensions. - In addition, -\begin_inset Formula $\Delta t$ -\end_inset - - will be longer for binaries because of the short timesteps required during - some phases of mass transfer, the fact that there are two stars to follow - in the evolution/nucleosynthesis algorithms and extra overhead from logging - and parsing output from both stars. - Typically, -\begin_inset Formula $\Delta t\sim0.1\,\mbox{s}$ -\end_inset - - on a -\begin_inset Formula $3\,\mbox{Ghz}$ -\end_inset - - PC. -\end_layout - -\end_inset - - -\end_layout - -\begin_layout Plain Layout - -\end_layout - -\end_inset - - -\end_layout - -\begin_layout Subsection -What to do with the grid -\end_layout - -\begin_layout Standard -What do we do once the grid of stars is set up? In most cases this involves - adding up some statistics related to each star on the grid. - There are two approaches which are commonly used, constant star formation - and a starburst. - The one that suits you depends on what you are trying to calculate and - to which observations you hope to compare. -\end_layout - -\begin_layout Subsubsection -Constant star formation rate -\end_layout - -\begin_layout Standard -In this case the formation rate or (perhaps -\begin_inset Formula $\delta t$ -\end_inset - --weighted) probabilities for each star corresponding to those in which you - are interested are simply added up. - This is why I say it is like accountancy! Because the rate of star formation - is assumed to be -\emph on -constant -\emph default - the evolution time of the stellar evolution is irrelevant. - A hybrid scheme can also be used, you might only consider stars older than - a given age (e.g. - for halo stars). -\end_layout - -\begin_layout Subsubsection -Starburst -\end_layout - -\begin_layout Standard -All stars form at time zero and you add up the (probably -\begin_inset Formula $\delta t$ -\end_inset - --weighted) number of stars in which you are interested which form or exist - in each time bin. - A good example is the delay-time distribution of type Ia supernovae. -\begin_inset Newline newline -\end_inset - - -\end_layout - -\begin_layout Standard -The statistic you wish to add up is usually output from -\emph on -binary_c/nucsyn. - -\emph default -Your -\begin_inset Quotes eld -\end_inset - -grid script -\begin_inset Quotes erd -\end_inset - - runs each star, takes the output of -\emph on -binary_c/nucsyn -\emph default - and adds up the statistic. - You can generate single numbers, histograms or arbitrarily complicated - statistical constructs for comparison with observations. - You can choose whether to do the calculations on the fly or save the progenitor - information for later data processing. -\end_layout - -\begin_layout Standard -The grid script can be used on multi-CPU machines and handles the administrative - issues regarding parallel processing. -\end_layout - -\begin_layout Standard -\begin_inset Newpage pagebreak -\end_inset - - -\end_layout - -\begin_layout Section -Grid setup (in theory) -\end_layout - -\begin_layout Standard -\begin_inset CommandInset label -LatexCommand label -name "sec:grid-setup-theory" - -\end_inset - -This section presents the -\emph on -theory -\emph default - behind the setup of a grid in -\begin_inset Formula $M$ -\end_inset - -, for single stars, or -\begin_inset Formula $M_{1}$ -\end_inset - -, -\begin_inset Formula $M_{2}$ -\end_inset - - and -\begin_inset Formula $a$ -\end_inset - - for binary stars. - In general a -\emph on -logarithmic -\emph default - spacing is chosen for the mass grid because the important relevant physical - processes are -\begin_inset Quotes eld -\end_inset - -more different -\begin_inset Quotes erd -\end_inset - - for the mass range -\begin_inset Formula $1-10\,\mathrm{M}_{\odot}$ -\end_inset - - than between -\begin_inset Formula $10-100\,\mathrm{M}_{\odot}$ -\end_inset - -. - This is rather subjective but you can chose the bounds of your grid to - reflect the stars in which your interest lies. -\end_layout - -\begin_layout Standard -Each star in the grid represents a -\emph on -phase volume -\emph default -. - This means that a star of mass -\begin_inset Formula $M$ -\end_inset - - represents stars which, in reality, have masses -\begin_inset Formula $M-\delta M/2$ -\end_inset - - to -\begin_inset Formula $M+\delta M/2$ -\end_inset - -, where -\begin_inset Formula $\delta M$ -\end_inset - - is the grid spacing. - In an ideal world -\begin_inset Formula $\delta M$ -\end_inset - - would be very small, so our simulations match reality as closely as possible. - However, this is not usually possible if the grid is to run in a reasonable - amount of time (before funding runs out). - The usual way around this is to 1) be clever and/or 2) use a brute-force - approach where the resolution is increased (in this case -\begin_inset Formula $\delta M$ -\end_inset - - decreased) until your -\begin_inset Quotes eld -\end_inset - -answer -\begin_inset Quotes erd -\end_inset - - converges. -\end_layout - -\begin_layout Standard -One concept which must be grasped is that the bounds of the -\emph on -grid -\emph default - are not necessarily the bounds of the -\emph on -initial distributions -\emph default - you will be using (e.g. - the initial mass function, IMF). - This is a critical point which can lead to confusion, it is best explained - with an example. - Say you wish to calculate the ratio of type II to type Ib/c supernovae. - You would do this by adding up the number of stars that explode as type - IIs and divide by the number of stars that explode as type Ib/cs. - You -\emph on -could -\emph default - do this with a grid from -\begin_inset Formula $0.1$ -\end_inset - - to -\begin_inset Formula $100\,\mathrm{M}_{\odot}$ -\end_inset - - and, given enough stars, you would come up with the correct answer. - This is easy for single stars, because -\begin_inset Formula $10^{4}$ -\end_inset - - single stars are easily run on a modern PC. - However, for binaries this is difficult, because even with only -\begin_inset Formula $100$ -\end_inset - - stars in the -\begin_inset Formula $M_{2}$ -\end_inset - - and -\begin_inset Formula $a$ -\end_inset - - dimensions, there would be -\begin_inset Formula $10^{8}$ -\end_inset - - stars in your simulation and the runtime would be huge. - You can, however, be smarter and reduce the grid bounds and resolution. - You know in advance that at solar metallicity ( -\begin_inset Formula $Z=0.02$ -\end_inset - -) type II and Ib/c supernovae occur in -\emph on -single stars -\emph default - with -\begin_inset Formula $M\gtrsim8\mathrm{M}_{\odot}$ -\end_inset - -. - If you choose -\begin_inset Formula $M_{1}$ -\end_inset - - to run between (say) -\begin_inset Formula $4$ -\end_inset - - and -\begin_inset Formula $100\,\mathrm{M}_{\odot}$ -\end_inset - - you know you will record the supernovae from mass transfer (as -\begin_inset Formula $M_{2}\le M_{1}$ -\end_inset - - so the minimum mass of merged stars is the required -\begin_inset Formula $8\,\mathrm{M}_{\odot}$ -\end_inset - -) as well as all the others at higher masses. - So, you will get the -\emph on -same answer -\emph default - from a grid between -\begin_inset Formula $4$ -\end_inset - - and -\begin_inset Formula $100\,\mathrm{M}_{\odot}$ -\end_inset - - as with a grid between -\begin_inset Formula $0.1$ -\end_inset - - and -\begin_inset Formula $100\,\mathrm{M}_{\odot}$ -\end_inset - -. - Note that the -\emph on -grid -\emph default - has changed, but the result has not. - This is because the initial distributions have fixed bounds independent - of the grid bounds. - See Section -\begin_inset space ~ -\end_inset - - -\begin_inset CommandInset ref -LatexCommand ref -reference "sec:initial-dists" - -\end_inset - - for more details on initial distributions. - -\end_layout - -\begin_layout Standard -This process requires some knowledge in advance, which you may not have. - In that case, run a low resolution grid, find suitable grid bounds and - then repeat at higher resolution until you are happy. - The downside to the process is that you may well miss small parts of the - parameter space which contain interesting systems. - In practice this is often a compromise worth making and, if in doubt, test - your model runs at low resolution but then crank the resolution to the - maximum you think is possible for the final model run. -\end_layout - -\begin_layout Standard -Another advantage of choosing the grid bounds is that sub-grids can be run - on different computers or CPU cores and the results combined. - This is discussed further in Section -\begin_inset space ~ -\end_inset - - -\begin_inset CommandInset ref -LatexCommand ref -reference "sec:threads" - -\end_inset - -. -\end_layout - -\begin_layout Subsection -Phase Volume -\end_layout - -\begin_layout Standard -\begin_inset CommandInset label -LatexCommand label -name "sub:phase-volume" - -\end_inset - -Given a chosen set of these distributions a logarithmic grid is set up in - one-dimensional -\begin_inset Formula $M$ -\end_inset - - space for single stars or 3D -\begin_inset Formula $M_{1}$ -\end_inset - --- -\begin_inset Formula $M_{2}$ -\end_inset - --- -\begin_inset Formula $a$ -\end_inset - - space for binary stars. - The grid is split into -\begin_inset Formula $n$ -\end_inset - - stars per dimension such that each star represents the centre of a logarithmic - grid-cell of size -\begin_inset Formula $\delta V$ -\end_inset - - where -\end_layout - -\begin_layout Standard -\begin_inset Formula -\begin{equation} -\delta V=\left\{ \begin{array}{cc} -\delta\ln M & \textrm{single stars}\\ -\delta\ln M_{1}\,\delta\ln M_{2}\,\delta\ln a & \textrm{binary stars} -\end{array}\right. -\end{equation} - -\end_inset - -and -\begin_inset Formula -\begin{equation} -\delta\ln x=\frac{\ln x_{\textrm{max}}-\ln x_{\textrm{min}}}{n}\,, -\end{equation} - -\end_inset - -where -\begin_inset Formula $x$ -\end_inset - - represents -\begin_inset Formula $M$ -\end_inset - -, -\begin_inset Formula $M_{1}$ -\end_inset - -, -\begin_inset Formula $M_{2}$ -\end_inset - - or -\begin_inset Formula $a$ -\end_inset - - and -\begin_inset Formula $x_{\textrm{max}}$ -\end_inset - - and -\begin_inset Formula $x_{\textrm{min}}$ -\end_inset - - are the grid limits. - The total number of stars is denoted by -\begin_inset Formula $N$ -\end_inset - - such that -\begin_inset Formula $N=n$ -\end_inset - - for single stars and -\begin_inset Formula $N=n^{3}$ -\end_inset - - for binary stars. -\end_layout - -\begin_layout Standard -The probability of existence of star -\begin_inset Formula $i$ -\end_inset - - is given by -\end_layout - -\begin_layout Standard -\begin_inset Formula -\begin{equation} -\delta p_{i}=\Psi\delta V_{i}=\Psi\delta V\,, -\end{equation} - -\end_inset - -because -\begin_inset Formula $\delta V$ -\end_inset - - is a constant. - The function -\begin_inset Formula $\Psi$ -\end_inset - - is discussed in Section -\begin_inset space ~ -\end_inset - - -\begin_inset CommandInset ref -LatexCommand ref -reference "sec:initial-dists" - -\end_inset - -. - -\end_layout - -\begin_layout Standard -The probability, -\begin_inset Formula $\delta p_{i}$ -\end_inset - -, is sometimes the quantity you wish to add up, although commonly you want - -\begin_inset Formula $\delta p_{\mathrm{i}}\times\delta t$ -\end_inset - - where -\begin_inset Formula $\delta t$ -\end_inset - - is the time spent in the phase of interest. - This is usually the case when comparing the number of stars which go through - a particular phase of evolution because the -\emph on -time -\emph default -in the phase of evolution is as important as the -\emph on -probability -\emph default - of the star existing in the first place. - -\emph on - -\emph default -However, for -\emph on -event rates -\emph default - (e.g. - supernovae) the time involved is zero, they are instantaneous events on - a stellar evolution timescale, so you have to sum up the -\begin_inset Formula $\delta p_{i}$ -\end_inset - -. - You have to be careful to calculate the appropriate statistics for comparison - with the observations. -\end_layout - -\begin_layout Subsection -Grid loops -\end_layout - -\begin_layout Standard -\begin_inset CommandInset label -LatexCommand label -name "sub:grid-loops" - -\end_inset - -In binary systems, the secondary mass -\begin_inset Formula $M_{2}$ -\end_inset - - typically depends on the primary mass -\begin_inset Formula $M_{2}$ -\end_inset - -, and the separation, -\begin_inset Formula $a$ -\end_inset - -, or period -\begin_inset Formula $P$ -\end_inset - -, may depend on both. - This means that usually the grid must be constructed in a series of nested - loops and statistics must be added in order as follows: -\end_layout - -\begin_layout Standard -\begin_inset Formula -\begin{equation} -{\displaystyle \sum}_{M_{1}=M_{\mathrm{1,min}}}^{M_{1,\mathrm{max}}}\left(\sum_{M_{2}=M_{2}}^{M_{2\mathrm{,max}}}\left\{ \sum_{a=a_{\mathrm{min}}}^{a_{\mathrm{max}}}\left[\dots\right]\right\} \right)\,.\label{eq:grid-loops} -\end{equation} - -\end_inset - -In the default grid, -\begin_inset Formula $M_{2}$ -\end_inset - - depends on -\begin_inset Formula $M_{1}$ -\end_inset - - through the -\begin_inset Formula $q=M_{2}/M_{1}$ -\end_inset - - distribution. - The default is a flat- -\begin_inset Formula $q$ -\end_inset - - distribution (see Section -\begin_inset space ~ -\end_inset - - -\begin_inset CommandInset ref -LatexCommand ref -reference "sec:initial-dists" - -\end_inset - -), with which stars only exist if -\begin_inset Formula $0.1\,\mathrm{M}_{\odot}\leq M_{2}\leq M_{1}$ -\end_inset - -. - As such it generally makes sense to have -\begin_inset Formula $M_{2,\mathrm{min}}=0.1\,\mathrm{M}_{\odot}$ -\end_inset - - and -\begin_inset Formula $M_{2,\mathrm{max}}=M_{1}$ -\end_inset - - because secondary stars with mass greater than the primary do not exist - (by definition of the secondary and primary). -\end_layout - -\begin_layout Standard -The default separation distribution does not depend on the masses, but it - may if the -\family typewriter -adapt_sepdist -\family default - option is used (see Section -\begin_inset space ~ -\end_inset - - -\begin_inset CommandInset ref -LatexCommand ref -reference "sec:grid-options" - -\end_inset - -). -\end_layout - -\begin_layout Subsection -Resolution -\end_layout - -\begin_layout Standard -\begin_inset CommandInset label -LatexCommand label -name "sub:resolution" - -\end_inset - -The choice of grid resolution depends very much on the problem you wish - to address and what you are trying to calculate. - As a general rule, assuming you are modelling stars from -\begin_inset Formula $M_{\mathrm{min}}=0.1\,\mathrm{M}_{\odot}$ -\end_inset - - to -\begin_inset Formula $M_{\mathrm{max}}=100\,\mathrm{M}_{\odot}$ -\end_inset - - you probably want at least -\begin_inset Formula $100$ -\end_inset - - stars in the -\begin_inset Formula $M$ -\end_inset - - (or -\begin_inset Formula $M_{1}$ -\end_inset - -) dimension. - -\end_layout - -\begin_layout Standard -However, before rushing off to run millions of stars, run some low-resolution - test models and gradually increase the number of stars. - The best way to determine the required resolution is simply the brute force - method: keep increasing the resolution until your answers converge. -\end_layout - -\begin_layout Standard -You can roughly estimate the -\emph on -statistical -\emph default -error by counting the number of stars that satisfy your criterion (say -\begin_inset Formula $k$ -\end_inset - - stars) and then use Poisson statistics (i.e. - the error on a value -\begin_inset Formula $x$ -\end_inset - - is -\begin_inset Formula $x/\sqrt{k}$ -\end_inset - -). - -\series bold -Be warned that this is -\emph on -not -\emph default - the error due to the use of a grid. - -\series default - If your data calculation binning is -\emph on -over -\emph default --resolved you may see problems with artifacts and aliasing. - These may or may not affect your results. - If in doubt, increase the resolution until the problem goes away (if it - goes away!). - In some cases this may not be possible because your computer is not fast - enough. - You could always buy a time machine\SpecialChar \ldots{} - but then you wouldn't be doing astrophysics -! -\end_layout - -\begin_layout Standard -Sometimes you can choose a better mass grid than the default -\begin_inset Formula $\ln M$ -\end_inset - - grid to obtain better resolution where required for the same number of - stars, as described in the next section. -\end_layout - -\begin_layout Subsection -Alternative grid spacing -\end_layout - -\begin_layout Standard -\begin_inset CommandInset label -LatexCommand label -name "sub:alternative-grid-spacing" - -\end_inset - -Some problems require a more carefully spaced grid than the simple -\begin_inset Formula $\ln M$ -\end_inset - - grid. - A good example is the calculation of stellar yields. - The yield sets are generally required to give yields out to a time of many - -\begin_inset Formula $\mathrm{Gyr}$ -\end_inset - - and with a time resolution of, say, -\begin_inset Formula $10\,\mathrm{Myr}$ -\end_inset - -. - At early times this is not a problem, but at late times the stellar lifetime - scales with the mass as -\begin_inset Formula $t\sim M^{3}$ -\end_inset - - (roughly) so in order to have good time resolution we require -\begin_inset Formula $\delta M\sim\delta t/(3M^{2})\sim t^{-2/3}\delta t$ -\end_inset - - which is rather small at late times when -\begin_inset Formula $t$ -\end_inset - - is large. - -\end_layout - -\begin_layout Standard -An alternative is to set up the grid to -\emph on -enforce -\emph default - -\begin_inset Formula $\delta M=f\times\delta t/(3M^{2})$ -\end_inset - - as our grid spacing (with a factor -\begin_inset Formula $f<1$ -\end_inset - - which ensures over-resolution to avoid gridding artifacts). - Implementations of this, and a fixed -\begin_inset Formula $\delta\ln t$ -\end_inset - - grid, are available in -\emph on -binary_grid -\emph default -. - -\end_layout - -\begin_layout Standard -\begin_inset Newpage pagebreak -\end_inset - - -\end_layout - -\begin_layout Section -Grid setup (in practice) -\end_layout - -\begin_layout Standard -\begin_inset CommandInset label -LatexCommand label -name "sec:grid-setup-practice" - -\end_inset - -This section describes a typical grid setup with the default grid options. - Alternative grid setups are discussed in Section -\begin_inset space ~ -\end_inset - - -\begin_inset CommandInset ref -LatexCommand ref -reference "sec:grid-options" - -\end_inset - - which lists the grid options in detail. -\end_layout - -\begin_layout Standard -The grid is set up by use of a Perl module called -\emph on -binary_grid -\emph default -. - This is usually installed with -\emph on -binary_c/nucsyn -\emph default - (see the -\emph on -binary_c/nucsyn -\emph default - manual). - In any case, you need it! You will also need the -\emph on -IMF -\emph default - perl module (to calculate initial stellar distribution functions, see Section -\begin_inset space ~ -\end_inset - - -\begin_inset CommandInset ref -LatexCommand ref -reference "sec:initial-dists" - -\end_inset - -) and -\emph on -rob_misc -\emph default - (Rob's miscellaneous function library). -\end_layout - -\begin_layout Standard -You should copy the grid.pl script provided with -\emph on -binary_c/nucsyn -\emph default - and work on your -\emph on -copy -\emph default -. - The -\emph on -grid.pl -\emph default - script is a template for a minimal grid setup -- you will need to change - it to reflect whatever you output from the -\emph on -binary_c/nucsyn -\emph default - code. - It will be referred to as -\begin_inset Quotes eld -\end_inset - -your grid script -\begin_inset Quotes erd -\end_inset - - in what follows. -\end_layout - -\begin_layout Subsection -The Perl Module -\end_layout - -\begin_layout Standard -The -\emph on -binary_grid -\emph default - Perl module contains (almost) all the code to set up, manage and run the - grid, as well as the interface to the -\emph on -binary_c/nucsyn -\emph default -. - This should be (almost) completely transparent to you, the user, and the - process is as automated as possible. - -\end_layout - -\begin_layout Subsubsection -Variables -\end_layout - -\begin_layout Standard -There are many global variables (sorry) but let's face it, this is written - in Perl, not C, so it doesn't matter. - You should not access most of them, except for the two hashes: -\end_layout - -\begin_layout Description - -\family typewriter -%bse_options -\family default - are those that are passed to the -\emph on -binary_c/nucsyn -\emph default - code and are discussed in detail in the -\emph on -binary_c/nucsyn -\emph default - manual. - They usually affect the -\emph on -physics -\emph default - being implemented in the simulation. -\end_layout - -\begin_layout Description - -\family typewriter -%grid_options -\family default - are variables which control details of the -\emph on -grid -\emph default - and the processing of the output. -\end_layout - -\begin_layout Standard -To access the variables in your grid script, you should use something like - the following: -\begin_inset Newline newline -\end_inset - - -\end_layout - -\begin_layout Standard - -\family typewriter -$binary_grid::bse_options{'max_evolution_time'}=10.0; -\end_layout - -\begin_layout Standard - -\family typewriter -$binary_grid::grid_options{'imf1'}='ktg93'; -\begin_inset Newline newline -\end_inset - - -\end_layout - -\begin_layout Standard -The -\family typewriter -$binary_grid:: -\family default - tells Perl that you want to change the hash in the -\family typewriter -binary_grid -\family default - module rather than a local variable with the same name which may exist - in your grid script. -\end_layout - -\begin_layout Subsubsection -Important Subroutines -\end_layout - -\begin_layout Standard -The most important subroutines involved in setting up the grid, some of - which you have to call from your grid script (see Section -\begin_inset space ~ -\end_inset - - -\begin_inset CommandInset ref -LatexCommand ref -reference "sec:grid.pl" - -\end_inset - -) are the following: -\end_layout - -\begin_layout Description - -\family typewriter -grid_defaults -\family default - This sets up the default values for the two main hashes of options: -\family typewriter -%grid_options -\family default - and -\family typewriter -%bse_options -\family default -. - Note that in the case where a -\family typewriter -bse_option -\family default - is -\emph on -not -\emph default - given default, you may still set it in your grid script, but if it is -\emph on -not -\emph default - set the default -\emph on -binary_c/nucsyn -\emph default - value is used. -\end_layout - -\begin_layout Description - -\family typewriter -parse_grid_args -\family default - Arguments given on the command line in the form -\emph on -x -\family typewriter -\emph default -= -\family default -\emph on -y -\emph default - are parsed in turn. - If -\emph on -x -\emph default - matches any of the keys of the -\family typewriter -%grid_options -\family default - or -\family typewriter -%bse_options hashes -\family default -, the value of the hash item is set to that given by -\emph on -y -\emph default -. - If the key is not matched it is ignored. - A good example of the use of this function is the use of -\family typewriter -vb=1 -\family default - to turn on verbose log output from the grid. - This verbose output is often very useful as it gives you an estimate of - the fraction of the grid that is complete, the time remaining and the estimated - time at which the grid will finish. -\end_layout - -\begin_layout Description - -\family typewriter -setup_binary_grid -\family default - This should be called just before running your grid. - It initialises the initial distributions, sets up the timeout feature, - opens some log files etc. -\end_layout - -\begin_layout Description - -\family typewriter -test_grid -\family default - This was originally used to run the grid without running -\emph on -binary_c/nucsyn -\emph default -. - There are uses for this, such as calculating the mass that goes into stars - for a given initial distribution, but you probably do not need it. -\end_layout - -\begin_layout Description - -\family typewriter -grid -\family default - This runs the old-fashioned, single-thread grid. - You should really learn how to use the superior -\emph on -flexigrid -\emph default - instead. -\end_layout - -\begin_layout Description - -\family typewriter -flexigrid -\family default - This runs the latest version of the grid with perfect load balancing and - code built on the fly. - If you are running a grid of stars for the first time, you should use this. -\end_layout - -\begin_layout Description - -\family typewriter -tbse_line -\family default - This is called to retrieve data from calls to -\emph on -binary_c/nucsyn -\emph default -: see Section -\begin_inset space ~ -\end_inset - - -\begin_inset CommandInset ref -LatexCommand ref -reference "sec:data-parsing" - -\end_inset - -. -\end_layout - -\begin_layout Subsection -Less important subroutines -\end_layout - -\begin_layout Standard -If you really care about the structure of the -\family typewriter -binary_grid module -\family default -, rather than how to use it, you have come to the right place. - Almost everything in -\family typewriter -binary_grid -\family default - not mentioned above is dedicated to the running and management of the grid - loops (see Eq. -\begin_inset space ~ -\end_inset - - -\begin_inset CommandInset ref -LatexCommand ref -reference "eq:grid-loops" - -\end_inset - -). -\end_layout - -\begin_layout Standard -The -\family typewriter -grid -\family default - subroutine does a number of things in turn, of which the most important - are listed below: -\end_layout - -\begin_layout Enumerate -The -\family typewriter -%masshash -\family default - is set up. - The -\family typewriter -%masshash -\family default - contains as its keys the (single- or binary-star) masses -\begin_inset Formula $M$ -\end_inset - - (or -\begin_inset Formula $M_{1}$ -\end_inset - -) and as values the width in -\emph on -log mass space -\begin_inset Formula $\delta\ln M$ -\end_inset - - -\emph default -(or -\begin_inset Formula $\delta\ln M_{1}$ -\end_inset - -) -\emph on -. - -\emph default - This is done with the -\family typewriter -setup_masshash -\family default - subroutine. - This also creates a numerically sorted list of masses in the hash, stored - in -\family typewriter -@mlist -\family default -. -\end_layout - -\begin_layout Enumerate -The -\family typewriter -tbse_launch -\family default - subroutine is called to start -\emph on -binary_c/nucsyn -\emph default -. -\end_layout - -\begin_layout Enumerate -A loop is made over the -\family typewriter -@mlist -\family default - masses. - Note that the loop is -\emph on -not necessarily -\emph default - over the whole list! In a threaded grid only a part of the list is looped - over -- if threads are not being used, the whole list is looped. - -\end_layout - -\begin_layout Enumerate -If -\family typewriter -$binary_grid::grid_options{'binary'} -\family default - is -\emph on -zero -\emph default -(i.e. - we want single stars only) then a loop over the masses is performed. - For each mass: -\end_layout - -\begin_deeper -\begin_layout Enumerate -The -\family typewriter -$binary_grid::progenitor -\family default - variables are set (see Section -\begin_inset space ~ -\end_inset - - -\begin_inset CommandInset ref -LatexCommand ref -reference "sec:debugging" - -\end_inset - -). - These save the values of the masses, period, separation and eccentricity - for each star and so are useful for debugging/logging. -\end_layout - -\begin_layout Enumerate -The probability of existence of the star is calculated with -\family typewriter -calc_prob -\family default - (from the IMF Perl module) -\end_layout - -\begin_layout Enumerate -The -\family typewriter -tbse() -\family default - subroutine is called for each mass. -\end_layout - -\end_deeper -\begin_layout Enumerate -If -\family typewriter -$binary_grid::grid_options{'binary'} -\family default - is -\emph on -one -\emph default -(i.e. - we want binary stars) the list of masses is looped over as in single stars - but things are then done a little differently: -\end_layout - -\begin_deeper -\begin_layout Enumerate -For each primary mass -\begin_inset Formula $M_{1}$ -\end_inset - - a call is made to the -\family typewriter -populate_m2list -\family default - subroutine. - This makes a list of secondary star masses -\begin_inset Formula $M_{2}$ -\end_inset - - which is looped over. -\end_layout - -\begin_layout Enumerate -For each -\begin_inset Formula $M_{2}$ -\end_inset - - the third loop is called. - This is usually call to the -\family typewriter -separation_loop -\family default - subroutine, but if you are using an initial distribution which is based - on the orbital period rather than the separation then -\family typewriter -period_loop -\family default - is called. -\end_layout - -\begin_layout Enumerate -The separation (or period) loop then sets -\family typewriter -$binary_grid::progenitor -\family default -, calculates the probability with -\family typewriter -calc_prob -\family default - and calls -\family typewriter -tbse() -\family default - for each combination of -\begin_inset Formula $M_{1}$ -\end_inset - -, -\begin_inset Formula $M_{2}$ -\end_inset - - and -\begin_inset Formula $a$ -\end_inset - - (or -\begin_inset Formula $P$ -\end_inset - -). -\end_layout - -\end_deeper -\begin_layout Enumerate -The -\family typewriter -tbse_land() -\family default - subroutine is called to stop -\emph on -binary_c/nucsyn -\emph default -. -\end_layout - -\begin_layout Standard -There are numerous other subroutines in binary_grid, some of which are not - really used anymore and many shouldn't -- in an ideal world -- be there. - However, you should not remove them because backward compatibility is vital - to some old codes (and perhaps the GCE code). -\end_layout - -\begin_layout Standard -\begin_inset Newpage pagebreak -\end_inset - - -\end_layout - -\begin_layout Section -Data parsing (Accountancy without the salary) -\end_layout - -\begin_layout Standard -\begin_inset CommandInset label -LatexCommand label -name "sec:data-parsing" - -\end_inset - -The previous sections describe how to set up a grid. - Before you actually run your own grid you have to think about what you - want to discover from your stellar models. - A few standard cases are outlined here. - You may, of course, want a combination of all these methods. -\end_layout - -\begin_layout Standard -This section describes the theory, the practical aspects of combining -\emph on -binary_c/nucsyn -\emph default - with your grid script are described in Section -\begin_inset space ~ -\end_inset - - -\begin_inset CommandInset ref -LatexCommand ref -reference "sec:grid.pl" - -\end_inset - -. -\end_layout - -\begin_layout Subsection -Rates of things -\end_layout - -\begin_layout Standard -\begin_inset CommandInset label -LatexCommand label -name "sub:rates-of-things" - -\end_inset - -The simplest thing to calculate is the rate of formation of some type of - star, or alternatively the rate of stellar death (e.g. - the supernova rate), merger rate, etc. - These are -\emph on -events -\emph default -which have no duration so the important thing to log is the -\emph on -time at which the event happened -\emph default -, -\emph on - -\begin_inset Formula $t_{i}$ -\end_inset - - -\emph default -, and -\emph on -the probability of existence of the stellar system, -\emph default - -\begin_inset Formula $p_{i}$ -\end_inset - -. -\end_layout - -\begin_layout Standard -You will probably want to count the number of systems that explode in a - given time bin, i.e. - between time -\begin_inset Formula $t$ -\end_inset - - and -\begin_inset Formula $t+\Delta t$ -\end_inset - -, where -\begin_inset Formula $\Delta t$ -\end_inset - - is the time bin width ( -\emph on -not -\emph default - the -\emph on -binary_c/nucsyn -\emph default - timestep!). - The formation rate is the product of the star formation rate -\begin_inset Formula $S$ -\end_inset - - and the summed probability of the stars that do whatever it is that is - interesting in time -\begin_inset Formula $t$ -\end_inset - - to -\begin_inset Formula $t+\Delta t$ -\end_inset - -, -\begin_inset Formula $\sum p_{i}$ -\end_inset - -. - You have to somehow calculate -\begin_inset Formula $S$ -\end_inset - - (see e.g. - -\begin_inset CommandInset citation -LatexCommand citealp -key "2002MNRAS_329_897H" - -\end_inset - - for a simple prescription). - You would be better comparing the relative rates of two types of event, - in which case -\begin_inset Formula $S$ -\end_inset - - (and its associated uncertainty) cancels. -\end_layout - -\begin_layout Standard -This is all correct for a starburst at time -\begin_inset Formula $t=0$ -\end_inset - -. - If you want to use a more realistic star formation history you have to - convolve the results of many starbursts. - You can do this manually (and it is easy if, say, the metallicity and other - physics is not a function of -\begin_inset Formula $t$ -\end_inset - -) or use a pre-existing code such as Rob's Galactic Chemical Evolution (GCE) - code. - The latter has the advantage that it already exists and is well tested. - You will, however, have to ask Rob about it because it is not (yet) a part - of the standard -\emph on -binary_c/nucsyn -\emph default - distribution. - -\end_layout - -\begin_layout Subsection -Numbers of things -\end_layout - -\begin_layout Standard -\begin_inset CommandInset label -LatexCommand label -name "sub:numbers-of-things" - -\end_inset - - -\end_layout - -\begin_layout Standard -Alternatively, perhaps you wish to calculate the number of stars of a certain - type e.g. - the number of carbon stars or the number of K-type stars. - In this case you have to count both the probability of the existence of - the star -\begin_inset Formula $p_{i}$ -\end_inset - - and the time the star spends in the evolutionary phase of interest. - If we assume -\begin_inset Formula $S=1$ -\end_inset - - (i.e. - constant star formation) you should then count -\begin_inset Formula $\sum p_{i}\,\delta t\,\bar{\delta}$ -\end_inset - - where -\begin_inset Formula $\bar{\delta}=1$ -\end_inset - - if the star is interesting to you, but zero otherwise. -\end_layout - -\begin_layout Standard -As in the previous example, if -\begin_inset Formula $S$ -\end_inset - - is not simply a constant things get tricky. - But usually a constant star formation rate is -\begin_inset Quotes eld -\end_inset - -good enough -\begin_inset Quotes erd -\end_inset - - for e.g. - Galactic stellar population studies of anything but the youngest stars. - In other cases a starburst is more appropriate and you will have to factor - in a check on the time -\begin_inset Formula $t$ -\end_inset - - into -\begin_inset Formula $\bar{\delta}$ -\end_inset - - to match the present-day age of the population. - -\end_layout - -\begin_layout Subsection -GCE and the ensemble -\end_layout - -\begin_layout Standard -\begin_inset CommandInset label -LatexCommand label -name "sub:gce" - -\end_inset - -As already mentioned, Rob has written a Galactic Chemical Evolution code - to do much of the work described above for you. - In addition to (sort of!) self-consistently calculating the nucleosynthesis - and hence metallicity evolution in a Galaxy for arbitrary star formation, - gas infall and outflow rates, you can enable the -\begin_inset Quotes eld -\end_inset - -stellar ensemble -\begin_inset Quotes erd -\end_inset - - in -\emph on -binary_c/nucsyn -\emph default -. - This simply enables a large piece of logging code to output e.g. - stellar types, spectral types, explosion counts, etc. - Rob's GCE code is designed to follow these and do the convolution for you. - It runs in two modes. - The first is to use saved starburst data from previous grid runs. - This is fast but not entirely self-consistent (although often it is good - enough). - The second technique is to run the binary grids at each timestep of the - GCE code. - This is better, in that the metallicity is more self-consistent, but can - be very slow because the GCE code runtime is limited by the time it takes - to run an entire binary grid (which is usually hours). - In future it is hoped that the GCE code will be run on a cluster of machines - with sufficient CPU power to reduce the overhead of running a binary grid. - This will require some effort to reliably automate the process. -\end_layout - -\begin_layout Standard -\begin_inset Newpage pagebreak -\end_inset - - -\end_layout - -\begin_layout Section -Your grid-xxx.pl script -\end_layout - -\begin_layout Standard -\begin_inset CommandInset label -LatexCommand label -name "sec:grid.pl" - -\end_inset - -This describes a simple, single-thread grid based on the hard-coded loop - code. - If you want a better grid, working on multi-core CPUs, learn about the - -\emph on -flexigrid -\emph default - as well (see Section -\begin_inset space ~ -\end_inset - - -\begin_inset CommandInset ref -LatexCommand ref -reference "sec:flexigrid" - -\end_inset - -). -\begin_inset Newline newline -\end_inset - - -\begin_inset Newline newline -\end_inset - -Before you start: you should copy the -\family typewriter -grid.pl -\family default - script in the -\family typewriter -binary_c -\family default - directory to a script of your own naming (usually grid- -\emph on -xxx -\emph default -.pl where you choose a suitable label to replace -\emph on -xxx -\emph default -). - Work on your copy, not the original! -\end_layout - -\begin_layout Subsection -Logging in -\emph on -binary_c -\emph default -or -\emph on -How to know when to add up the number of stars -\end_layout - -\begin_layout Standard -When -\emph on -binary_c -\emph default - is run for one star with the -\family typewriter -tbse -\family default - script the output is dumped to the screen (known in -\emph on -UNIX -\emph default - as -\family typewriter -stdout -\family default -). - A standard build of -\emph on -binary_c -\emph default - outputs very little information because it does not know what you wish - to know. - Every line that is output is expensive in terms of CPU time, and CPU time - is critical when running millions of stars. - This means you have to think carefully about what you will output from - -\emph on -binary_c -\emph default - and when. - Too much information slows things down, too little is useless -- you have - to decide. -\end_layout - -\begin_layout Standard -You will probably want to output one line of information per -\emph on - binary_c -\emph default -timestep. - This should be done in the -\family typewriter -iteration_logging -\family default - subroutine which is called every timestep. - Your logging code should look something like: -\end_layout - -\begin_layout Standard - -\family typewriter -printf( -\begin_inset Quotes eld -\end_inset - -MYLOG %g %g %g %i -\backslash -n -\begin_inset Quotes erd -\end_inset - -, -\end_layout - -\begin_layout Standard - -\family typewriter -stardata->model.model_time, -\end_layout - -\begin_layout Standard - -\family typewriter -stardata->model.probability, -\end_layout - -\begin_layout Standard - -\family typewriter -stardata->model.dt, -\end_layout - -\begin_layout Standard - -\family typewriter -stardata->star[1].mass, -\end_layout - -\begin_layout Standard - -\family typewriter -stardata->star[1].stellar_type); -\end_layout - -\begin_layout Standard -The string -\family typewriter -MYLOG -\family default - is critical: this is what will be recognised and used by -\emph on -binary_grid -\emph default -. - You should have a think (and consult Section -\begin_inset space ~ -\end_inset - - -\begin_inset CommandInset ref -LatexCommand ref -reference "sec:data-parsing" - -\end_inset - -) to determine whether you want to output either the probability ( -\family typewriter -stardata-> model.probability -\family default -) or both the probability and timestep ( -\family typewriter -stardata->model.dt -\family default -). - Often it is the number of stars in a particular phase that you want to - count, in which case you want to add up -\family typewriter -stardata-> (model.probability*stardata->model.dt) -\family default -. -\end_layout - -\begin_layout Subsection -Coupling your -\emph on -binary_c/nucsyn -\emph default - and your grid: -\family typewriter -tbse_line -\family default -and -\family typewriter - parse_bse -\end_layout - -\begin_layout Standard -Now you know how to make lines of logging information come out of the -\emph on -binary_c -\emph default - program. - It remains to couple this to the grid. - This is done through the -\family typewriter -tbse_line -\family default - subroutine in the -\family typewriter -parse_bse -\family default - function (see the example -\family typewriter -grid.pl -\family default -). - Each time -\family typewriter -tbse_line -\family default - is called it gets a line of output from -\emph on -binary_c -\emph default - and loads returns it (usually to -\family typewriter -$_ -\family default - the Perl default variable). - It is then up to you to decide what to with the data from -\family typewriter -tbse_line -\family default -. - -\end_layout - -\begin_layout Standard -There may be many lines of data pumped into -\family typewriter -tbse_line -\family default -, so you have to choose those labelled with your header string -- in the - above example this is -\family typewriter -MYLOG -\family default -. - This is best done with a Perl substitution-regular expression: the regular - expression matches -\family typewriter -MYLOG -\family default -, the substitution removes it (because it is not data). - In the following example note that the check for ' -\family typewriter -fin -\family default -' -\emph on -must -\emph default - be there. - -\emph on -binary_c -\emph default - returns a ' -\family typewriter -fin -\family default -' when the star has finished its evolution. - Without this it would be stuck in an infinite loop, so avoid removing the - -\family typewriter -$brk -\family default - stuff. - -\begin_inset Newline newline -\end_inset - - -\end_layout - -\begin_layout Standard - -\family typewriter -while($brk==0) -\end_layout - -\begin_layout Standard - -\family typewriter -{ -\end_layout - -\begin_layout Standard - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -$_=tbse_line(); chomp; # get line of data from binary_c -\end_layout - -\begin_layout Standard - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -if($_ eq 'fin') -\end_layout - -\begin_layout Standard - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -{ -\end_layout - -\begin_layout Standard - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -$brk=1; # the end of output -\end_layout - -\begin_layout Standard - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -} -\end_layout - -\begin_layout Standard - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -elsif(s/^MYLOG //) # regular expression to match and remove MYLOG -\end_layout - -\begin_layout Standard - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -{ -\end_layout - -\begin_layout Standard - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -split; # convert data string to array -\end_layout - -\begin_layout Standard - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -#... - do stuff with @_ ... -\end_layout - -\begin_layout Standard - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -# e.g. - $_[0] is the time, $_[1] is the probability etc. -\end_layout - -\begin_layout Standard - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -} -\end_layout - -\begin_layout Standard -} -\end_layout - -\begin_layout Subsection -Adding things up -\end_layout - -\begin_layout Standard -So you have the probabilities (and maybe the timesteps) for each timestep - of -\emph on -binary_c -\emph default - and for each star. - What do you do now? Well, you have to create meaningful statistics by summing - up the results. - The easiest way to do this is to use a global hash as in the following - example which counts the number of different types of -\begin_inset Quotes eld -\end_inset - -low mass -\begin_inset Quotes erd -\end_inset - - and -\begin_inset Quotes eld -\end_inset - -high mass -\begin_inset Quotes erd -\end_inset - - stars: -\begin_inset Newline newline -\end_inset - - -\end_layout - -\begin_layout Standard - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -elsif(s/^MYLOG //) # regular expression to match and remove MYLOG -\end_layout - -\begin_layout Standard - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -{ -\end_layout - -\begin_layout Standard - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -split; # convert data string to array -\end_layout - -\begin_layout Standard - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -my $dtp=$_[1]*$_[2];# calculate dt * p -\end_layout - -\begin_layout Standard - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -if($_[3]>8.0) -\end_layout - -\begin_layout Standard - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -{ -\end_layout - -\begin_layout Standard - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -# high mass star -\end_layout - -\begin_layout Standard - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -$results{'high-mass'}+=$dtp; -\end_layout - -\begin_layout Standard - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -} -\end_layout - -\begin_layout Standard - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -else -\end_layout - -\begin_layout Standard - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -{ -\end_layout - -\begin_layout Standard - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -# low mass star -\end_layout - -\begin_layout Standard - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -$results{'low-mass'}+=$dtp; -\end_layout - -\begin_layout Standard - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\family default -} -\end_layout - -\begin_layout Standard - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -} -\begin_inset Newline newline -\end_inset - - -\end_layout - -\begin_layout Standard -At the end of the first section of the grid.pl script it says -\begin_inset Quotes eld -\end_inset - -put your output here -\begin_inset Quotes erd -\end_inset - -. - This is where you should output the results, e.g. - -\end_layout - -\begin_layout Standard - -\family typewriter -# put output here -\end_layout - -\begin_layout Standard - -\family typewriter -printf -\begin_inset Quotes eld -\end_inset - -Ratio of the number of high to low mass stars = %g -\backslash -n -\begin_inset Quotes erd -\end_inset - -, -\end_layout - -\begin_layout Standard - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -$results{'high-mass'}/$results{'low-mass'}; -\end_layout - -\begin_layout Subsection -More advanced accountancy -\end_layout - -\begin_layout Standard -Consider the previous example. - Perhaps instead of simply having -\begin_inset Quotes eld -\end_inset - -low -\begin_inset Quotes erd -\end_inset - - and -\begin_inset Quotes eld -\end_inset - -high -\begin_inset Quotes erd -\end_inset - - mass stars you actually want to calculate a histogram of number of stars - as a function of mass at a certain time. -\end_layout - -\begin_layout Standard -The problem of how to force -\emph on -binary_c -\emph default - to output at given times is a tricky one which is not dealt with here. - However, you should consider following the -\family typewriter -VROT_LOGGING -\family default - code in -\emph on -binary_c -\emph default - (see -\family typewriter -deltat.c -\family default -) which does just this. - Let us assume you have fixed -\emph on -binary_c/nucsyn -\emph default - so it outputs the mass of each star every -\begin_inset Formula $1\,\mathrm{Myr}$ -\end_inset - -. - You want to bin the masses at each timestep, so you will have a series - of histograms. - Note that -\family typewriter -$dtp -\family default - is not required because you are not counting the number of stars in a given - -\emph on -phase -\emph default - but rather an instantaneous property of the stars at a given time -\family typewriter -$t -\family default -. -\end_layout - -\begin_layout Standard -Something like this will do it: -\begin_inset Newline newline -\end_inset - - -\end_layout - -\begin_layout Standard - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -elsif(s/^MYLOG //) # regular expression to match and remove MYLOG -\end_layout - -\begin_layout Standard - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -{ -\end_layout - -\begin_layout Standard - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -split; # convert data string to array -\end_layout - -\begin_layout Standard - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -my $t=$_[0]; # time (an integer number of Myr since the starburst) -\end_layout - -\begin_layout Standard - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -my $p=$_[1]; # probability -\end_layout - -\begin_layout Standard - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -my $m=$_[3]; # stellar mass -\end_layout - -\begin_layout Standard - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\end_layout - -\begin_layout Standard - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -# bin stellar mass in 1Msun bins -\end_layout - -\begin_layout Standard - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -$m = int(0.5+$m); -\end_layout - -\begin_layout Standard - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\end_layout - -\begin_layout Standard - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -$results{'mass histogram'}{$t}{$m}+=$p; # construct histogram -\end_layout - -\begin_layout Standard - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -} -\end_layout - -\begin_layout Standard -Things to note include: -\end_layout - -\begin_layout Itemize -The mass is binned to the nearest integer. - You can construct a similar expression for an arbitrary bin width. - Why do we do this? Well, if we take the instantaneous mass of each star - in a population at a given time there will be a huge number of different - masses because mass loss may be effective. - This would give a histogram with -\begin_inset Formula $N\times N_{t}=n_{\mathrm{M1}}\times n_{\mathrm{M2}}\times n_{\mathrm{a}}\times N_{t}$ -\end_inset - - bins where -\begin_inset Formula $N_{t}$ -\end_inset - - is the number of timesteps of -\emph on -binary_c -\emph default - output. - This is too much data to deal with and negates the whole purpose of making - a histogram! Bin your data: it makes life a lot easier. -\end_layout - -\begin_layout Itemize -We could have similarly binned the time to include stars at an age -\begin_inset Formula $t$ -\end_inset - - to -\begin_inset Formula $t+\Delta t$ -\end_inset - - (in this case -\begin_inset Formula $\Delta t$ -\end_inset - - would be -\begin_inset Formula $1\,\mathrm{Myr}$ -\end_inset - -) but that smears out the results into -\begin_inset Formula $1\,\mathrm{Myr}$ -\end_inset - - bins. - In our case we have -\emph on -snapshots -\emph default -at a given time instead. -\end_layout - -\begin_layout Itemize -The time and mass are integers in this case, so we could have used arrays - (which have integer index) instead of hashes for the output, but if you - want finer resolution they will not be and hashes are -\emph on -required -\emph default -. - It is good to get into the habit. - -\end_layout - -\begin_layout Itemize -The 'mass histogram' hash label is not required in this simple example, - but in a real grid you may be constructing many different histograms, each - with different labels. -\end_layout - -\begin_layout Itemize -The results are saved in hash of hashes of hashes. - This is a typical example of a Perl nested variable, help for how to deal - with (and output) hashes of hashes is easily found with a simple web search - (or consult the excellent -\emph on -Programming Perl -\emph default -). -\end_layout - -\begin_layout Itemize -Beware resolution! Always test different resolutions and beware binning - and aliasing effects. -\end_layout - -\begin_layout Subsection -Save your data -- or process on the fly? -\end_layout - -\begin_layout Standard -Before running a grid you have to make the big decision: do you save your - data or process it all on the fly? There are advantages and disadvantages - to both, as described below. -\end_layout - -\begin_layout Subsubsection -Saving data -\end_layout - -\begin_layout Standard -\begin_inset CommandInset label -LatexCommand label -name "sub:saving_data" - -\end_inset - -In this case you run a grid and tag the initial parameters of each system - of interest (i.e. - the -\begin_inset Formula $M_{1}$ -\end_inset - -, -\begin_inset Formula $M_{2}$ -\end_inset - -, -\begin_inset Formula $a$ -\end_inset - - and -\begin_inset Formula $\delta V=\delta\ln M_{1}\,\delta\ln M_{2}\,\delta a$ -\end_inset - -). - -\emph on -You save these initial parameters into a large datafile. - -\emph default - The big advantage of this technique is that you can rerun the saved grid - -\emph on -from the datafile, -\emph default -possibly -\emph on - -\emph default -without running -\emph on -binary_c/nucsyn -\emph default - again, and with a different initial distribution function (e.g. - initial mass function) or very slightly different physics (on the assumption - that changing the physics will not change the systems which were saved). - -\end_layout - -\begin_layout Standard -You could save, as well as the initial parameters of the systems, the time - spent in the phase of interest, -\begin_inset Formula $\Delta t$ -\end_inset - -. - Each time the grid is rerun you would then calculate the probability -\begin_inset Formula $p_{i}$ -\end_inset - - for each system again, hence you know -\begin_inset Formula $p_{i}\Delta t$ -\end_inset - - which is your required -\begin_inset Quotes eld -\end_inset - -number of stars -\begin_inset Quotes erd -\end_inset - -. - You can either -\end_layout - -\begin_layout Enumerate -Change -\begin_inset Formula $p_{i}$ -\end_inset - - and recalculate your statistics. - This does -\emph on -not -\emph default -require the running of -\emph on -binary_c/nucsyn -\emph default - and is the fast option. -\end_layout - -\begin_layout Enumerate -Change -\begin_inset Formula $p_{i}$ -\end_inset - - and some physics, which requires rerunning of -\emph on -binary_c/nucsyn -\emph default -. - This is slower, but still faster than running the full grid. -\end_layout - -\begin_layout Standard -Saving the progenitor data set is a very useful way of saving time after - an initial high-resolution grid run. -\end_layout - -\begin_layout Subsubsection -On the fly data processing -\end_layout - -\begin_layout Standard -\begin_inset CommandInset label -LatexCommand label -name "sub:on-the-fly" - -\end_inset - - -\end_layout - -\begin_layout Standard -If you do not want to recalculate your answer with different initial functions, - you might be better off calculating the results you require -\begin_inset Quotes eld -\end_inset - -on the fly -\begin_inset Quotes erd -\end_inset - -. - This means you do your data processing -\emph on -in your grid script -\emph default -. - The main advantages to this are speed and data storage. - For example, if you have -\begin_inset Formula $10^{6}$ -\end_inset - - -\begin_inset space ~ -\end_inset - -stars in your grid, that is -\begin_inset Formula $10^{6}$ -\end_inset - - -\begin_inset space ~ -\end_inset - -lines of data -- this might be a lot of data. -\end_layout - -\begin_layout Standard -In some cases you -\emph on -must -\emph default - do this. - If you are looking at data which is time dependent then you will have -\begin_inset Formula $10^{6}\times N_{t}$ -\end_inset - - -\begin_inset space ~ -\end_inset - -lines of data, where -\begin_inset Formula $N_{t}$ -\end_inset - - is the number of timesteps during which your system is of interest. - -\begin_inset Formula $N_{t}$ -\end_inset - - may be many hundreds for a given system, hence the total number of lines - of data is of the order of -\begin_inset Formula $10^{8}$ -\end_inset - - and the data storage requirements become quite ridiculous. - For example, a typical line of data has about 200 characters, so -\begin_inset Formula $200\times10^{8}=2\times10^{10}\,\mathrm{bytes}$ -\end_inset - - of data, or -\begin_inset Formula $20\,\mbox{GB}$ -\end_inset - -. - The time it takes to process all this data may be longer than the time - to -\emph on -rerun -\emph default - -\emph on -binary_c/nucsyn -\emph default -for each system, especially if your data storage is non-local (e.g. - on an NFS (network) partition). - Furthermore, you might not have 20 -\begin_inset space ~ -\end_inset - -GB available to you\SpecialChar \ldots{} - -\end_layout - -\begin_layout Standard -You can save some space by outputting data every, say, Myr, but this may - not be the time resolution you require to catch systems of interest. -\end_layout - -\begin_layout Standard -\begin_inset Newpage pagebreak -\end_inset - - -\end_layout - -\begin_layout Section -Grid options -\end_layout - -\begin_layout Standard -\begin_inset CommandInset label -LatexCommand label -name "sec:grid-options" - -\end_inset - -The following summarises the -\family typewriter -%grid_options -\family default - hash elements. - Please note that some options are (perhaps) no longer used and are left - in this manual as a reference guide only. -\end_layout - -\begin_layout Description - -\family typewriter -adapt_sepdist -\family default - The default separation distribution runs from -\begin_inset Formula $3\,\mathrm{R}_{\odot}$ -\end_inset - - to -\begin_inset Formula $10^{4}\,\mathrm{R}_{\odot}$ -\end_inset - - but the lower limit may be too close to avoid immediate Roche-lobe overflow - (and contact/merger) in massive stars. - Use -\family typewriter -adapt_sepdist=1 -\family default - to avoid this situation by adaptively increasing the lower limit to avoid - instantaneous mergers. - (See -\family typewriter -sepdist_min -\family default -.) (Will not work with -\emph on -flexigrid -\emph default - -- you have to specify a function call yourself in that case.) -\end_layout - -\begin_layout Description - -\family typewriter -alarm_procedure -\family default - When a signal is captured (usually on a timeout) the alarm_procedure tells - us what to do. - If -\begin_inset Formula $0$ -\end_inset - - then the grid exits. - If -\begin_inset Formula $1$ -\end_inset - - it tries to restart on the next star (although this may be buggy it is - the default!). - Really you should fix the problem if there is a timeout because it should - not happen. -\end_layout - -\begin_layout Description - -\family typewriter -args -\family default - Not technically an option, but is the string of arguments which is passed - to -\emph on -binary_c/nucsyn -\emph default -. - Useful for logging or debugging. -\end_layout - -\begin_layout Description - -\family typewriter -binary -\family default - The duplicity. - If binary is 1 then the grid runs binary stars, if 0 then single stars. -\end_layout - -\begin_layout Description - -\family typewriter -colour -\family default - If -\family typewriter -colour=1 -\family default - then verbose output (see -\family typewriter -vb -\family default -) is in colour, using the -\family typewriter -Term::ANSIColor -\family default - Perl module. - This is recommended. -\end_layout - -\begin_layout Description - -\family typewriter -compatibility_mode -\family default - An old (probably now deprecated) option which deletes the -\family typewriter -nucsyn_metallicity -\family default - from -\family typewriter -bse_options -\family default -. - Should no longer be required, so set it to zero. -\end_layout - -\begin_layout Description - -\family typewriter -dm -\family default - Not really a grid option, but stores the current -\begin_inset Formula $\delta M=M\delta\ln M$ -\end_inset - -. - (Was once) useful for debugging. -\end_layout - -\begin_layout Description - -\family typewriter -exit_on_eval_failure -\family default - When each star is run, it is inside a -\emph on -Perl -\emph default - -\family typewriter -eval -\family default - construct. - If there is an error (i.e. - -\family typewriter -$@ -\family default - is not undef) -\emph on -and -\emph default - -\family typewriter -exit_on_eval_failure -\family default - is defined then the grid is stopped. - Otherwise, the grid goes on in the hope that the error does not persist - (possibly dubious!). -\end_layout - -\begin_layout Description - -\family typewriter -extra_flash_resolution -\family default - Use this option to provide extra mass resolution around -\begin_inset Formula $1.9\,\mathrm{M}_{\odot}$ -\end_inset - - (the upper mass of the helium flash) in the lookup table used for the -\family typewriter -time_adaptive_mass_grid -\family default - (see that option and -\family typewriter -stellar_lifetime_table_nm -\family default -). -\emph on - -\begin_inset space ~ -\end_inset - -Please use the flexigrid instead of this option. -\end_layout - -\begin_layout Description - -\family typewriter -fixed_m1 -\family default - Set to -\begin_inset Formula $1$ -\end_inset - - if there is only one -\begin_inset Formula $M_{1}$ -\end_inset - - in the binary grid, otherwise keep set to zero. -\emph on - -\begin_inset space ~ -\end_inset - -Please use the flexigrid instead of this option. -\end_layout - -\begin_layout Description - -\family typewriter -imf1 -\family default - The primary star initial mass, -\begin_inset Formula $M$ -\end_inset - - or -\begin_inset Formula $M_{1}$ -\end_inset - -, function/distribution, usually -\begin_inset Quotes eld -\end_inset - -ktg93 -\begin_inset Quotes erd -\end_inset - -. - See -\emph on -IMF.pm -\emph default - (Section -\begin_inset space ~ -\end_inset - - -\begin_inset CommandInset ref -LatexCommand ref -reference "sec:initial-dists" - -\end_inset - -). -\emph on - -\begin_inset space ~ -\end_inset - -Please use the flexigrid instead of this option. -\end_layout - -\begin_layout Description - -\family typewriter -imf2 -\family default - The secondary star mass (or mass ratio -\begin_inset Formula $q=M_{2}/M_{1}$ -\end_inset - -) function/distribution, usually -\begin_inset Quotes eld -\end_inset - -flatq -\begin_inset Quotes erd -\end_inset - -. - See -\emph on -IMF.pm -\emph default - (Section -\begin_inset space ~ -\end_inset - - -\begin_inset CommandInset ref -LatexCommand ref -reference "sec:initial-dists" - -\end_inset - -). -\emph on - -\begin_inset space ~ -\end_inset - -Please use the flexigrid instead of this option. -\end_layout - -\begin_layout Description - -\family typewriter -imf2_exponent -\family default - The exponent in the secondary star -\begin_inset Formula $q$ -\end_inset - - distribution if it is a power law (0 is flat). -\emph on - -\begin_inset space ~ -\end_inset - -Please use the flexigrid instead of this option. -\end_layout - -\begin_layout Description - -\family typewriter -imf2_minm -\family default - The minimum mass in the secondary star -\begin_inset Formula $q$ -\end_inset - - distribution, usually -\begin_inset Formula $0.1$ -\end_inset - -( -\begin_inset Formula $\mathrm{M}_{\odot}$ -\end_inset - -). -\emph on - -\begin_inset space ~ -\end_inset - -Please use the flexigrid instead of this option. -\end_layout - -\begin_layout Description - -\family typewriter -imf2_maxm -\family default - The maximum mass in the secondary star -\begin_inset Formula $q$ -\end_inset - - distribution, usually -\begin_inset Quotes eld -\end_inset - -auto -\begin_inset Quotes erd -\end_inset - - (which means use -\begin_inset Formula $M_{1}$ -\end_inset - - as the maximum). - You can, alternatively, set this to an actual number, in which case you'll - be running a square ( -\begin_inset Formula $M_{2}\leq M_{2,\mathrm{max}}$ -\end_inset - -) rather than triangular ( -\begin_inset Formula $M_{2}\leq M_{1}$ -\end_inset - -) grid so you'll be needlessly repeating systems and reducing the grid resolutio -n in -\begin_inset Formula $M_{2}$ -\end_inset - -. -\emph on - -\begin_inset space ~ -\end_inset - -Please use the flexigrid instead of this option. -\end_layout - -\begin_layout Description - -\family typewriter -imf2_minq -\family default - The minimum -\begin_inset Formula $q$ -\end_inset - - value allowed on the grid, usually -\family typewriter -undef -\family default - and ignored (overrides -\family typewriter -imf2_minq -\family default -). -\emph on - -\begin_inset space ~ -\end_inset - -Please use the flexigrid instead of this option. -\end_layout - -\begin_layout Description - -\family typewriter -imf2_maxq -\family default - The maximum -\begin_inset Formula $q$ -\end_inset - - value allowed on the grid, usually -\begin_inset Formula $1$ -\end_inset - -. - (Overrides -\family typewriter -imf2_maxm -\family default -) -\emph on - -\begin_inset space ~ -\end_inset - -Please use the flexigrid instead of this option. -\end_layout - -\begin_layout Description - -\family typewriter -lastargs -\family default - Very similar to log_args but at a slightly different place in the code. - Should be avoided, use -\family typewriter -log_args -\family default - instead. -\end_layout - -\begin_layout Description - -\family typewriter -libpath -\family default - Path to libraries to be included in the calling of the -\emph on -binary_c/nucsyn -\emph default - executable. - This harks back to the days when -\emph on -binary_c/nucsyn -\emph default - was built as a set of shared libraries. - These days it is built statically, so libpath is usually an empty string - (and hence is ignored). -\end_layout - -\begin_layout Description - -\family typewriter -log_args -\family default - If this is set to -\begin_inset Formula $1$ -\end_inset - - then the arguments passed to -\emph on -binary_c/nucsyn -\emph default - are saved in a file in -\family typewriter -/tmp/ -\family default - (usually -\family typewriter -/tmp/binary_c-args -\family default - or similar, with separate files for each thread). - This is very useful when the grid freezes as you can immediately see which - stellar system has caused the problem and then rerun it manually. - -\end_layout - -\begin_layout Description - -\family typewriter -log_normal_median -\family default - The median value of a log-normal mass distribution (see -\emph on -IMF -\emph default -.pm, Section -\begin_inset space ~ -\end_inset - - -\begin_inset CommandInset ref -LatexCommand ref -reference "sec:initial-dists" - -\end_inset - -). - -\emph on - -\begin_inset space ~ -\end_inset - -Please use the flexigrid instead of this option. -\end_layout - -\begin_layout Description - -\family typewriter -log_normal_dispersion -\family default - The dispersion of a log-normal mass distribution (see -\emph on -IMF -\emph default -.pm, Section -\begin_inset space ~ -\end_inset - - -\begin_inset CommandInset ref -LatexCommand ref -reference "sec:initial-dists" - -\end_inset - -). - -\emph on - Please use the flexigrid instead of this option. -\end_layout - -\begin_layout Description - -\family typewriter -masshash_function -\family default - This can be set to an alternative function to make the -\begin_inset Formula $M$ -\end_inset - - or -\begin_inset Formula $M_{1}$ -\end_inset - - -\family typewriter -%masshash -\family default -. - (The default is -\family typewriter -undef -\family default - so it is ignored.) -\emph on -Please use the flexigrid instead of this option. -\end_layout - -\begin_layout Description - -\family typewriter -mmax -\family default - The maximum mass at which the single -\begin_inset Formula $M$ -\end_inset - - or primary mass -\begin_inset Formula $M_{1}$ -\end_inset - - grid ends (in -\begin_inset Formula $M_{\odot}$ -\end_inset - -, default -\begin_inset Formula $80$ -\end_inset - -). - -\family typewriter - -\family default -\emph on -Please use the flexigrid instead of this option. -\end_layout - -\begin_layout Description - -\family typewriter -m2max -\family default - The maximum mass at which the secondary mass -\begin_inset Formula $M_{2}$ -\end_inset - - grid ends (in -\begin_inset Formula $M_{\odot}$ -\end_inset - -, default -\begin_inset Formula $80$ -\end_inset - -). - -\emph on -Please use the flexigrid instead of this option. -\end_layout - -\begin_layout Description - -\family typewriter -mmin -\family default - The minimum mass at which the single -\begin_inset Formula $M$ -\end_inset - - or primary -\begin_inset Formula $M_{1}$ -\end_inset - - mass grid begins (in -\begin_inset Formula $M_{\odot}$ -\end_inset - -, default -\begin_inset Formula $0.1$ -\end_inset - -). - -\emph on -Please use the flexigrid instead of this option. -\end_layout - -\begin_layout Description - -\family typewriter -m2min -\family default - The minimum mass at which the secondary mass -\begin_inset Formula $M_{2}$ -\end_inset - - grid begins (in -\begin_inset Formula $M_{\odot}$ -\end_inset - -, default -\begin_inset Formula $0.1$ -\end_inset - -). - -\emph on -Please use the flexigrid instead of this option. -\end_layout - -\begin_layout Description - -\family typewriter -m2zoom -\family default - If set to 1 then for -\begin_inset Formula $M_{2}/M_{1}=q>$ -\end_inset - -m2q_zoom_q the resolution is set to m2q_zoom_n. - This can be used to increase the number of stars in the high -\begin_inset Formula $q$ -\end_inset - -. - -\emph on -Please use the flexigrid instead of this option. -\end_layout - -\begin_layout Description - -\family typewriter -necc -\family default - The number of stars in the eccentricity -\begin_inset Formula $e$ -\end_inset - - dimension of the grid. - If -\begin_inset Formula $1$ -\end_inset - - then the eccentricity is constant (usually zero, depends on the -\family typewriter -bse_option -\family default -). - -\emph on - Please use the flexigrid instead of this option. -\end_layout - -\begin_layout Description - -\family typewriter -newline -\family default - If -\family typewriter -vb=1 -\family default - then the value of this option is used as the end of line character. - You can use either -\family typewriter - -\begin_inset Quotes eld -\end_inset - - -\backslash -x0d -\begin_inset Quotes erd -\end_inset - - -\family default - (just a carriage return) or -\family typewriter - -\begin_inset Quotes eld -\end_inset - - -\backslash -n -\begin_inset Quotes erd -\end_inset - - -\family default - which is the carriage return with a line feed (the usual concept of -\begin_inset Quotes eld -\end_inset - -new line -\begin_inset Quotes erd -\end_inset - -). -\end_layout - -\begin_layout Description - -\family typewriter -nice -\family default - A string containing the nice command used to run -\shape italic -binary_c/nucsyn -\shape default -. - Usually no nice is used, so this is ' -\family typewriter -nice -n +0 -\family default -'. - You can leave this as it is and run ' -\family typewriter -nice grid.pl -\family default -' if you want the whole grid to be -\begin_inset Quotes eld -\end_inset - -niced -\begin_inset Quotes erd -\end_inset - -. -\end_layout - -\begin_layout Description - -\family typewriter -nmlow -\family default - The grid uses the values in the -\family typewriter -@mlist -\family default - between index -\family typewriter -nmlow -\family default - and -\family typewriter -nmhigh -\family default -. - If zero then all stars are used. -\end_layout - -\begin_layout Description - -\family typewriter -nmhigh -\family default - See -\family typewriter -nmlow -\family default -. -\end_layout - -\begin_layout Description - -\family typewriter -nm -\family default - The number of single star masses -\begin_inset Formula $M$ -\end_inset - - used in the grid. -\emph on - -\begin_inset space ~ -\end_inset - -Please use the flexigrid instead of this option. -\end_layout - -\begin_layout Description - -\family typewriter -nm1 -\family default - The number of primary star masses -\begin_inset Formula $M_{1}$ -\end_inset - - used in the grid. -\emph on - -\begin_inset space ~ -\end_inset - -Please use the flexigrid instead of this option. -\end_layout - -\begin_layout Description - -\family typewriter -nmod -\family default - When -\family typewriter -vb=1 -\family default - information on the grid is output every -\family typewriter -nmod -\family default - models or, if -\family typewriter -nmod -\family default - is zero, once every second. -\end_layout - -\begin_layout Description - -\family typewriter -nper -\family default - The number of stars in the period -\begin_inset Formula $P$ -\end_inset - - dimension. -\emph on - -\begin_inset space ~ -\end_inset - -Please use the flexigrid instead of this option. -\end_layout - -\begin_layout Description - -\family typewriter -nsep -\family default - The number of stars in the separation -\begin_inset Formula $a$ -\end_inset - - dimension. -\emph on - -\begin_inset space ~ -\end_inset - -Please use the flexigrid instead of this option. -\end_layout - -\begin_layout Description - -\family typewriter -parse_bse_function_pointer -\family default - In your grid script you need to define a subroutine (also known as a function) - to be used for data parsing. - Usually this is called -\family typewriter -parse_bse -\family default -. - and is set with a line in -\emph on -grid-xxx.pl -\emph default - like this: -\begin_inset Newline newline -\end_inset - - -\family typewriter -$binary_grid::grid_options{'parse_bse_function_pointer'}= -\backslash -&parse_bse; -\family default - -\begin_inset Newline newline -\end_inset - -You have to provide a pointer to this function in order that the grid software - knows where to send the output of -\emph on -binary_c/nucsyn -\emph default -. -\end_layout - -\begin_layout Description - -\family typewriter -period_dist -\family default - You may want to use a period-based initial distribution instead of the - default separation distribution, e.g. - for the -\begin_inset CommandInset citation -LatexCommand citet -key "1991A&A...248..485D" - -\end_inset - - initial distribution. - In this case set -\family typewriter -sepdist -\family default - to -\family typewriter - -\begin_inset Quotes eld -\end_inset - -period -\begin_inset Quotes erd -\end_inset - - -\family default - and choose -\family typewriter -period_dist= -\begin_inset Quotes erd -\end_inset - -gaussian -\begin_inset Quotes erd -\end_inset - - -\family default -. - (See -\emph on -IMF.pm -\emph default - for options.) Note that a Gaussian distribution requires a given minimum - and maximum period to be specified (in order that it normalises to -\begin_inset Formula $1$ -\end_inset - -). -\end_layout - -\begin_layout Description - -\family typewriter -period_dist_log_min -\family default - Minimum log period ( -\begin_inset Formula $\log_{10}P$ -\end_inset - -) of the initial distribution in days. - -\emph on - -\begin_inset space ~ -\end_inset - -Please use the flexigrid instead of this option. -\end_layout - -\begin_layout Description - -\family typewriter -period_dist_log_max -\family default - Maximum log period ( -\begin_inset Formula $\log_{10}P$ -\end_inset - -) of the initial distribution in days. -\emph on - -\begin_inset space ~ -\end_inset - -Please use the flexigrid instead of this option. -\end_layout - -\begin_layout Description - -\family typewriter -period_dist_mean_log -\family default - (log) Mean of the Gaussian period distribution in days. -\emph on - -\begin_inset space ~ -\end_inset - -Please use the flexigrid instead of this option. -\end_layout - -\begin_layout Description - -\family typewriter -period_dist_sigma -\family default - The width of the period distribution Gaussian (log days). -\emph on - -\begin_inset space ~ -\end_inset - -Please use the flexigrid instead of this option. -\end_layout - -\begin_layout Description - -\family typewriter -period_log_min -\family default - The minimum log period (days) in the period grid (not the initial distribution). -\emph on - -\begin_inset space ~ -\end_inset - -Please use the flexigrid instead of this option. -\end_layout - -\begin_layout Description - -\family typewriter -period_log_max -\family default - The maximum log period (days) in the period grid (not the initial distribution). -\emph on - -\begin_inset space ~ -\end_inset - -Please use the flexigrid instead of this option. -\end_layout - -\begin_layout Description - -\family typewriter -plaw_m0 -\family default - Minimum mass of the three-part power law -\begin_inset CommandInset citation -LatexCommand citet* -key "KTG1993MNRAS-262-545K" - -\end_inset - - initial mass function ( -\begin_inset Formula $0.1\,\mathrm{M}_{\odot}$ -\end_inset - -). -\emph on - -\begin_inset space ~ -\end_inset - -Please use the flexigrid instead of this option. -\end_layout - -\begin_layout Description - -\family typewriter -plaw_m1 -\family default - Mass break 1 of the three-part power law -\begin_inset CommandInset citation -LatexCommand citet* -key "KTG1993MNRAS-262-545K" - -\end_inset - - initial mass function ( -\begin_inset Formula $0.5\,\mathrm{M}_{\odot}$ -\end_inset - -). -\emph on - -\begin_inset space ~ -\end_inset - -Please use the flexigrid instead of this option. -\end_layout - -\begin_layout Description - -\family typewriter -plaw_m2 -\family default - Mass break 2 of the three-part power law -\begin_inset CommandInset citation -LatexCommand citet* -key "KTG1993MNRAS-262-545K" - -\end_inset - - initial mass function ( -\begin_inset Formula $1.0\,\mathrm{M}_{\odot}$ -\end_inset - -). -\emph on - -\begin_inset space ~ -\end_inset - -Please use the flexigrid instead of this option. -\end_layout - -\begin_layout Description - -\family typewriter -plaw_mmax -\family default - Maximum mass of the three-part power law -\begin_inset CommandInset citation -LatexCommand citet* -key "KTG1993MNRAS-262-545K" - -\end_inset - - initial mass function ( -\begin_inset Formula $80\,\mathrm{M}_{\odot}$ -\end_inset - -). -\emph on - -\begin_inset space ~ -\end_inset - -Please use the flexigrid instead of this option. -\end_layout - -\begin_layout Description - -\family typewriter -plaw_p -\family default - Slope of the (single) power-law initial mass function (e.g. - -\begin_inset Formula $-2.35$ -\end_inset - - for Salpeter). -\emph on - -\begin_inset space ~ -\end_inset - -Please use the flexigrid instead of this option. -\end_layout - -\begin_layout Description - -\family typewriter -plaw_p1 -\family default - Slope 1 of the three-part power law -\begin_inset CommandInset citation -LatexCommand citet* -key "KTG1993MNRAS-262-545K" - -\end_inset - - initial mass function ( -\begin_inset Formula $-1.3$ -\end_inset - -). -\emph on - -\begin_inset space ~ -\end_inset - -Please use the flexigrid instead of this option. -\end_layout - -\begin_layout Description - -\family typewriter -plaw_p2 -\family default - Slope 2 of the three-part power law -\begin_inset CommandInset citation -LatexCommand citet* -key "KTG1993MNRAS-262-545K" - -\end_inset - - initial mass function ( -\begin_inset Formula $-2.2$ -\end_inset - -). -\emph on - -\begin_inset space ~ -\end_inset - -Please use the flexigrid instead of this option. -\end_layout - -\begin_layout Description - -\family typewriter -plaw_p3 -\family default - Slope 3 of the three-part power law -\begin_inset CommandInset citation -LatexCommand citet* -key "KTG1993MNRAS-262-545K" - -\end_inset - - initial mass function ( -\begin_inset Formula $-2.7$ -\end_inset - -). -\emph on - -\begin_inset space ~ -\end_inset - -Please use the flexigrid instead of this option. -\end_layout - -\begin_layout Description - -\family typewriter -prob1 -\family default - If this is set to -\begin_inset Formula $1$ -\end_inset - - then all probabilities are -\begin_inset Formula $1.0$ -\end_inset - - (i.e. - -\family typewriter -calc_prob -\family default - is ignored). -\end_layout - -\begin_layout Description - -\family typewriter -prog -\family default - The -\emph on -binary_c/nucsyn -\emph default - executable name, usually ' -\family typewriter -binary_c -\family default -'. - See also -\family typewriter -rootpath -\family default -. -\end_layout - -\begin_layout Description - -\family typewriter -progenitor -\family default - Not really a grid option, but stores the system information ( -\begin_inset Formula $M$ -\end_inset - - or -\begin_inset Formula $M_{1}$ -\end_inset - -, -\begin_inset Formula $M_{2}$ -\end_inset - -, -\begin_inset Formula $a$ -\end_inset - -, -\begin_inset Formula $P$ -\end_inset - -, -\begin_inset Formula $e$ -\end_inset - -, -\begin_inset Formula $p$ -\end_inset - - etc.) -- useful for debugging or logging. -\end_layout - -\begin_layout Description - -\family typewriter -progenitor_hash -\family default - As progenitor but stores each item in a hash. -\end_layout - -\begin_layout Description - -\family typewriter -qmax -\family default - The maximum value of -\begin_inset Formula $q=M_{1}/M_{2}$ -\end_inset - - allowed in the grid, usually -\begin_inset Formula $1$ -\end_inset - -. -\end_layout - -\begin_layout Description - -\family typewriter -q_mean -\family default - When using a -\family typewriter -imf2= -\begin_inset Quotes erd -\end_inset - -gaussian -\begin_inset Quotes erd -\end_inset - - -\family default - the secondary mass ratio -\begin_inset Formula $q$ -\end_inset - - distribution is a Gaussian with centre -\family typewriter -q_mean -\family default - and width -\family typewriter -q_sigma -\family default -. - Useful for setting up a secondary mass distribution according to -\begin_inset CommandInset citation -LatexCommand citet -key "1991A&A...248..485D" - -\end_inset - -. - See also Section -\begin_inset space ~ -\end_inset - - -\begin_inset CommandInset ref -LatexCommand ref -reference "sec:initial-dists" - -\end_inset - -. -\emph on - -\begin_inset space ~ -\end_inset - -Please use the flexigrid instead of this option. -\end_layout - -\begin_layout Description - -\family typewriter -q_sigma -\family default - See -\family typewriter -q_mean -\family default -. -\emph on - -\begin_inset space ~ -\end_inset - -Please use the flexigrid instead of this option. -\end_layout - -\begin_layout Description - -\family typewriter -ref_tick_file -\family default - File from which timer (tick count) information is loaded. - See -\family typewriter -tick_counts -\family default -. - -\emph on - -\begin_inset space ~ -\end_inset - -Please use the flexigrid instead of this option -- -\emph default - -\begin_inset space ~ -\end_inset - -tick counts were used in the old -\family typewriter -threaded_grid -\family default - but are no longer required -\emph on -. -\end_layout - -\begin_layout Description - -\family typewriter -repeat -\family default - The number of times -\family typewriter -tbse() -\family default - is called for each grid point, default is -\begin_inset Formula $1$ -\end_inset - -. - This is useful for increasing the resolution in situations where Monte-Carlo - methods are used such as the random supernova or white dwarf kicks. -\end_layout - -\begin_layout Description - -\family typewriter -rootpath -\family default - The directory in which the -\emph on -binary_c/nucsyn -\emph default - code source and executable reside. - See also -\family typewriter -prog -\family default -. -\end_layout - -\begin_layout Description - -\family typewriter -runtime_function_pointer -\family default - A custom function which returns the time it takes (in CPU seconds) to run - a star of a given mass, used to split the single/primary mass range into - chunks and hence for load balancing in the threaded grid. - This is the old way of doing things, newer grids should use the tick counts - to time the runs of a test grid. - -\emph on - -\begin_inset space ~ -\end_inset - -Please use the flexigrid instead of this option. -\end_layout - -\begin_layout Description - -\family typewriter -runtime_lowmass -\family default - The runtime for a low-mass star that would otherwise never be run. - -\begin_inset Newline newline -\end_inset - -See -\family typewriter -runtime_function_pointer -\family default -. -\emph on - -\begin_inset space ~ -\end_inset - -Please use the flexigrid instead of this option. -\end_layout - -\begin_layout Description - -\family typewriter -secondary_mass_generator_function -\family default - Function to generate the list of secondary masses. - Usually this is set to the default function -\family typewriter - -\backslash -&populate_m2list -\family default -. -\emph on - -\begin_inset space ~ -\end_inset - -Please use the flexigrid instead of this option. -\end_layout - -\begin_layout Description - -\family typewriter -sepdist -\family default - The initial separation distribution, usually -\family typewriter - -\begin_inset Quotes eld -\end_inset - -flat -\begin_inset Quotes erd -\end_inset - - -\family default -, see -\emph on -IMF.pm -\emph default - (Section -\begin_inset space ~ -\end_inset - - -\begin_inset CommandInset ref -LatexCommand ref -reference "sec:initial-dists" - -\end_inset - -). -\emph on - -\begin_inset space ~ -\end_inset - -Please use the flexigrid instead of this option. -\end_layout - -\begin_layout Description - -\family typewriter -sepdist_exponent -\family default - If the separation distribution is a power law, the exponent is given by - this option. -\emph on - -\begin_inset space ~ -\end_inset - -Please use the flexigrid instead of this option. -\end_layout - -\begin_layout Description - -\family typewriter -sepdist_min -\family default - The minimum initial separation (solar radii) in the initial separation - distribution (but -\emph on -not -\emph default - the grid). -\emph on - -\begin_inset space ~ -\end_inset - -Please use the flexigrid instead of this option. -\end_layout - -\begin_layout Description - -\family typewriter -sepdist_max -\family default - The maximum initial separation (solar radii) in the initial separation - distribution (but -\emph on -not -\emph default - the grid). -\emph on - -\begin_inset space ~ -\end_inset - -Please use the flexigrid instead of this option. -\end_layout - -\begin_layout Description - -\family typewriter -sepmax -\family default - The maximum separation -\begin_inset Formula $a$ -\end_inset - - of the grid (solar radii). - -\emph on - -\begin_inset space ~ -\end_inset - -Please use the flexigrid instead of this option. -\end_layout - -\begin_layout Description - -\family typewriter -sepmin -\family default - The minimum separation -\begin_inset Formula $a$ -\end_inset - - of the grid (solar radii). -\emph on - -\begin_inset space ~ -\end_inset - -Please use the flexigrid instead of this option. -\end_layout - -\begin_layout Description - -\family typewriter -stellar_lifetime_table_nm -\family default - When the time adaptive mass grid is used (see -\family typewriter -time_adaptive_mass_grid -\family default -) a function is required to convert from stellar mass to stellar lifetimes. - This is interpolated from a (small) table of (single-star) models run at - the beginning of the grid. - -\family typewriter -stellar_lifetime_table_nm -\family default - is (approximately) the number of stars in this table, although -\family typewriter -time_adaptive_mass_grid_nlow _mass_stars -\family default - is the number of stars at low-mass in the table (because this probably - requires extra resolution due to -\begin_inset Formula $t\sim M^{3}$ -\end_inset - -) and there can also be extra stars around the helium flash lifetime (see - -\family typewriter -extra_flash_resolution -\family default -). -\end_layout - -\begin_layout Description - -\family typewriter -test -\family default - If test is set to 1 then the grid is run without calling tbse for each - system. - This is useful for testing the grid or calculating the total mass in stars. -\end_layout - -\begin_layout Description - -\family typewriter -test_grid_function_pointer -\family default - A pointer to a function which is called for each star in a test grid. - Ignored if -\family typewriter -undef -\family default -. -\end_layout - -\begin_layout Description - -\family typewriter -test_grid_mmax -\family default - The maximum single/primary mass used when running the test grid. -\end_layout - -\begin_layout Description - -\family typewriter -test_grid_mmin -\family default - The minimum single/primary mass used when running the test grid. -\end_layout - -\begin_layout Description - -\family typewriter -test_grid_only -\family default - If 1 then the code exits immediately after running the test grid. -\end_layout - -\begin_layout Description - -\family typewriter -thread_max_freeze_time_before_warning -\family default - The maximum time a thread loops its calls to -\family typewriter -tbse() -\family default - before a warning is issued (seconds, default 10). -\end_layout - -\begin_layout Description - -\family typewriter -thread_num -\family default - Not really an option, but stores the thread number of the current grid, - or -\family typewriter -undef -\family default - if threads are not being used. -\end_layout - -\begin_layout Description - -\family typewriter -thread_precreate_function_pointer -\family default - A pointer to a function to be called just before -\family typewriter -threads->create -\family default - is used to start a thread. - Ignored if -\family typewriter -undef -\family default -. -\end_layout - -\begin_layout Description - -\family typewriter -thread_prejoin_function_pointer -\family default - A pointer to a function called just before a thread is -\family typewriter -join -\family default -ed. - Ignored if -\family typewriter -undef -\family default -. -\end_layout - -\begin_layout Description - -\family typewriter -thread_presleep -\family default -A thread waits for this length of time (in seconds) before it starts in - order that all other threads have time to start before any output is logged - to the screen. - As such this is just to keep output pretty and should be small (default - 1 second). -\end_layout - -\begin_layout Description - -\family typewriter -thread_postjoin_function_pointer -\family default - A pointer to a function called just after a thread is -\family typewriter -join -\family default -ed. - Ignored if -\family typewriter -undef -\family default -. -\end_layout - -\begin_layout Description - -\family typewriter -thread_postrun_function_pointer -\family default - A pointer to a function to be called just after a -\family typewriter -thread->create -\family default - call (and just after -\family typewriter -$@ -\family default - is checked for a thread-creation error). - Ignored if -\family typewriter -undef -\family default -. -\end_layout - -\begin_layout Description - -\family typewriter -threads_entry_fun -\family default - A pointer to a function called from inside a thread just before grid() - is called. -\end_layout - -\begin_layout Description - -\family typewriter -threads_flush_fun -\family default - A pointer to a function called from inside a thread just after grid() returns. -\end_layout - -\begin_layout Description - -\family typewriter -threads_join_function_pointer -\family default - When using a threaded grid you have to define a subroutine (also known - as a function) pointer which points to the function to be called after - each thread have finished. - This function is responsible for -\begin_inset Quotes eld -\end_inset - -joining -\begin_inset Quotes erd -\end_inset - - the threads, which means it collects the results from the thread and adds - them to the global results. - This is usually a function called -\family typewriter -join_thread -\family default - and is set with a line in grid-xxx.pl similar to: -\begin_inset Newline newline -\end_inset - - -\family typewriter -$binary_grid::grid_options{'threads_join_function_pointer'}= -\backslash -&join_thread; -\end_layout - -\begin_layout Description - -\family typewriter -threads_stack_size -\family default - The stack size (in MBytes) for each of the Perl threads launched when -\family typewriter - -\begin_inset Newline newline -\end_inset - -threaded_grid -\family default - is used (see Section -\begin_inset space ~ -\end_inset - - -\begin_inset CommandInset ref -LatexCommand ref -reference "sec:threads" - -\end_inset - -). - Default is 32 (MBytes). -\end_layout - -\begin_layout Description - -\family typewriter -tick_counts -\family default - When threaded grids are used, the time it takes to run a system can be - computed using the tick_counts method. - With sufficiently accurate timing the load of each thread can be calculated - in advance and the mass grid split up accordingly. - This currently works only on CPUs which support the -\emph on -binary_c/nucsyn -\emph default - code options (see -\family typewriter -code_options.h -\family default -) -\family typewriter -RDTSC -\family default - and -\family typewriter -RDTSC_TIMER_PER_SYSTEM -\family default - (i.e. - Intel/AMD and compatible x86 architectures). - Note that if -\family typewriter -tick_counts -\family default - is 1 then tick clounts are merely saved, to -\emph on -use -\emph default -them you have to set -\family typewriter -use_ref_tick_counts -\family default - to 1. - This means you can rerun the grid without rerunning the tick count test - grid (instead the file is used, -\begin_inset Newline newline -\end_inset - -see -\family typewriter -tick_counts_file -\family default -). -\end_layout - -\begin_layout Description - -\family typewriter -tick_counts_file -\family default - File in which the timer (tick count) information is saved. -\end_layout - -\begin_layout Description - -\family typewriter -time_adaptive_mass_grid -\family default - This activates the time-adaptive mass grid such that the initial single/primary - masses -\begin_inset Formula $M_{1}$ -\end_inset - - are chosen to given equal -\begin_inset Quotes eld -\end_inset - -output -\begin_inset Quotes erd -\end_inset - - per unit time. - In this case -\begin_inset Quotes eld -\end_inset - -output -\begin_inset Quotes erd -\end_inset - - means stellar yield (i.e. - mass ejected) but this mostly comes at the end of the stellar evolution, - so the -\family typewriter -time_adaptive_mass_grid -\family default - can be used for other things such as supernovae which also occur then. - See the other -\family typewriter -time_adaptive_mass_grid -\family default - options and -\family typewriter -stellar_lifetime_table_nm -\family default -. -\end_layout - -\begin_layout Description - -\family typewriter -time_adaptive_mass_grid_step -\family default - The step in time -\begin_inset Formula $\Delta t$ -\end_inset - - which is converted to a corresponding -\begin_inset Formula $\Delta M_{1}$ -\end_inset - - in the -\family typewriter -time_adaptive_mass_grid -\family default - (see previous). -\end_layout - -\begin_layout Description - -\family typewriter -time_adaptive_mass_grid_log10_time -\family default - If this is true then instead of -\begin_inset Formula $\Delta M_{1}$ -\end_inset - - giving equal spacing in time -\begin_inset Formula $t$ -\end_inset - - instead equal spacing is calculated in -\begin_inset Formula $\log t$ -\end_inset - -. -\end_layout - -\begin_layout Description - -\family typewriter -time_adaptive_mass_grid_log10_step -\family default - -\begin_inset Formula $\Delta\log t$ -\end_inset - - for the previous entry. -\end_layout - -\begin_layout Description - -\family typewriter -time_adaptive_mass_grid_nlow_mass_stars -\family default - The number of low-mass stars run in the test grid which calculates stellar - lifetimes. - See -\family typewriter -stellar_lifetime_table_nm -\family default -. -\end_layout - -\begin_layout Description - -\family typewriter -timeout -\family default - When possible the grid sets an alarm (a Linux/UNIX signal) which means - that warnings are given and perhaps the grid stopped after -\family typewriter -timeout -\family default - seconds. - Set to zero to ignore, usually 30 is enough. - This assumes your -\emph on - binary_c/nucsyn -\emph default - process takes less than -\family typewriter -timeout -\family default - seconds to run a system so if you have problems with this please check - your system to make sure you have the CPU time you need. -\end_layout - -\begin_layout Description - -\family typewriter -use_ref_tick_counts -\family default - Switches on the use of tick count information for load balancing. - See -\family typewriter -tick_counts -\family default -. -\emph on - -\begin_inset space ~ -\end_inset - -Please use the flexigrid instead of this option. -\end_layout - -\begin_layout Description - -\family typewriter -vb -\family default - Verbosity level. - With -\family typewriter -vb=1 -\family default - you get some output about the grid, i.e. - the number of stars run, the number to go, the current -\begin_inset Formula $M$ -\end_inset - -, or -\begin_inset Formula $M_{1}$ -\end_inset - -, -\begin_inset space ~ -\end_inset - - -\begin_inset Formula $M_{2}$ -\end_inset - - and -\begin_inset Formula $a$ -\end_inset - -, an estimate of the time taken, time remaining and the time at which the - grid is expected to finish. - You may also get information about memory usage (if available). - Make sure your terminal window is quite wide to accommodate the information! - If -\family typewriter -vb=2 -\family default - you will get additional information about each system. - This is very useful for determining which stellar system is causing the - code to freeze and/or crash. - See also -\family typewriter -nmod -\family default -, -\family typewriter -colour -\family default - and -\family typewriter -log_args -\family default -. - Some verbose logging is only switched on if -\family typewriter -vb=3 -\family default -, although this should be considered experimental. -\end_layout - -\begin_layout Standard -\begin_inset Newpage pagebreak -\end_inset - - -\end_layout - -\begin_layout Section -Flexigrid -\end_layout - -\begin_layout Standard -\begin_inset CommandInset label -LatexCommand label -name "sec:flexigrid" - -\end_inset - -As of summer 2011, the -\begin_inset Quotes eld -\end_inset - -flexigrid -\begin_inset Quotes erd -\end_inset - - was developed. - This is an attempt to replace much of the old grid framework with a new, - dynamic set of instructions which are much more flexible. - The key concepts are the following: -\end_layout - -\begin_layout Itemize -When a flexigrid is run, it sets up -\begin_inset Formula $n$ -\end_inset - - threads each of which runs a star (or group of stars) at a time. - This is done -\emph on -as soon as a thread is free -\emph default - so load balancing is as good as it is possible to be. -\end_layout - -\begin_layout Itemize -Flexigrid sets up its -\begin_inset Formula $M_{1}-M_{2}-a$ -\end_inset - - etc. - grid -\emph on -dynamically -\emph default -. - It does this by writing the grid code itself and then compiling it with - Perl's -\emph on -eval -\emph default - command. - This means it is truly flexible, you can add or remove -\emph on -any variable you like -\emph default - to the grid and do not have to write any new code in the -\emph on -binary_grid -\emph default - module! -\end_layout - -\begin_layout Itemize -The standard version of flexigrid uses a multithreaded, local binary_c model. - However, in development is a binary_c-daemon which distributes the load - across remote machines on a network. -\end_layout - -\begin_layout Itemize -The grid spacing is now given by a Perl function and hence is -\emph on -not -\emph default - fixed. - -\end_layout - -\begin_layout Itemize -Probabilities are calculated more efficiently in an attempt to phase out - the -\emph on -IMF -\emph default - module in favour of the -\emph on -distribution_functions -\emph default - module. -\end_layout - -\begin_layout Subsection -Setup in your grid script -\end_layout - -\begin_layout Standard -You need to do two things: -\end_layout - -\begin_layout Enumerate -Call -\family typewriter -flexigrid( -\emph on -n -\emph default -); -\family default - instead of -\family typewriter -threaded_grid( -\emph on -n -\emph default -); -\end_layout - -\begin_layout Enumerate -Set up the grid in the -\family typewriter -grid_options -\family default -hash -\end_layout - -\begin_layout Standard -The call to -\family typewriter -flexigrid -\family default - is simple enough, where the argument is (as with -\family typewriter -threaded_grid -\family default -) the number of threads. - Next, some variables must be set in the grid_options hash in order that - the grid can be created. -\end_layout - -\begin_layout Subsubsection -Grid variables: 1D example -\end_layout - -\begin_layout Standard -Setting up which variables you use is best defined by example. - Let's start with -\begin_inset Formula $M_{1}$ -\end_inset - - which you will usually require. - First, define the grid resolution as $n -\begin_inset Formula $\times$ -\end_inset - -$n -\begin_inset Formula $\times$ -\end_inset - -$n (here -\begin_inset Formula $10\times10\times10$ -\end_inset - -) -\end_layout - -\begin_layout Standard - -\family typewriter -$n=10; -\family default - -\begin_inset Newline newline -\end_inset - -Next, set up the variable number corresponding to the grid variable. - Each grid variable must have a unique number, starting with 0 and working - upward. - -\end_layout - -\begin_layout Standard - -\family typewriter -my $nvar=0; -\family default - -\begin_inset Newline newline -\end_inset - - -\begin_inset Newline newline -\end_inset - -Now use an -\emph on -anonymous hash -\emph default - in the grid option {'flexigrid'}{'grid variable '.$nvar} to give the options: -\begin_inset Newline newline -\end_inset - - -\end_layout - -\begin_layout Standard - -\family typewriter -\begin_inset Box Frameless -position "t" -hor_pos "c" -has_inner_box 1 -inner_pos "t" -use_parbox 0 -use_makebox 0 -width "100col%" -special "none" -height "1in" -height_special "totalheight" -status open - -\begin_layout Plain Layout - -\family typewriter -# Mass 1 -\end_layout - -\begin_layout Plain Layout - -\family typewriter -$binary_grid::grid_options{'flexigrid'}{'grid variable '.$nvar++}= -\end_layout - -\begin_layout Plain Layout - -\family typewriter -{ -\end_layout - -\begin_layout Plain Layout - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -'name'=>'lnm1', -\end_layout - -\begin_layout Plain Layout - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -'longname'=>'Primary_Mass', -\end_layout - -\begin_layout Plain Layout - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -'range' => ["log($binary_grid::grid_options{'mmin'})", -\end_layout - -\begin_layout Plain Layout - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -"log($binary_grid::grid_options{'mmax'})"], -\end_layout - -\begin_layout Plain Layout - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -'resolution'=>$n, -\end_layout - -\begin_layout Plain Layout - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -'spacingfunc'=>"const(log($binary_grid::grid_options{'mmin'}),log($binary_grid:: -grid_options{'mmax'}),$n)", -\end_layout - -\begin_layout Plain Layout - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -'precode'=>"my -\backslash -$m1=exp( -\backslash -$lnm1);my -\backslash -$eccentricity=0.0;", -\end_layout - -\begin_layout Plain Layout - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -'probdist'=>"ktg93( -\backslash -$m1)* -\backslash -$m1", -\end_layout - -\begin_layout Plain Layout - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -'dphasevol'=>" -\backslash -$dlnm1 " -\end_layout - -\begin_layout Plain Layout - -\family typewriter -}; -\end_layout - -\end_inset - - -\family default -(Note the -\family typewriter -++ -\family default - after -\family typewriter -$nvar -\family default - which raises the variable number for the next variable. -\family typewriter -) -\begin_inset Newline newline -\end_inset - - -\end_layout - -\begin_layout Standard -What does this mean? -\end_layout - -\begin_layout Labeling -\labelwidthstring 00.00.0000 -name -\begin_inset space ~ -\end_inset - - -\emph on -string -\emph default - This is the variable name. - It should be parsable in Perl, e.g. - in the above case it is expanded to -\family typewriter -$lnm1 -\family default - in the gridcode. -\end_layout - -\begin_layout Labeling -\labelwidthstring 00.00.0000 -longname -\begin_inset space ~ -\end_inset - - -\emph on -string -\emph default - This is a long (human-readable) name used in logging. - It should contain no spaces (use underscores). -\end_layout - -\begin_layout Labeling -\labelwidthstring 00.00.0000 -range -\begin_inset space ~ -\end_inset - - -\emph on -x -\emph default - -\begin_inset space ~ -\end_inset - - -\emph on -y -\emph default - This defines the range of the grid, from -\emph on -x -\emph default - to -\emph on -y. - -\emph default - In the above case from -\family typewriter -log(0.1) -\family default - to -\family typewriter -log(80.0) -\family default -. - (We are using a grid in -\emph on -log -\emph default - -\begin_inset Formula $M_{1}$ -\end_inset - -.) Note that this is an -\emph on -anonymous array -\emph default -. - which must be declared with -\family typewriter -[ -\emph on -min -\emph default -, -\emph on -max -\emph default -] -\family default -. -\end_layout - -\begin_layout Labeling -\labelwidthstring 00.00.0000 -resolution -\begin_inset space ~ -\end_inset - - -\emph on -n -\emph default -This is the grid resolution, given above by -\family typewriter -$n -\family default -. -\end_layout - -\begin_layout Labeling -\labelwidthstring 00.00.0000 -spacingfunc -\begin_inset space ~ -\end_inset - - -\emph on -func -\emph default -This defines the spacing function which should be in the -\emph on -spacing_functions -\emph default - Perl module. - In the above example the spacing is constant between -\family typewriter -log(0.1) -\family default -and -\family typewriter - log(80.0) -\family default -with -\family typewriter - $n -\family default -steps. -\end_layout - -\begin_layout Labeling -\labelwidthstring 00.00.0000 -precode -\begin_inset space ~ -\end_inset - - -\emph on -code -\emph default -This is code executed before the next part of the grid is set up. - In our case we have to specify -\family typewriter -$m1 -\family default - because we have only calculated -\family typewriter -$lnm1 -\family default -. - We also set up the eccentricity because there is no grid for this and it - is required. - -\end_layout - -\begin_layout Labeling -\labelwidthstring 00.00.0000 -postcode -\begin_inset space ~ -\end_inset - - -\emph on -code -\emph default -This is code executed after the next part of the grid is set up. - (In our case there is no -\emph on -postcode -\emph default -). -\end_layout - -\begin_layout Labeling -\labelwidthstring 00.00.0000 -probdist -\begin_inset space ~ -\end_inset - - -\emph on -func -\emph default -This is a probability distribution function as given in the -\emph on -distribution_functions -\emph default - Perl module. - In the above we use the -\family typewriter -ktg93 -\family default - (Kroupa, Tout, Gilmore 1993 IMF) function. - -\end_layout - -\begin_layout Labeling -\labelwidthstring 00.00.0000 -dphasevol -\begin_inset space ~ -\end_inset - - -\emph on -expression -\emph default -This defines the contribution to the phase volume from this variable. - In general this is just -\family typewriter -$dlnm1 -\family default - (i.e. - should be -\family typewriter -$d -\emph on -name -\family default -\emph default -) but you can set it to whatever you like. - -\end_layout - -\begin_layout Subsection -3D grid example -\end_layout - -\begin_layout Standard -The next step is to set up the further grid variables. - Usually these are -\begin_inset Formula $M_{2}$ -\end_inset - - and -\begin_inset Formula $a$ -\end_inset - -, as defined in the code below. -\end_layout - -\begin_layout Standard - -\family typewriter -\begin_inset Box Frameless -position "t" -hor_pos "c" -has_inner_box 1 -inner_pos "t" -use_parbox 0 -use_makebox 0 -width "100col%" -special "none" -height "1in" -height_special "totalheight" -status open - -\begin_layout Plain Layout - -\family typewriter -# Binary stars: Mass 2 and Separation -\end_layout - -\begin_layout Plain Layout - -\family typewriter -if($binary_grid::grid_options{'binary'}) -\end_layout - -\begin_layout Plain Layout - -\family typewriter -{ -\end_layout - -\begin_layout Plain Layout - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -$binary_grid::grid_options{'flexigrid'}{'grid variable '.$nvar++}= -\end_layout - -\begin_layout Plain Layout - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -{ -\end_layout - -\begin_layout Plain Layout - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -'name'=>'m2', -\end_layout - -\begin_layout Plain Layout - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -'longname'=>'Secondary_mass', -\end_layout - -\begin_layout Plain Layout - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -'range'=>[$binary_grid::grid_options{'m2min'},'$m1'], -\end_layout - -\begin_layout Plain Layout - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -'resolution'=>$n, -\end_layout - -\begin_layout Plain Layout - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -'spacingfunc'=>"const($binary_grid::grid_options{'m2min'}, -\backslash -$m1,$n)", -\end_layout - -\begin_layout Plain Layout - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -'probdist'=>"const($binary_grid::grid_options{'m2min'}, -\backslash -$m1)", -\end_layout - -\begin_layout Plain Layout - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -'dphasevol','$dm2' -\end_layout - -\begin_layout Plain Layout - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -}; -\end_layout - -\begin_layout Plain Layout - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -$binary_grid::grid_options{'flexigrid'}{'grid variable '.$nvar++}= -\end_layout - -\begin_layout Plain Layout - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -{ -\end_layout - -\begin_layout Plain Layout - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -'name'=>'lnsep', -\end_layout - -\begin_layout Plain Layout - -\family typewriter -'longname'=>'ln(Orbital_Separation)', -\end_layout - -\begin_layout Plain Layout - -\family typewriter -'range'=>['log(3.0)','log(1e4)'], -\end_layout - -\begin_layout Plain Layout - -\family typewriter -'resolution',$n, -\end_layout - -\begin_layout Plain Layout - -\family typewriter -'spacingfunc',"const(log(3.0),log(1e4),$n)", -\end_layout - -\begin_layout Plain Layout - -\family typewriter -'precode'=>"my -\backslash -$sep=exp( -\backslash -$lnsep);my -\backslash -$per=calc_period_from_sep( -\backslash -$m1, -\backslash -$m2, -\backslash -$sep);", -\end_layout - -\begin_layout Plain Layout - -\family typewriter -'probdist'=>'const(log(3.0),log(1e4))', -\end_layout - -\begin_layout Plain Layout - -\family typewriter -'dphasevol'=>'$dlnsep' -\end_layout - -\begin_layout Plain Layout - -\family typewriter -} -\end_layout - -\begin_layout Plain Layout - -\family typewriter -} -\end_layout - -\end_inset - - -\end_layout - -\begin_layout Standard -The above setup has the same general form as for -\begin_inset Formula $M_{1}$ -\end_inset - - but with different spacing functions (the -\emph on -const -\emph default - spacing function is used, for -\begin_inset Formula $M_{2}$ -\end_inset - - in the range -\begin_inset Formula $0.1$ -\end_inset - - to -\begin_inset Formula $M_{1}$ -\end_inset - - and for -\begin_inset Formula $\ln a$ -\end_inset - - in the range -\begin_inset Formula $3$ -\end_inset - - to -\begin_inset Formula $10^{4}$ -\end_inset - -). -\end_layout - -\begin_layout Subsection -Gridcode -\end_layout - -\begin_layout Standard -The complete example from the above is -\begin_inset Newline newline -\end_inset - - -\begin_inset Newline newline -\end_inset - - -\begin_inset Box Frameless -position "t" -hor_pos "c" -has_inner_box 1 -inner_pos "t" -use_parbox 0 -use_makebox 0 -width "100col%" -special "none" -height "1in" -height_special "totalheight" -status open - -\begin_layout Plain Layout - -\family typewriter -$n=10; # grid resolution -\begin_inset Newline newline -\end_inset - -my $nvar=0; # variable number -\end_layout - -\begin_layout Plain Layout - -\family typewriter -# Mass 1 -\end_layout - -\begin_layout Plain Layout - -\family typewriter -$binary_grid::grid_options{'flexigrid'}{'grid variable '.$nvar++}= -\end_layout - -\begin_layout Plain Layout - -\family typewriter -{ -\end_layout - -\begin_layout Plain Layout - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -'name'=>'lnm1', -\end_layout - -\begin_layout Plain Layout - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -'longname'=>'Primary_Mass', -\end_layout - -\begin_layout Plain Layout - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -'range' => ["log($binary_grid::grid_options{'mmin'})", -\end_layout - -\begin_layout Plain Layout - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -"log($binary_grid::grid_options{'mmax'})"], -\end_layout - -\begin_layout Plain Layout - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -'resolution'=>$n, -\end_layout - -\begin_layout Plain Layout - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -'spacingfunc'=>"const(log($binary_grid::grid_options{'mmin'}),log($binary_grid:: -grid_options{'mmax'}),$n)", -\end_layout - -\begin_layout Plain Layout - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -'precode'=>"my -\backslash -$m1=exp( -\backslash -$lnm1);my -\backslash -$eccentricity=0.0;", -\end_layout - -\begin_layout Plain Layout - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -'probdist'=>"ktg93( -\backslash -$m1)* -\backslash -$m1", -\end_layout - -\begin_layout Plain Layout - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -'dphasevol'=>" -\backslash -$dlnm1 " -\end_layout - -\begin_layout Plain Layout - -\family typewriter -}; -\end_layout - -\begin_layout Plain Layout - -\family typewriter -# Binary stars: Mass 2 and Separation -\end_layout - -\begin_layout Plain Layout - -\family typewriter -if($binary_grid::grid_options{'binary'}) -\end_layout - -\begin_layout Plain Layout - -\family typewriter -{ -\end_layout - -\begin_layout Plain Layout - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -$binary_grid::grid_options{'flexigrid'}{'grid variable '.$nvar++}= -\end_layout - -\begin_layout Plain Layout - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -"name m2 longname Secondary_mass range 0.1 -\backslash -$m1 resolution $n spacingfunc const(0.1, -\backslash -$m1,$n) probdist const(0.1/ -\backslash -$m1,1.0) dphasevol -\backslash -$dm2 "; -\end_layout - -\begin_layout Plain Layout - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -$binary_grid::grid_options{'flexigrid'}{'grid variable '.$nvar++}= -\end_layout - -\begin_layout Plain Layout - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -"name lnsep longname ln(Orbital_Separation) range log(3.0) log(1e4) resolution - $n spacingfunc const(log(3.0),log(1e4),$n) precode my -\backslash -$sep=exp( -\backslash -$lnsep);my -\backslash -$per=calc_period_from_sep( -\backslash -$m1, -\backslash -$m2, -\backslash -$sep); probdist const(log(3.0),log(1e4)) dphasevol -\backslash -$dlnsep "; -\end_layout - -\begin_layout Plain Layout - -\family typewriter -} -\end_layout - -\end_inset - - -\begin_inset Newline newline -\end_inset - -When you run -\family typewriter -flexigrid(2); -\family default - in your grid script, a (flexi)grid with two threads will be run. - You can find the code that is constructed by the -\emph on -binary_grid -\emph default - module in the file -\family typewriter -/tmp/gridcode -\family default - (view it with -\emph on -less -\emph default - or some other tool that can parse ANSI colours, or set -\family typewriter -$binary_grid::grid_options{'colour'}=0; -\family default -). -\end_layout - -\begin_layout Subsection -Technical details -\end_layout - -\begin_layout Standard -This code is, of course, still under development. - Please use it with care! -\end_layout - -\begin_layout Itemize -I have replaced calls to tbse with calls to run_binary_c which is a more - flexible function (and will be used by the binary_c daemon once the remote-mach -ine version is complete). -\end_layout - -\begin_layout Itemize -$starcount should equal the number of stars run on the grid. - -\end_layout - -\begin_layout Itemize -@starcount stores the number of stars run in each subgrid. -\end_layout - -\begin_layout Itemize -The array @prob stores the contribution to the probability from each variable - separately (except the final variable, for which $prob is calculated). - This assumes, as always, that the probability density functions are separable. -\end_layout - -\begin_layout Standard -\begin_inset Newpage pagebreak -\end_inset - - -\end_layout - -\begin_layout Section -Initial distributions (IMF etc.) -\end_layout - -\begin_layout Standard -\begin_inset CommandInset label -LatexCommand label -name "sec:initial-dists" - -\end_inset - -The initial distributions of stellar masses, mass ratios, separations and - periods are handled by the -\emph on -IMF.pm -\emph default - Perl module. - The general idea is that given a set of stellar parameters -\begin_inset Formula $M_{1}$ -\end_inset - -, -\begin_inset Formula $M_{2}$ -\end_inset - - and -\begin_inset Formula $a$ -\end_inset - - (or -\begin_inset Formula $P$ -\end_inset - -) and phase volume -\begin_inset Formula $\delta\ln M_{1}$ -\end_inset - -, -\begin_inset Formula $\delta\ln M_{2}$ -\end_inset - - and -\begin_inset Formula $\delta\ln a$ -\end_inset - - (or -\begin_inset Formula $\delta\ln P$ -\end_inset - -) the probability of existence of star -\begin_inset Formula $i$ -\end_inset - - is calculated from -\end_layout - -\begin_layout Standard -\begin_inset Formula -\begin{eqnarray} -p_{i} & = & \Psi(M_{1})\Phi(M_{2})\chi(a)\,\delta\ln M_{1}\,\delta\ln M_{2}\,\delta\ln a\nonumber \\ - & = & \Psi\Phi\chi\delta\ln V\label{eq:prob-eq} -\end{eqnarray} - -\end_inset - -where -\begin_inset Formula $\delta\ln V$ -\end_inset - - is the 'logphasevol' (as stored in the progenitor hash, see Section -\begin_inset space ~ -\end_inset - - -\begin_inset CommandInset ref -LatexCommand ref -reference "sec:grid-options" - -\end_inset - -). - The functions -\begin_inset Formula $\Psi$ -\end_inset - -, -\begin_inset Formula $\Phi$ -\end_inset - - and -\begin_inset Formula $\chi$ -\end_inset - - are not necessarily independent (e.g. - -\begin_inset Formula $\Phi(M_{2})$ -\end_inset - - may actually be -\begin_inset Formula $\Phi(q=M_{2}/M_{1})$ -\end_inset - - in which case it depends on -\begin_inset Formula $M_{1}$ -\end_inset - -) but the assumption we make is that -\begin_inset Formula $p_{i}$ -\end_inset - - is separable. - Note that -\begin_inset Formula $\sum p_{i}$ -\end_inset - - must add to one, i.e. - -\begin_inset Formula $\int p\, dV=1$ -\end_inset - -. - In general, each of the distributions must also satisfy -\begin_inset Formula $\int\Psi(M_{1})dM_{1}=\int\Psi(M_{2})dM_{2}=\int\chi(a)da=1$ -\end_inset - - where the integrals are from -\begin_inset Formula $-\infty$ -\end_inset - - to -\begin_inset Formula $+\infty$ -\end_inset - -. -\end_layout - -\begin_layout Standard -There are many forms for each initial distributions and they depend on which - authors you believe and/or which stars you are looking at (e.g. - low- or high-mass stars). - There is no one true answer -- yet! -\end_layout - -\begin_layout Subsection -The distribution_functions module -\end_layout - -\begin_layout Standard -In earlier versions of binary_grid, the distribution functions were built - into the -\begin_inset Quotes eld -\end_inset - -IMF -\begin_inset Quotes erd -\end_inset - - module. - In the latest binary_grid, however, which uses Flexigrid (see Section -\begin_inset space ~ -\end_inset - - -\begin_inset CommandInset ref -LatexCommand ref -reference "sec:flexigrid" - -\end_inset - -) these distribution functions are found in the distribution_functions module - instead. - This is much more flexible, for example it allows the functions -\begin_inset Formula $\Psi$ -\end_inset - -, -\begin_inset Formula $\Phi$ -\end_inset - -, -\begin_inset Formula $\chi$ -\end_inset - - etc. - to be completely arbitrary. -\end_layout - -\begin_layout Subsection -Predefined functions -\end_layout - -\begin_layout Description -const( -\begin_inset Formula $a$ -\end_inset - -, -\begin_inset Formula $b$ -\end_inset - -, -\begin_inset Formula $x$ -\end_inset - -) Returns a constant distribution function between -\begin_inset Formula $x$ -\end_inset - - and -\begin_inset Formula $y$ -\end_inset - - i.e. - returns -\begin_inset Formula $1/(b-a)$ -\end_inset - -. - -\begin_inset Formula $x$ -\end_inset - - is optional, if given then a result is returned only if -\begin_inset Formula $a\geq x\geq b$ -\end_inset - -, otherwise zero. - (This is useful for specifying a flat- -\begin_inset Formula $q$ -\end_inset - - distribution for the secondary mass or a flat- -\begin_inset Formula $\ln a$ -\end_inset - - separation distribution.) -\end_layout - -\begin_layout Description -powerlaw( -\begin_inset Formula $a$ -\end_inset - -, -\begin_inset Formula $b$ -\end_inset - -, -\begin_inset Formula $k$ -\end_inset - -, -\begin_inset Formula $x$ -\end_inset - -) A power-law distribution in -\begin_inset Formula $x$ -\end_inset - - between -\begin_inset Formula $a$ -\end_inset - - and -\begin_inset Formula $b$ -\end_inset - - with slope -\begin_inset Formula $k$ -\end_inset - -, zero if out of range. -\end_layout - -\begin_layout Description -three_part_power_law( -\begin_inset Formula $x$ -\end_inset - -, -\begin_inset Formula $x_{0}$ -\end_inset - -, -\begin_inset Formula $x_{1}$ -\end_inset - -, -\begin_inset Formula $x_{2}$ -\end_inset - -, -\begin_inset Formula $x_{\mathrm{max}}$ -\end_inset - -, -\begin_inset Formula $p_{1}$ -\end_inset - -, -\begin_inset Formula $p_{2}$ -\end_inset - -, -\begin_inset Formula $p_{3}$ -\end_inset - -, -\family typewriter -$consts -\family default -) A three-part power-law distrubition between -\begin_inset Formula $x_{0}$ -\end_inset - - and -\begin_inset Formula $x_{\mathrm{max}}$ -\end_inset - -, with slopes -\begin_inset Formula $p_{i}$ -\end_inset - - between -\begin_inset Formula $x_{i-1}$ -\end_inset - - and -\begin_inset Formula $x_{i}$ -\end_inset - - ( -\begin_inset Formula $i=1,2,3$ -\end_inset - -), zero otherwise. -\begin_inset Newline newline -\end_inset - - -\family typewriter -$consts -\family default - is optional: it can be built by calling -\family typewriter -initialize_three_part_power_law(@opts,$consts) -\family default - before calling -\family typewriter -three_part_power_law() -\family default - (where -\family typewriter -@opts -\family default - contains -\begin_inset Formula $x$ -\end_inset - -, -\begin_inset Formula $x_{0}$ -\end_inset - -, -\begin_inset Formula $x_{1}$ -\end_inset - -, -\begin_inset Formula $x_{2}$ -\end_inset - -, -\begin_inset Formula $x_{\mathrm{max}}$ -\end_inset - -, -\begin_inset Formula $p_{1}$ -\end_inset - -, -\begin_inset Formula $p_{2}$ -\end_inset - -, -\begin_inset Formula $p_{3}$ -\end_inset - -). - Why do this? Well, for a general three-part power law, you have to normalise - -- this imposes a calculation overhead. - You can put the results of the normalisation in -\family typewriter -$consts -\family default - and -- if the power-law you use is a constant, you do not have to calculate - these normalisation constants again\SpecialChar \@. - The -\family typewriter -ktg93() -\family default - function does exactly what is described above (see the module code for - details). -\end_layout - -\begin_layout Description -ktg93( -\begin_inset Formula $M$ -\end_inset - -) A wrapper function to use the Kroupa, Tout & Gilmore 1993 initial mass - function for mass -\begin_inset Formula $M$ -\end_inset - -. - All the constants are set up for you, you just have to specify the mass - -\begin_inset Formula $M$ -\end_inset - -. - Easy! -\end_layout - -\begin_layout Standard -\begin_inset Newpage pagebreak -\end_inset - - -\end_layout - -\begin_layout Section -Debugging options -\end_layout - -\begin_layout Standard -\begin_inset CommandInset label -LatexCommand label -name "sec:debugging" - -\end_inset - -This section provides a summary of debugging options and suggestions for - ways to fix your code (or -\emph on -binary_grid -\emph default -!). - -\end_layout - -\begin_layout Itemize - -\family typewriter -$binary_grid::grid_options{'vb'} -\family default - controls the amount of grid output to the screen, usually lines showing - the number of stars evolved, the total number in the grid, the current - time, -\begin_inset Formula $M_{1}$ -\end_inset - -, -\begin_inset Formula $M_{2}$ -\end_inset - -, -\begin_inset Formula $a$ -\end_inset - -, -\begin_inset Formula $P$ -\end_inset - - and -\begin_inset Formula $Z$ -\end_inset - -, the probability, the total grid probability, -\begin_inset Formula $\%$ -\end_inset - - grid completion, estimated time until arrival (finish) i.e. - -\emph on -ETA -\emph default -, -\emph on -tpr -\emph default - (time per run), ETF (estimated time at which it will finish) and memory - usage. - If set to 1 it shows output every second or every -\family typewriter -$binary_grid::grid_options{'nmod'} -\family default - models. - If -\family typewriter -vb -\family default - is set to -\family typewriter -2 -\family default - then more output, showing the arguments sent to -\emph on -binary_c/nucsyn -\emph default -, will be dumped onto the screen for each model. - This is only useful for small grids, for large grids it will overwhelm - you. - It is possible to set -\family typewriter -vb=3 -\family default - but this is experimental. -\end_layout - -\begin_layout Itemize - -\family typewriter -$binary_grid::grid_options{'log_args'} -\family default - will output the arguments sent to -\emph on -binary_c/nucsyn -\emph default - in files in -\family typewriter -/tmp/ -\family default -. - In unthreaded grids these go in -\family typewriter -/tmp/binary_c.lastargs -\family default - while in threaded grids -\family typewriter -/tmp/binary_c.thread_$n.lastargs -\family default - where -\family typewriter -$n -\family default - is the thread number. - This is a more practical approach to debugging individual systems in large - grids than -\family typewriter -vb=2 -\family default -. - It is also useful in the case where your code freezes, because as long - as the code is frozen you can access the final model (for each thread) - in the files and then rerun them with -\family typewriter -tbse -\family default - to see where it went wrong. -\end_layout - -\begin_layout Itemize - -\family typewriter -$binary_grid::grid_options{'args'} -\family default - stores a single string with the raw arguments that were passed into -\emph on -binary_c/nucsyn -\emph default -. - This is useful if you want to do some debugging in the parse_bse function - (which has access to this variable). -\end_layout - -\begin_layout Itemize - -\family typewriter -$binary_grid::grid_options{'progenitor'} -\family default - stores the progenitor information in a single string, in the following - order: binarity, -\begin_inset Formula $M_{1}$ -\end_inset - -, -\begin_inset Formula $M_{2}$ -\end_inset - -, -\begin_inset Formula $P$ -\end_inset - -, -\begin_inset Formula $a$ -\end_inset - -, -\begin_inset Formula $e$ -\end_inset - -, -\begin_inset Formula $Z$ -\end_inset - -, -\begin_inset Formula $P$ -\end_inset - - and -\begin_inset Formula $\delta\ln V$ -\end_inset - - (the ' -\family typewriter -logphasevol -\family default -'= -\begin_inset Formula $\delta\ln M_{1}\delta\ln M_{2}\delta a$ -\end_inset - -). - If the star is a single star ( -\family roman -binarity -\family typewriter -==0 -\family default -) then -\begin_inset Formula $M_{2}$ -\end_inset - -, -\begin_inset Formula $P$ -\end_inset - -, -\begin_inset Formula $a$ -\end_inset - - and -\begin_inset Formula $e$ -\end_inset - - are omitted and -\begin_inset Formula $\delta\ln V=\delta\ln M$ -\end_inset - -. - This data is accessible from -\family typewriter -parse_bse -\family default -. -\end_layout - -\begin_layout Itemize -The hash-in-a-hash -\family typewriter - -\begin_inset Newline newline -\end_inset - -%binary_grid::grid_options{'progenitor_hash'}{ -\begin_inset Formula $\dots$ -\end_inset - -} -\family default - -\begin_inset Newline newline -\end_inset - -contains the same information as the progenitor string (above) in a more - accessible form: the hash -\emph on -keys -\emph default - are binarity, -\begin_inset Formula $M_{1}$ -\end_inset - -, -\begin_inset Formula $M_{2}$ -\end_inset - -, -\begin_inset Formula $P$ -\end_inset - -, -\begin_inset Formula $a$ -\end_inset - -, -\begin_inset Formula $e$ -\end_inset - -, -\begin_inset Formula $Z$ -\end_inset - -, -\begin_inset Formula $P$ -\end_inset - - and -\begin_inset Formula $\delta\ln V$ -\end_inset - -, and the values contain the appropriate data. - Again, this is accessible from -\family typewriter -parse_bse -\family default -. -\end_layout - -\begin_layout Itemize -Use the -\family typewriter -test_grid -\family default - if you are running a full grid and want to test if your initial distributions - integrate such that -\begin_inset Formula $\sum_{i}p_{i}=1$ -\end_inset - -. -\end_layout - -\begin_layout Itemize -Use the -\family typewriter -timeout -\family default - feature if your code is freezing. - This is -\emph on -not -\emph default - the same as fixing your problem, but you may be able to stop the code from - using all your CPU when it freezes! -\end_layout - -\begin_layout Standard -\begin_inset Newpage pagebreak -\end_inset - - -\end_layout - -\begin_layout Section -Future Plans -\end_layout - -\begin_layout Standard -\begin_inset CommandInset label -LatexCommand label -name "sec:future-plans" - -\end_inset - - -\end_layout - -\begin_layout Itemize -The period and separation grid functions could be extended to include other - distributions. -\end_layout - -\begin_layout Itemize -A graphical frontend would be good! -\end_layout - -\begin_layout Itemize -There once was an adaptive grid which zoomed into areas of special interest, - should this be resurrected? -\end_layout - -\begin_layout Standard -\begin_inset Newpage pagebreak -\end_inset - - -\end_layout - -\begin_layout Section -FAQ -\end_layout - -\begin_layout Standard -\begin_inset CommandInset label -LatexCommand label -name "sec:FAQ" - -\end_inset - - -\end_layout - -\begin_layout Description -Why -\begin_inset space ~ -\end_inset - -not -\begin_inset space ~ -\end_inset - -Monte -\begin_inset space ~ -\end_inset - -Carlo? The alternative to running a grid is a Monte Carlo method, where - you throw systems in according to some initial distribution and a random - number generator. - In the high number limit this should give the -\emph on -same -\emph default - -\emph on -result -\emph default -as a grid. - However, in the low-number limit, the results are probably going to be - different, and this is when you test your code. - The big advantage of a grid is that you have a good handle on -\emph on -errors -\emph default - due to the finite resolution of your sampling of the initial distribution(s) - without the smearing out of a Monte Carlo approach. - Furthermore, MC may accidentally miss part of the initial parameter space - (it is, after all, random) which you know is covered by a grid approach - (at least to within a known error e.g. - -\begin_inset Formula $\delta\ln M_{1}$ -\end_inset - -). - You are also guaranteed, on a grid, to sample even the rare systems which - would be sparsely populated (if at all) in an MC simulation. - Such systems will have a small probability per star, -\begin_inset Formula $p_{i}$ -\end_inset - -, but on the other hand these might be the systems of particular interest - to you! -\end_layout - -\begin_layout Description -Why -\begin_inset space ~ -\end_inset - -MC -\begin_inset space ~ -\end_inset - -SN -\begin_inset space ~ -\end_inset - -kicks? Traditionally supernova (and white dwarf) kicks have had their velocity - chosen in a Monte-Carlo way, rather than on a grid. - This was left as-is because there are four dimensions for each kick, which - -- given a coarse grid of -\begin_inset Formula $10\times10\times10\times10$ -\end_inset - - -- means the parameter space expands by a factor of -\begin_inset Formula $1,\,000$ -\end_inset - - for stars with kicks. - The runtime increase is not worth the effort as in order to finish anything - in your lifetime you would have to either buy a supercomputer or run such - a coarse grid in the original parameters that the whole exercise becomes - pointless. - The brute force resolution test is what you need here: just keep increasing - the resolution until the numbers converge. - It helps if you are clever about it: if you're interested in supernovae - only then -\begin_inset Formula $M_{1}$ -\end_inset - - is probably the dimension that requires the most resolution, or perhaps - -\begin_inset Formula $M_{2}$ -\end_inset - -, but probably not -\begin_inset Formula $a$ -\end_inset - -. -\end_layout - -\begin_layout Description -Zombie -\begin_inset space ~ -\end_inset - -binary_c -\begin_inset space ~ -\end_inset - -processes When the grid exits abnormally, or is killed, a -\emph on -binary_c/nucsyn -\emph default - process may be left behind in an infinite loop state and as such will take - up your precious CPU time. - You will have to kill it manually -\emph on -if you are sure it is not doing anything with another grid process! -\emph default -(Be careful and do -\emph on -not -\emph default - do -\begin_inset Quotes eld -\end_inset - -killall binary_c -\begin_inset Quotes erd -\end_inset - - as root\SpecialChar \ldots{} -) -\end_layout - -\begin_layout Description -Zombie -\begin_inset space ~ -\end_inset - -Perl -\begin_inset space ~ -\end_inset - -processes These should die naturally when the grid finishes and the Perl - script exits. - They are harmless and have never been seen to consume CPU time. -\end_layout - -\begin_layout Standard -\begin_inset Newpage pagebreak -\end_inset - - -\end_layout - -\begin_layout Section -Threaded grids -\end_layout - -\begin_layout Standard - -\emph on -This section is deprecated. - You should use the flexigrid as described above in Section -\begin_inset space ~ -\end_inset - - -\begin_inset CommandInset ref -LatexCommand ref -reference "sec:flexigrid" - -\end_inset - - -\end_layout - -\begin_layout Standard -\begin_inset CommandInset label -LatexCommand label -name "sec:threads" - -\end_inset - -When -\emph on -binary_grid -\emph default - was originally developed, multi-core CPUs were unheard of and multi-CPU - systems rare. - However, these days they are common, so a simple technique was developed - to make the grid function on multi-CPU/core systems. - The grid over single-star masses, -\begin_inset Formula $M$ -\end_inset - -, or primary-star masses, -\begin_inset Formula $M_{1}$ -\end_inset - -, is now split into chunks and each chunk given to a CPU via a native Perl - -\begin_inset Quotes eld -\end_inset - -thread -\begin_inset Quotes erd -\end_inset - - (see e.g. - -\begin_inset Flex URL -status collapsed - -\begin_layout Plain Layout - -http://search.cpan.org/~jdhedden/threads-1.79/lib/threads.pm -\end_layout - -\end_inset - -, you will need to have a thread-capable Perl and install the -\family typewriter -threads-shared -\family default - module). - The difficult trick is to make the chunks equal in runtime and to perform - the accounting when -\begin_inset Quotes eld -\end_inset - -joining -\begin_inset Quotes erd -\end_inset - - the results of the threads. -\end_layout - -\begin_layout Subsection -The threaded grid -\end_layout - -\begin_layout Standard -\begin_inset CommandInset label -LatexCommand label -name "sub:threaded-grid" - -\end_inset - -From the perspective of the user, only a few things have to change in order - to use a threaded grid. - In -\emph on -grid-xxx.pl -\emph default - you just have to set -\family typewriter -$usethreads=1 -\family default -. - This calls the following code: -\begin_inset Newline newline -\end_inset - - -\end_layout - -\begin_layout Standard - -\family typewriter -if($usethreads) -\end_layout - -\begin_layout Standard - -\family typewriter -{ -\end_layout - -\begin_layout Standard - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -use threads; -\end_layout - -\begin_layout Standard - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -threaded_grid(); -\end_layout - -\begin_layout Standard - -\family typewriter -} -\begin_inset Newline newline -\end_inset - - -\family default - -\begin_inset Newline newline -\end_inset - -The -\family typewriter -threaded_grid -\family default - function takes an argument which is the number of threads. - If no argument is given the number of threads is automatically allocated - (usually from the number of CPUs, if that information is available). - -\end_layout - -\begin_layout Standard -Nothing else needs to change, except that you have to save data in a specific - format in -\family typewriter -parse_bse -\family default - and set up a -\family typewriter -join -\family default - function. - These are described in the following sections. -\end_layout - -\begin_layout Standard -A good example of a threaded grid is provided in the -\emph on -grid-hrd.pl -\emph default - script which was used to make multi-dimensional HR diagrams (also in time - and -\begin_inset Formula $\log g$ -\end_inset - -). - -\end_layout - -\begin_layout Subsection -Setting up your parse_bse -\end_layout - -\begin_layout Standard -\begin_inset CommandInset label -LatexCommand label -name "sub:parse-bse-threads" - -\end_inset - -The -\family typewriter -parse_bse -\family default - function is basically the same as with a single-thread grid, except that - you -\emph on -must -\emph default - save your results in a hash -\family typewriter -%h -\family default -. - Once the thread has run its sub-grid, it sends the results to the join - function (see the next section) which takes the -\family typewriter -%h -\family default - hash and adds it to the global results. -\end_layout - -\begin_layout Standard -The hash -\family typewriter -%h -\family default - can be used to store multi-dimensional data, e.g. - distributions (histograms). - In some cases you'll want to store numbers of stars, something like: -\begin_inset Newline newline -\end_inset - - -\end_layout - -\begin_layout Standard - -\family typewriter -$dtp = $p * $dt; -\end_layout - -\begin_layout Standard - -\family typewriter -$h{'R star'} += $dtp; -\family default - -\begin_inset Newline newline -\end_inset - - -\begin_inset Newline newline -\end_inset - -Perhaps you want to make histograms, e.g. - a luminosity function: -\begin_inset Newline newline -\end_inset - - -\end_layout - -\begin_layout Standard - -\family typewriter -$h{'Luminosity function'}{'10-20'}+=$dtp; -\family default - -\begin_inset Newline newline -\end_inset - - -\begin_inset Newline newline -\end_inset - -Perhaps you want to make histograms at given times: -\begin_inset Newline newline -\end_inset - - -\end_layout - -\begin_layout Standard - -\family typewriter -$h{'Luminosity function'}{'20 Myr'}{'30-40'}+=$dtp; -\family default - -\begin_inset Newline newline -\end_inset - - -\begin_inset Newline newline -\end_inset - - -\end_layout - -\begin_layout Standard -Similarly you can make -\begin_inset Formula $n$ -\end_inset - --dimensional hashes of hashes of hashes (or arrays!). - Perl is good for that. -\end_layout - -\begin_layout Subsection -Joining the results -\end_layout - -\begin_layout Standard -\begin_inset CommandInset label -LatexCommand label -name "sub:thread-join" - -\end_inset - -Once your thread has finished running its stars, it calls the join thread - function. - This is set in your grid-xxx.pl with a line like the following: -\begin_inset Newline newline -\end_inset - - -\end_layout - -\begin_layout Standard - -\family typewriter -$binary_grid::grid_options{'threads_join_function_pointer'}= -\backslash -&join_thread; -\family default - -\begin_inset Newline newline -\end_inset - - -\begin_inset Newline newline -\end_inset - -You have to write join_thread yourself. - It should take a pointer to a hash ( -\family typewriter -%h -\family default - in the thread, which must be dereferenced as -\family typewriter -%$h -\family default - in the join function). - It should look something like the following: -\begin_inset Newline newline -\end_inset - - -\end_layout - -\begin_layout Standard - -\family typewriter -sub join_thread -\end_layout - -\begin_layout Standard - -\family typewriter -{ -\end_layout - -\begin_layout Standard - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -# function which is called when a thread is joined: -\end_layout - -\begin_layout Standard - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -# Note that $h is a hash pointer which is used by binary_c threads -\end_layout - -\begin_layout Standard - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -# to collect data. - It dies when it goes out of scope, probably -\end_layout - -\begin_layout Standard - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -# after this function. -\begin_inset Newline newline -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\end_layout - -\begin_layout Standard - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -my $h=shift; -\begin_inset Newline newline -\end_inset - - -\end_layout - -\begin_layout Standard - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -# save the results -\begin_inset Newline newline -\end_inset - - -\end_layout - -\begin_layout Standard - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -foreach my $k (keys %$h) -\end_layout - -\begin_layout Standard - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -{ -\end_layout - -\begin_layout Standard - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -# add the data from %$h into a global hash -\end_layout - -\begin_layout Standard - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -} -\end_layout - -\begin_layout Standard - -\family typewriter -} -\family default - -\begin_inset Newline newline -\end_inset - - -\begin_inset Newline newline -\end_inset - -At present you will have to determine whether the hash is a simple hash, - hash of hashes, etc. - from the value of the string in -\family typewriter -$k -\family default -. - It may well be possible to automate this process, but so far that level - of sophistication has not proven necessary. - One way to do it may be to prepend the hash keys with a (e.g.) 'scalar', - 'array' or 'hash' string. -\end_layout - -\begin_layout Standard -Once all your threads have finished, control is restored to your -\emph on -grid-xxx.pl -\emph default - script and you can output the results from global hash. -\end_layout - -\begin_layout Subsection -Load balancing -\end_layout - -\begin_layout Standard -\begin_inset CommandInset label -LatexCommand label -name "sub:load-balancing" - -\end_inset - -The other difficulty with running threaded grids is to spread the workload - equally over the different CPUs/cores. - Because the grid is split according to primary/single-star mass -\begin_inset Formula $M_{1}$ -\end_inset - - we really need the workload for a given -\emph on -stellar mass -\emph default -. - There are two methods to doing this. - Both assume that the runtime as a function of -\begin_inset Formula $M_{1}$ -\end_inset - - is representative of the runtime of systems with parameters -\begin_inset Formula $M_{1}$ -\end_inset - -, -\begin_inset Formula $M_{2}$ -\end_inset - - and -\begin_inset Formula $a$ -\end_inset - -, i.e. - that single-star runtimes are representative of binary-star systems with - the same primary mass. - This seems to work well enough for the technique to work. -\end_layout - -\begin_layout Subsubsection -The function approximation -\end_layout - -\begin_layout Standard -You can provide a -\emph on -function -\emph default - which returns the runtime (in arbitrary units) as a function of -\begin_inset Formula $\log_{10}M$ -\end_inset - -. - This is not recommended but if you want to give it a try you can set -\family typewriter - -\begin_inset Newline newline -\end_inset - -$binary_grid::grid_options{'runtime_function_pointer'} -\family default - -\begin_inset Newline newline -\end_inset - -to point to the -\family typewriter -MS_lifetime -\family default - function in -\emph on -binary_grid -\emph default -, or write your own function. - Of course, this function has to be bug-free and accurate for your choice - of input physics. - -\family typewriter -MS_lifetime -\family default - takes into account (roughly) changes in metallicity, but that is all. -\end_layout - -\begin_layout Subsubsection -The timed-run approach -\end_layout - -\begin_layout Standard -The alternative approach is more accurate and takes into account changes - in the physics of your simulation. - To determine the runtime as a function of mass, a number of test models - are run. - The runtimes are put into a table which is then interpolated in order to - find the runtime as a function of mass for any mass. -\end_layout - -\begin_layout Standard -In order to use the timed-run approach, -\emph on -binary_c/nucsyn -\emph default - must be equipped to tell -\emph on -binary_grid -\emph default - the runtime of each star that it evolves. - The most common way to do this is to build in support for the -\family typewriter -RDTSC_TIMER -\family default - (and -\family typewriter -RDTSC_TIMER_PER_SYSTEM -\family default -) in -\family typewriter -code_options.h -\family default -. - This uses the Intel tick counter to tell you how many cycles have passed - for each system that is evolved, the -\begin_inset Quotes eld -\end_inset - -tick count -\begin_inset Quotes erd -\end_inset - -. - On running a single system with tbse you should see something like: -\begin_inset Newline newline -\end_inset - - -\end_layout - -\begin_layout Standard - -\family typewriter -Tick count 275804808, ~ runtime = 0.108842 repeat=1 -\family default - -\begin_inset Newline newline -\end_inset - - -\begin_inset Newline newline -\end_inset - - -\emph on -Binary_grid -\emph default - can use this information to construct a table of runtimes and then interpolate - on this to balance the loads equally across the threads. - Note that -\family typewriter -CPUFREQ -\family default - must be defined (in MHz, usually at code -\emph on -configure -\emph default - time) for a true runtime to be output, otherwise only the -\begin_inset Quotes eld -\end_inset - -tick count -\begin_inset Quotes erd -\end_inset - - will be available. -\end_layout - -\begin_layout Standard -On CPUs other than the Intel-compatibles you will have to use a different - timer. - You could try the virtual timer ( -\family typewriter -CC_TIMER -\family default - in -\family typewriter -code_options.h -\family default -) or write your own code for it (see the code in -\family typewriter -main.c -\family default -). -\end_layout - -\begin_layout Subsection -Thread timeout -\end_layout - -\begin_layout Standard -If a thread should appear to be -\begin_inset Quotes eld -\end_inset - -stuck -\begin_inset Quotes erd -\end_inset - - (i.e. - it contributes no output) after -\begin_inset Newline newline -\end_inset - - -\family typewriter -$binary_grid::grid_options{'thread_max_freeze_time_before_warning'} -\family default - seconds, a warning will be sent to the screen. -\end_layout - -\begin_layout Subsection -Thread flushing -\end_layout - -\begin_layout Standard -If you define a function pointed to by -\family typewriter -$binary_grid::grid_options{'threads_flush_func'} -\family default - this will be called at the end of the run of each thread (the -\begin_inset Quotes eld -\end_inset - -flush -\begin_inset Quotes erd -\end_inset - - stage) with a pointer to the -\family typewriter -%h -\family default - data hash passed as the only argument. -\end_layout - -\begin_layout Standard -\begin_inset Newpage pagebreak -\end_inset - - -\end_layout - -\begin_layout Standard - -\size scriptsize -\begin_inset CommandInset bibtex -LatexCommand bibtex -bibfiles "references" -options "apalike" - -\end_inset - - -\end_layout - -\end_body -\end_document diff --git a/doc/deprecated/binary_grid.pdf b/doc/deprecated/binary_grid.pdf deleted file mode 100644 index 3ff08dd6e4e89a58d85f1c21abb3b443bdcee9fb..0000000000000000000000000000000000000000 Binary files a/doc/deprecated/binary_grid.pdf and /dev/null differ diff --git a/doc/deprecated/binary_grid2.lyx b/doc/deprecated/binary_grid2.lyx deleted file mode 100644 index f25c73f8a91a8fa8cd3b5de08c95864129221d67..0000000000000000000000000000000000000000 --- a/doc/deprecated/binary_grid2.lyx +++ /dev/null @@ -1,10409 +0,0 @@ -#LyX 2.0 created this file. For more info see http://www.lyx.org/ -\lyxformat 413 -\begin_document -\begin_header -\textclass scrartcl -\begin_preamble -\usepackage{eulervm} -% bibliography stuff -\def\aj{Astronomical Journal} % Astronomical Journal -\def\araa{ARA\&A} % Annual Review of Astron and Astrophys -\def\apj{Astrophysical Journal} % Astrophysical Journal -\def\apjl{Astrophysical Journal, Letters} % Astrophysical Journal, Letters -\def\apjs{Astrophysical Journal, Supplement} % Astrophysical Journal, Supplement -\def\apss{Ap\&SS} % Astrophysics and Space Science -\def\aap{Astronomy and Astrophysics} % Astronomy and Astrophysics -\def\aapr{A\&A~Rev.} % Astronomy and Astrophysics Reviews -\def\aaps{A\&AS} % Astronomy and Astrophysics, Supplement -\def\mnras{Monthly Notices of the Royal Astronomical Society} % Monthly Notices of the RAS -\def\pra{Phys.~Rev.~A} % Physical Review A: General Physics -\def\prl{Phys.~Rev.~Lett.} % Physical Review Letters -\def\pasa{PASA} % Publications of the ASP -\def\pasp{PASP} % Publications of the ASP -\def\pasj{PASJ} % Publications of the ASJ -\def\nat{Nature} % Nature -\def\aplett{Astrophys.~Lett.} % Astrophysics Letters -\def\physrep{Phys.~Rep.} % Physics Reports% - - -\usepackage{listings} -\end_preamble -\use_default_options true -\maintain_unincluded_children false -\language british -\language_package default -\inputencoding auto -\fontencoding global -\font_roman default -\font_sans helvet -\font_typewriter beramono -\font_default_family sfdefault -\use_non_tex_fonts false -\font_sc false -\font_osf false -\font_sf_scale 100 -\font_tt_scale 90 - -\graphics default -\default_output_format default -\output_sync 0 -\bibtex_command default -\index_command default -\paperfontsize default -\spacing single -\use_hyperref false -\papersize default -\use_geometry true -\use_amsmath 2 -\use_esint 1 -\use_mhchem 1 -\use_mathdots 1 -\cite_engine natbib_authoryear -\use_bibtopic false -\use_indices false -\paperorientation portrait -\suppress_date false -\use_refstyle 0 -\index Index -\shortcut idx -\color #008000 -\end_index -\leftmargin 2cm -\topmargin 3cm -\rightmargin 2cm -\bottommargin 3cm -\secnumdepth 3 -\tocdepth 3 -\paragraph_separation indent -\paragraph_indentation default -\quotes_language english -\papercolumns 1 -\papersides 1 -\paperpagestyle default -\tracking_changes false -\output_changes false -\html_math_output 0 -\html_css_as_file 0 -\html_be_strict false -\end_header - -\begin_body - -\begin_layout Title -Binary_grid -\end_layout - -\begin_layout Standard -Written by Robert Izzard, with greatly appreciated help from Fabian Schneider - and the other users of -\emph on -binary_grid -\emph default -. -\end_layout - -\begin_layout Section -Aims: what the grid does and why -\end_layout - -\begin_layout Standard -Binary population synthesis is a glorified form of accountancy, without - the huge pay but with of course much more fun! It involves modelling perhaps - millions of binary stars in a population to pick out those few that contribute - to the population of scientific interest. - The rate of formation, or number of these stars, or some other property - of them can then be examined in a -\emph on -quantitative -\emph default - and -\emph on -statistical -\emph default - manner. - This manual explains how the -\emph on -binary_grid -\emph default -module -- part of the -\emph on -binary_c/nucsyn -\emph default - code package -- can be used to model populations of single and binary stars. - -\end_layout - -\begin_layout Standard -For details about the binary stellar evolution code -\emph on -binary_c/nucsyn -\emph default - please see the nucsyn_manual document. - This guide is -\emph on -only -\emph default - concerned with the details of running grids of models, not about the details - of the models themselves. -\end_layout - -\begin_layout Subsection -Grid dimensions -\end_layout - -\begin_layout Standard -There are many parameters which can be set before running a stellar model. - The most important, for single stars, are the stellar mass -\begin_inset Formula $M$ -\end_inset - - and metallicity -\begin_inset Formula $Z$ -\end_inset - -. - It is common to set the metallicity -\begin_inset Formula $Z$ -\end_inset - - to be constant and vary the initial stellar mass -\begin_inset Formula $M$ -\end_inset - -. - In everything that follows I will assume you are working at a constant - metallicity -\begin_inset Formula $Z$ -\end_inset - -. - -\end_layout - -\begin_layout Standard -The situation is more complicated in binaries because instead of just -\begin_inset Formula $M$ -\end_inset - - there are two stellar masses -\begin_inset Formula $M_{1}$ -\end_inset - - and -\begin_inset Formula $M_{2}$ -\end_inset - -, the separation -\begin_inset Formula $a$ -\end_inset - - (or, equivalently, the period -\begin_inset Formula $P$ -\end_inset - -) and perhaps the eccentricity -\begin_inset Formula $e$ -\end_inset - -. - To run a population of binary stars then requires a grid of models in four - dimensions. - Often the eccentricity is ignored because close binaries -- which are the - ones in which you may be interested -- tend to circularise rapidly. - This reduces the problem to three dimensions. -\end_layout - -\begin_layout Standard -The number of stars on each side of the grid, i.e. - the -\emph on -resolution -\emph default - -\begin_inset Formula $n$ -\end_inset - -, roughly determines the total runtime of your simulation. - In single stars this is just -\begin_inset Formula $\Delta t\times n$ -\end_inset - -, where one model takes a time -\begin_inset Formula $\Delta t$ -\end_inset - - to run. - In the case of binaries on a three-dimensional grid, this increases to - -\begin_inset Formula $\Delta t\times n^{3}$ -\end_inset - - (see Fig. -\begin_inset space ~ -\end_inset - - -\begin_inset CommandInset ref -LatexCommand ref -reference "fig:grid-size" - -\end_inset - -). - In a typical population -\begin_inset Formula $n\sim100$ -\end_inset - - so the total runtime increases by a factor of -\begin_inset Formula $100^{2}=10^{4}$ -\end_inset - -. - This ignores the increase in -\begin_inset Formula $\Delta t$ -\end_inset - - for binaries which is unavoidable because there are two stars under considerati -on as well as smaller timesteps during mass transfer. - It is for this reason that the -\emph on -binary_c/nucsyn -\emph default - code (and its BSE ancestor) must be -- and is -- fast. - It can run a population of -\begin_inset Formula $10^{6}$ -\end_inset - - binaries in less than -\begin_inset Formula $24\,\mathrm{CPU\, hours}$ -\end_inset - -. - -\begin_inset Float figure -wide false -sideways false -status open - -\begin_layout Plain Layout -\begin_inset Graphics - filename binary_grid_images/m1_cuboid.ps - lyxscale 10 - scale 30 - rotateAngle 270 - -\end_inset - - -\begin_inset Graphics - filename binary_grid_images/m1_m2_a_cuboid.ps - lyxscale 10 - scale 30 - rotateAngle 270 - -\end_inset - - -\end_layout - -\begin_layout Plain Layout -\begin_inset Caption - -\begin_layout Plain Layout -\begin_inset CommandInset label -LatexCommand label -name "fig:grid-size" - -\end_inset - -The relative size of the single- and binary-star grids. - In single stars only one mass is required, -\begin_inset Formula $M_{1}$ -\end_inset - -, while in binaries the two masses -\begin_inset Formula $M_{1}$ -\end_inset - - and -\begin_inset Formula $M_{2}$ -\end_inset - - and separation are needed. - For a grid resolution of -\begin_inset Formula $n=100$ -\end_inset - -, the runtime for the single stars (left cuboid) is -\begin_inset Formula $100\times\Delta t$ -\end_inset - -, where -\begin_inset Formula $\Delta t$ -\end_inset - - is the runtime for one stellar system. - In binaries (right cuboid) this increases to at least -\begin_inset Formula $10^{6}\times\Delta t$ -\end_inset - - because of the extra grid dimensions. - In addition, -\begin_inset Formula $\Delta t$ -\end_inset - - will be longer for binaries because of the short timesteps required during - some phases of mass transfer, the fact that there are two stars to follow - in the evolution/nucleosynthesis algorithms and extra overhead from logging - and parsing output from both stars. - Typically, -\begin_inset Formula $\Delta t\sim0.1\,\mbox{s}$ -\end_inset - - on a -\begin_inset Formula $3\,\mbox{Ghz}$ -\end_inset - - PC. -\end_layout - -\end_inset - - -\end_layout - -\begin_layout Plain Layout - -\end_layout - -\end_inset - - -\end_layout - -\begin_layout Subsection -What to do with the grid -\end_layout - -\begin_layout Standard -What do we do once the grid of stars is set up? In most cases this involves - adding up some statistics related to each star on the grid. - There are two approaches which are commonly used, constant star formation - and a starburst. - The one that suits you depends on what you are trying to calculate and - to which observations you hope to compare. -\end_layout - -\begin_layout Subsubsection -Constant star formation rate -\end_layout - -\begin_layout Standard -In this case the formation rate or (perhaps -\begin_inset Formula $\delta t$ -\end_inset - --weighted) probabilities for each star corresponding to those in which you - are interested are simply added up. - This is why I say it is like accountancy! Because the rate of star formation - is assumed to be -\emph on -constant -\emph default - the evolution time of the stellar evolution is irrelevant. - A hybrid scheme can also be used, you might only consider stars older than - a given age (e.g. - for halo stars). -\end_layout - -\begin_layout Subsubsection -Starburst -\end_layout - -\begin_layout Standard -All stars form at time zero and you add up the (probably -\begin_inset Formula $\delta t$ -\end_inset - --weighted) number of stars in which you are interested which form or exist - in each time bin. - A good example is the delay-time distribution of type Ia supernovae. -\begin_inset Newline newline -\end_inset - - -\end_layout - -\begin_layout Standard -The statistic you wish to add up is usually output from -\emph on -binary_c/nucsyn. - -\emph default -Your -\begin_inset Quotes eld -\end_inset - -grid script -\begin_inset Quotes erd -\end_inset - - runs each star, takes the output of -\emph on -binary_c/nucsyn -\emph default - and adds up the statistic. - You can generate single numbers, histograms or arbitrarily complicated - statistical constructs for comparison with observations. - You can choose whether to do the calculations on the fly or save the progenitor - information for later data processing. -\end_layout - -\begin_layout Standard -The grid script can be used on multi-CPU machines and handles the administrative - issues regarding parallel processing. -\end_layout - -\begin_layout Standard -\begin_inset Newpage pagebreak -\end_inset - - -\end_layout - -\begin_layout Section -The theory of grids of stars -\end_layout - -\begin_layout Standard -\begin_inset CommandInset label -LatexCommand label -name "sec:grid-setup-theory" - -\end_inset - -This section presents the -\emph on -theory -\emph default - behind the setup of a grid in -\begin_inset Formula $M$ -\end_inset - -, for single stars, or -\begin_inset Formula $M_{1}$ -\end_inset - -, -\begin_inset Formula $M_{2}$ -\end_inset - - and -\begin_inset Formula $a$ -\end_inset - - for binary stars. - In general a -\emph on -logarithmic -\emph default - spacing is chosen for the mass grid because the important relevant physical - processes are -\begin_inset Quotes eld -\end_inset - -more different -\begin_inset Quotes erd -\end_inset - - for the mass range -\begin_inset Formula $1-10\,\mathrm{M}_{\odot}$ -\end_inset - - than between -\begin_inset Formula $10-100\,\mathrm{M}_{\odot}$ -\end_inset - -. - This is rather subjective but you can chose the bounds of your grid to - reflect the stars in which your interest lies. -\end_layout - -\begin_layout Standard -Each star in the grid represents a -\emph on -phase volume -\emph default -. - This means that a star of mass -\begin_inset Formula $M$ -\end_inset - - represents stars which, in reality, have masses -\begin_inset Formula $M-\delta M/2$ -\end_inset - - to -\begin_inset Formula $M+\delta M/2$ -\end_inset - -, where -\begin_inset Formula $\delta M$ -\end_inset - - is the grid spacing. - In an ideal world -\begin_inset Formula $\delta M$ -\end_inset - - would be very small, so our simulations match reality as closely as possible. - However, this is not usually possible if the grid is to run in a reasonable - amount of time (before funding runs out). - The usual way around this is to 1) be clever and/or 2) use a brute-force - approach where the resolution is increased (in this case -\begin_inset Formula $\delta M$ -\end_inset - - decreased) until your -\begin_inset Quotes eld -\end_inset - -answer -\begin_inset Quotes erd -\end_inset - - converges. -\end_layout - -\begin_layout Standard -One concept which must be grasped is that the bounds of the -\emph on -grid -\emph default - are not necessarily the bounds of the -\emph on -initial distributions -\emph default - you will be using (e.g. - the initial mass function, IMF). - This is a critical point which can lead to confusion, it is best explained - with an example. - Say you wish to calculate the ratio of type II to type Ib/c supernovae. - You would do this by adding up the number of stars that explode as type - IIs and divide by the number of stars that explode as type Ib/cs. - You -\emph on -could -\emph default - do this with a grid from -\begin_inset Formula $0.1$ -\end_inset - - to -\begin_inset Formula $100\,\mathrm{M}_{\odot}$ -\end_inset - - and, given enough stars, you would come up with the correct answer. - This is easy for single stars, because -\begin_inset Formula $10^{4}$ -\end_inset - - single stars are easily run on a modern PC. - However, for binaries this is difficult, because even with only -\begin_inset Formula $100$ -\end_inset - - stars in the -\begin_inset Formula $M_{2}$ -\end_inset - - and -\begin_inset Formula $a$ -\end_inset - - dimensions, there would be -\begin_inset Formula $10^{8}$ -\end_inset - - stars in your simulation and the runtime would be huge. - You can, however, be smarter and reduce the grid bounds and resolution. - You know in advance that at solar metallicity ( -\begin_inset Formula $Z=0.02$ -\end_inset - -) type II and Ib/c supernovae occur in -\emph on -single stars -\emph default - with -\begin_inset Formula $M\gtrsim8\mathrm{M}_{\odot}$ -\end_inset - -. - If you choose -\begin_inset Formula $M_{1}$ -\end_inset - - to run between (say) -\begin_inset Formula $4$ -\end_inset - - and -\begin_inset Formula $100\,\mathrm{M}_{\odot}$ -\end_inset - - you know you will record the supernovae from mass transfer (as -\begin_inset Formula $M_{2}\le M_{1}$ -\end_inset - - so the minimum mass of merged stars is the required -\begin_inset Formula $8\,\mathrm{M}_{\odot}$ -\end_inset - -) as well as all the others at higher masses. - So, you will get the -\emph on -same answer -\emph default - from a grid between -\begin_inset Formula $4$ -\end_inset - - and -\begin_inset Formula $100\,\mathrm{M}_{\odot}$ -\end_inset - - as with a grid between -\begin_inset Formula $0.1$ -\end_inset - - and -\begin_inset Formula $100\,\mathrm{M}_{\odot}$ -\end_inset - -. - Note that the -\emph on -grid -\emph default - has changed, but the result has not. - This is because the initial distributions have fixed bounds independent - of the grid bounds. - See Section -\begin_inset space ~ -\end_inset - - -\begin_inset CommandInset ref -LatexCommand ref -reference "sec:initial-dists" - -\end_inset - - for more details on initial distributions. - -\end_layout - -\begin_layout Standard -This process requires some knowledge in advance, which you may not have. - In that case, run a low resolution grid, find suitable grid bounds and - then repeat at higher resolution until you are happy. - The downside to the process is that you may well miss small parts of the - parameter space which contain interesting systems. - In practice this is often a compromise worth making and, if in doubt, test - your model runs at low resolution but then crank the resolution to the - maximum you think is possible for the final model run. -\end_layout - -\begin_layout Standard -Another advantage of choosing the grid bounds is that sub-grids can be run - on different computers or CPU cores and the results combined. - This is discussed further in Section -\begin_inset space ~ -\end_inset - - -\begin_inset CommandInset ref -LatexCommand ref -reference "sec:threads" - -\end_inset - -. -\end_layout - -\begin_layout Subsection -Phase Volume -\end_layout - -\begin_layout Standard -\begin_inset CommandInset label -LatexCommand label -name "sub:phase-volume" - -\end_inset - -Given a chosen set of these distributions a logarithmic grid is set up in - one-dimensional -\begin_inset Formula $M$ -\end_inset - - space for single stars or 3D -\begin_inset Formula $M_{1}$ -\end_inset - --- -\begin_inset Formula $M_{2}$ -\end_inset - --- -\begin_inset Formula $a$ -\end_inset - - space for binary stars. - The grid is split into -\begin_inset Formula $n$ -\end_inset - - stars per dimension such that each star represents the centre of a logarithmic - grid-cell of size -\begin_inset Formula $\delta V$ -\end_inset - - where -\end_layout - -\begin_layout Standard -\begin_inset Formula -\begin{equation} -\delta V=\left\{ \begin{array}{cc} -\delta\ln M & \textrm{single stars}\\ -\delta\ln M_{1}\,\delta\ln M_{2}\,\delta\ln a & \textrm{binary stars} -\end{array}\right. -\end{equation} - -\end_inset - -and -\begin_inset Formula -\begin{equation} -\delta\ln x=\frac{\ln x_{\textrm{max}}-\ln x_{\textrm{min}}}{n}\,, -\end{equation} - -\end_inset - -where -\begin_inset Formula $x$ -\end_inset - - represents -\begin_inset Formula $M$ -\end_inset - -, -\begin_inset Formula $M_{1}$ -\end_inset - -, -\begin_inset Formula $M_{2}$ -\end_inset - - or -\begin_inset Formula $a$ -\end_inset - - and -\begin_inset Formula $x_{\textrm{max}}$ -\end_inset - - and -\begin_inset Formula $x_{\textrm{min}}$ -\end_inset - - are the grid limits. - The total number of stars is denoted by -\begin_inset Formula $N$ -\end_inset - - such that -\begin_inset Formula $N=n$ -\end_inset - - for single stars and -\begin_inset Formula $N=n^{3}$ -\end_inset - - for binary stars. -\end_layout - -\begin_layout Standard -The probability of existence of star -\begin_inset Formula $i$ -\end_inset - - is given by -\end_layout - -\begin_layout Standard -\begin_inset Formula -\begin{equation} -\delta p_{i}=\Psi\delta V_{i}=\Psi\delta V\,, -\end{equation} - -\end_inset - -because -\begin_inset Formula $\delta V$ -\end_inset - - is a constant. - The function -\begin_inset Formula $\Psi$ -\end_inset - - is discussed in Section -\begin_inset space ~ -\end_inset - - -\begin_inset CommandInset ref -LatexCommand ref -reference "sec:initial-dists" - -\end_inset - -. - -\end_layout - -\begin_layout Standard -The probability, -\begin_inset Formula $\delta p_{i}$ -\end_inset - -, is sometimes the quantity you wish to add up, although commonly you want - -\begin_inset Formula $\delta p_{\mathrm{i}}\times\delta t$ -\end_inset - - where -\begin_inset Formula $\delta t$ -\end_inset - - is the time spent in the phase of interest. - This is usually the case when comparing the number of stars which go through - a particular phase of evolution because the -\emph on -time -\emph default -in the phase of evolution is as important as the -\emph on -probability -\emph default - of the star existing in the first place. - -\emph on - -\emph default -However, for -\emph on -event rates -\emph default - (e.g. - supernovae) the time involved is zero, they are instantaneous events on - a stellar evolution timescale, so you have to sum up the -\begin_inset Formula $\delta p_{i}$ -\end_inset - -. - You have to be careful to calculate the appropriate statistics for comparison - with the observations. -\end_layout - -\begin_layout Subsection -Grid loops -\end_layout - -\begin_layout Standard -\begin_inset CommandInset label -LatexCommand label -name "sub:grid-loops" - -\end_inset - -In binary systems, the secondary mass -\begin_inset Formula $M_{2}$ -\end_inset - - typically depends on the primary mass -\begin_inset Formula $M_{2}$ -\end_inset - -, and the separation, -\begin_inset Formula $a$ -\end_inset - -, or period -\begin_inset Formula $P$ -\end_inset - -, may depend on both. - This means that usually the grid must be constructed in a series of nested - loops and statistics must be added in order as follows: -\end_layout - -\begin_layout Standard -\begin_inset Formula -\begin{equation} -{\displaystyle \sum}_{M_{1}=M_{\mathrm{1,min}}}^{M_{1,\mathrm{max}}}\left(\sum_{M_{2}=M_{2}}^{M_{2\mathrm{,max}}}\left\{ \sum_{a=a_{\mathrm{min}}}^{a_{\mathrm{max}}}\left[\dots\right]\right\} \right)\,.\label{eq:grid-loops} -\end{equation} - -\end_inset - -In the default grid, -\begin_inset Formula $M_{2}$ -\end_inset - - depends on -\begin_inset Formula $M_{1}$ -\end_inset - - through the -\begin_inset Formula $q=M_{2}/M_{1}$ -\end_inset - - distribution. - The default is a flat- -\begin_inset Formula $q$ -\end_inset - - distribution (see Section -\begin_inset space ~ -\end_inset - - -\begin_inset CommandInset ref -LatexCommand ref -reference "sec:initial-dists" - -\end_inset - -), with which stars only exist if -\begin_inset Formula $0.1\,\mathrm{M}_{\odot}\leq M_{2}\leq M_{1}$ -\end_inset - -. - As such it generally makes sense to have -\begin_inset Formula $M_{2,\mathrm{min}}=0.1\,\mathrm{M}_{\odot}$ -\end_inset - - and -\begin_inset Formula $M_{2,\mathrm{max}}=M_{1}$ -\end_inset - - because secondary stars with mass greater than the primary do not exist - (by definition of the secondary and primary). -\end_layout - -\begin_layout Standard -The default separation distribution does not depend on the masses, but it - may if the -\family typewriter -adapt_sepdist -\family default - option is used (see Section -\begin_inset space ~ -\end_inset - - -\begin_inset CommandInset ref -LatexCommand ref -reference "sec:grid-options" - -\end_inset - -). -\end_layout - -\begin_layout Subsection -Resolution -\end_layout - -\begin_layout Standard -\begin_inset CommandInset label -LatexCommand label -name "sub:resolution" - -\end_inset - -The choice of grid resolution depends very much on the problem you wish - to address and what you are trying to calculate. - As a general rule, assuming you are modelling stars from -\begin_inset Formula $M_{\mathrm{min}}=0.1\,\mathrm{M}_{\odot}$ -\end_inset - - to -\begin_inset Formula $M_{\mathrm{max}}=100\,\mathrm{M}_{\odot}$ -\end_inset - - you probably want at least -\begin_inset Formula $100$ -\end_inset - - stars in the -\begin_inset Formula $M$ -\end_inset - - (or -\begin_inset Formula $M_{1}$ -\end_inset - -) dimension. - -\end_layout - -\begin_layout Standard -However, before rushing off to run millions of stars, run some low-resolution - test models and gradually increase the number of stars. - The best way to determine the required resolution is simply the brute force - method: keep increasing the resolution until your answers converge. -\end_layout - -\begin_layout Standard -You can roughly estimate the -\emph on -statistical -\emph default -error by counting the number of stars that satisfy your criterion (say -\begin_inset Formula $k$ -\end_inset - - stars) and then use Poisson statistics (i.e. - the error on a value -\begin_inset Formula $x$ -\end_inset - - is -\begin_inset Formula $x/\sqrt{k}$ -\end_inset - -). - -\series bold -Be warned that this is -\emph on -not -\emph default - the error due to the use of a grid. - -\series default - If your data calculation binning is -\emph on -over -\emph default --resolved you may see problems with artifacts and aliasing. - These may or may not affect your results. - If in doubt, increase the resolution until the problem goes away (if it - goes away!). - In some cases this may not be possible because your computer is not fast - enough. - You could always buy a time machine\SpecialChar \ldots{} - but then you wouldn't be doing astrophysics -! -\end_layout - -\begin_layout Standard -Sometimes you can choose a better mass grid than the default -\begin_inset Formula $\ln M$ -\end_inset - - grid to obtain better resolution where required for the same number of - stars, as described in the next section. -\end_layout - -\begin_layout Subsection -Alternative grid spacing -\end_layout - -\begin_layout Standard -\begin_inset CommandInset label -LatexCommand label -name "sub:alternative-grid-spacing" - -\end_inset - -Some problems require a more carefully spaced grid than the simple -\begin_inset Formula $\ln M$ -\end_inset - - grid. - A good example is the calculation of stellar yields. - The yield sets are generally required to give yields out to a time of many - -\begin_inset Formula $\mathrm{Gyr}$ -\end_inset - - and with a time resolution of, say, -\begin_inset Formula $10\,\mathrm{Myr}$ -\end_inset - -. - At early times this is not a problem, but at late times the stellar lifetime - scales with the mass as -\begin_inset Formula $t\sim M^{3}$ -\end_inset - - (roughly) so in order to have good time resolution we require -\begin_inset Formula $\delta M\sim\delta t/(3M^{2})\sim t^{-2/3}\delta t$ -\end_inset - - which is rather small at late times when -\begin_inset Formula $t$ -\end_inset - - is large. - -\end_layout - -\begin_layout Standard -An alternative is to set up the grid to -\emph on -enforce -\emph default - -\begin_inset Formula $\delta M=f\times\delta t/(3M^{2})$ -\end_inset - - as our grid spacing (with a factor -\begin_inset Formula $f<1$ -\end_inset - - which ensures over-resolution to avoid gridding artifacts). - Implementations of this, and a fixed -\begin_inset Formula $\delta\ln t$ -\end_inset - - grid, are available in -\emph on -binary_grid -\emph default -. - -\end_layout - -\begin_layout Standard -\begin_inset Newpage pagebreak -\end_inset - - -\end_layout - -\begin_layout Section -Grid setup (in practice) -\end_layout - -\begin_layout Standard -\begin_inset CommandInset label -LatexCommand label -name "sec:grid-setup-practice" - -\end_inset - -This section describes a typical grid setup with the default grid options. - Alternative grid setups are discussed in Section -\begin_inset space ~ -\end_inset - - -\begin_inset CommandInset ref -LatexCommand ref -reference "sec:grid-options" - -\end_inset - - which lists the grid options in detail. -\end_layout - -\begin_layout Standard -The grid is set up by use of a Perl module called -\emph on -binary_grid -\emph default -. - This is usually installed with -\emph on -binary_c/nucsyn -\emph default - (see the -\emph on -binary_c/nucsyn -\emph default - manual). - In any case, you need it! You will also need the -\emph on -IMF -\emph default - perl module (to calculate initial stellar distribution functions, see Section -\begin_inset space ~ -\end_inset - - -\begin_inset CommandInset ref -LatexCommand ref -reference "sec:initial-dists" - -\end_inset - -) and -\emph on -rob_misc -\emph default - (Rob's miscellaneous function library). -\end_layout - -\begin_layout Standard -You should copy the grid.pl script provided with -\emph on -binary_c/nucsyn -\emph default - and work on your -\emph on -copy -\emph default -. - The -\emph on -grid.pl -\emph default - script is a template for a minimal grid setup -- you will need to change - it to reflect whatever you output from the -\emph on -binary_c/nucsyn -\emph default - code. - It will be referred to as -\begin_inset Quotes eld -\end_inset - -your grid script -\begin_inset Quotes erd -\end_inset - - in what follows. -\end_layout - -\begin_layout Subsection -The Perl Module -\end_layout - -\begin_layout Standard -The -\emph on -binary_grid -\emph default - Perl module contains (almost) all the code to set up, manage and run your - stellar grid, as well as the interface to the -\emph on -binary_c/nucsyn -\emph default -. - This should be (almost) completely transparent to you, the user, and the - process is as automated as possible. - -\end_layout - -\begin_layout Subsubsection -Variables -\end_layout - -\begin_layout Standard -There are many global variables (sorry) but let's face it, this is written - in Perl, not C, so it doesn't matter. - You should not access most of them, except for the two hashes: -\end_layout - -\begin_layout Description - -\family typewriter -%bse_options -\family default - are those that are passed to the -\emph on -binary_c/nucsyn -\emph default - code and are discussed in detail in the -\emph on -binary_c/nucsyn -\emph default - manual. - They usually affect the -\emph on -physics -\emph default - being implemented in the simulation. -\end_layout - -\begin_layout Description - -\family typewriter -%grid_options -\family default - are variables which control details of the -\emph on -grid -\emph default - and the processing of the output. -\end_layout - -\begin_layout Standard -To access the variables in your grid script, you should use something like - the following: -\begin_inset Newline newline -\end_inset - - -\end_layout - -\begin_layout Standard - -\family typewriter -$binary_grid::bse_options{'max_evolution_time'}=10.0; -\end_layout - -\begin_layout Standard - -\family typewriter -$binary_grid::grid_options{'imf1'}='ktg93'; -\begin_inset Newline newline -\end_inset - - -\end_layout - -\begin_layout Standard -The -\family typewriter -$binary_grid:: -\family default - tells Perl that you want to change the hash in the -\family typewriter -binary_grid -\family default - module. -\end_layout - -\begin_layout Subsubsection -Important Subroutines -\end_layout - -\begin_layout Standard -The most important subroutines involved in setting up the grid, some of - which you have to call from your grid script (see Section -\begin_inset space ~ -\end_inset - - -\begin_inset CommandInset ref -LatexCommand ref -reference "sec:grid.pl" - -\end_inset - -) are the following: -\end_layout - -\begin_layout Description - -\family typewriter -grid_defaults -\family default - This sets up the default values for the two main hashes of options: -\family typewriter -%grid_options -\family default - and -\family typewriter -%bse_options -\family default -. - Note that in the case where a -\family typewriter -bse_option -\family default - is -\emph on -not -\emph default - given default, you may still set it in your grid script, but if it is -\emph on -not -\emph default - set the default -\emph on -binary_c/nucsyn -\emph default - value is used. -\end_layout - -\begin_layout Description - -\family typewriter -parse_grid_args -\family default - Arguments given on the command line in the form -\emph on -x -\family typewriter -\emph default -= -\family default -\emph on -y -\emph default - are parsed in turn. - If -\emph on -x -\emph default - matches any of the keys of the -\family typewriter -%grid_options -\family default - or -\family typewriter -%bse_options hashes -\family default -, the value of the hash item is set to that given by -\emph on -y -\emph default -. - If the key is not matched it is ignored. - A good example of the use of this function is the use of -\family typewriter -vb=1 -\family default - to turn on verbose log output from the grid. - This verbose output is often very useful as it gives you an estimate of - the fraction of the grid that is complete, the time remaining and the estimated - time at which the grid will finish. -\end_layout - -\begin_layout Description - -\family typewriter -setup_binary_grid -\family default - This should be called just before running your grid. - It initialises the initial distributions, sets up the timeout feature, - opens some log files etc. - -\end_layout - -\begin_layout Description - -\family typewriter -flexigrid -\family default - This runs through every star on your grid. - It is the call to this subroutine that does all the work of calculating - stellar models and parsing the results. - -\end_layout - -\begin_layout Description - -\family typewriter -tbse_line -\family default - This is called to retrieve data from calls to -\emph on -binary_c/nucsyn -\emph default -: see Section -\begin_inset space ~ -\end_inset - - -\begin_inset CommandInset ref -LatexCommand ref -reference "sec:data-parsing" - -\end_inset - -. -\end_layout - -\begin_layout Subsection -How binary_grid works (the guts) -\end_layout - -\begin_layout Standard -In order to run grids of stars, you do not have to understand how binary_grid - works. - However, for those that are interested, this section provides some clues. -\end_layout - -\begin_layout Subsubsection -The main components -\end_layout - -\begin_layout Standard -In order to run a grid of stars, you require a few main components. -\end_layout - -\begin_layout Enumerate -A stellar evolution code. - In most cases, this is -\emph on -binary_c/nucsyn -\emph default -. - However, it does not really matter which code you use, as long as you know - how to control and talk to it. -\end_layout - -\begin_layout Enumerate -A grid. - This is really just a way to define which stars you run (their masses, - separations, etc.). - -\emph on -binary_grid -\emph default -does this for you. -\end_layout - -\begin_layout Enumerate -A way of converting the output from your stellar code into useful statistics/dis -tributions. - This is done by -\emph on -you -\emph default - in your -\emph on -grid script -\emph default -. -\end_layout - -\begin_layout Standard -When you run a grid, the first thing that is set up (by -\emph on -flexigrid -\emph default -) is a set of loops over the specified variables, e.g. - -\begin_inset Formula $M_{1}$ -\end_inset - -, -\begin_inset Formula $M_{2}$ -\end_inset - -, -\begin_inset Formula $a$ -\end_inset - - or -\begin_inset Formula $P$ -\end_inset - -. - Binary_grid then runs a number of binary_c processes (e.g. - one for each CPU). - Binary_grid talks to binary_c through a two-way pipe, which is a standard - Unix interprocess communication technique (see Perl's open2 and open3 modules - on CPAN). -\end_layout - -\begin_layout Standard -The loops are started and a bunch ( -\begin_inset Formula $\sim10$ -\end_inset - -) of stars, each with a given -\begin_inset Formula $\{M_{1},M_{2},a\}$ -\end_inset - - combination, is sent to a free thread which runs each star in turn. - Binary_grid sends commands through its pipes to binary_c and then receives - answers through other pipes. - The answers are presented to the grid script via the tbse_line subroutine - -- it is up to the grid script, via its parse_bse function, to then do - something with the answers. -\end_layout - -\begin_layout Standard -In the parse_bse function, the first argument ($_[0]) is always set to $h, - the results hash -\begin_inset Foot -status collapsed - -\begin_layout Plain Layout -Or, rather, a reference to the hash because passing a huge hash around between - subroutines is very inefficient -\end_layout - -\end_inset - -. - Any results (e.g. - statistics, distributions) should be put in $h. -\end_layout - -\begin_layout Standard -Each thread has its own results hash $h so once a thread is finished (which - means all the stars are run), the data in all the different $h hashes must - be added to a global results hash. - This is done in the grid script's join_thread subroutine by use of the - arithmetically_add_hashes subroutine. -\end_layout - -\begin_layout Standard -\begin_inset Newpage pagebreak -\end_inset - - -\end_layout - -\begin_layout Section -Data parsing (Accountancy without the salary) -\end_layout - -\begin_layout Standard -\begin_inset CommandInset label -LatexCommand label -name "sec:data-parsing" - -\end_inset - -The previous sections describe how to set up a grid. - Before you actually run your own grid you have to think about what you - want to discover from your stellar models. - A few standard cases are outlined here. - You may, of course, want a combination of all these methods. -\end_layout - -\begin_layout Standard -This section describes the theory, the practical aspects of combining -\emph on -binary_c/nucsyn -\emph default - with your grid script are described in Section -\begin_inset space ~ -\end_inset - - -\begin_inset CommandInset ref -LatexCommand ref -reference "sec:grid.pl" - -\end_inset - -. -\end_layout - -\begin_layout Subsection -Rates of things -\end_layout - -\begin_layout Standard -\begin_inset CommandInset label -LatexCommand label -name "sub:rates-of-things" - -\end_inset - -The simplest thing to calculate is the rate of formation of some type of - star, or alternatively the rate of stellar death (e.g. - the supernova rate), merger rate, etc. - These are -\emph on -events -\emph default -which have no duration so the important thing to log is the -\emph on -time at which the event happened -\emph default -, -\emph on - -\begin_inset Formula $t_{i}$ -\end_inset - - -\emph default -, and -\emph on -the probability of existence of the stellar system, -\emph default - -\begin_inset Formula $p_{i}$ -\end_inset - -. -\end_layout - -\begin_layout Standard -You will probably want to count the number of systems that explode in a - given time bin, i.e. - between time -\begin_inset Formula $t$ -\end_inset - - and -\begin_inset Formula $t+\Delta t$ -\end_inset - -, where -\begin_inset Formula $\Delta t$ -\end_inset - - is the time bin width ( -\emph on -not -\emph default - the -\emph on -binary_c/nucsyn -\emph default - timestep!). - The formation rate is the product of the star formation rate -\begin_inset Formula $S$ -\end_inset - - and the summed probability of the stars that do whatever it is that is - interesting in time -\begin_inset Formula $t$ -\end_inset - - to -\begin_inset Formula $t+\Delta t$ -\end_inset - -, -\begin_inset Formula $\sum p_{i}$ -\end_inset - -. - You have to somehow calculate -\begin_inset Formula $S$ -\end_inset - - (see e.g. - -\begin_inset CommandInset citation -LatexCommand citealp -key "2002MNRAS_329_897H" - -\end_inset - - for a simple prescription). - You would be better comparing the relative rates of two types of event, - in which case -\begin_inset Formula $S$ -\end_inset - - (and its associated uncertainty) cancels. -\end_layout - -\begin_layout Standard -This is all correct for a starburst at time -\begin_inset Formula $t=0$ -\end_inset - -. - If you want to use a more realistic star formation history you have to - convolve the results of many starbursts. - You can do this manually (and it is easy if, say, the metallicity and other - physics is not a function of -\begin_inset Formula $t$ -\end_inset - -) or use a pre-existing code such as Rob's Galactic Chemical Evolution (GCE) - code. - The latter has the advantage that it already exists and is well tested. - You will, however, have to ask Rob about it because it is not (yet) a part - of the standard -\emph on -binary_c/nucsyn -\emph default - distribution. - -\end_layout - -\begin_layout Subsection -Numbers of things -\end_layout - -\begin_layout Standard -\begin_inset CommandInset label -LatexCommand label -name "sub:numbers-of-things" - -\end_inset - - -\end_layout - -\begin_layout Standard -Alternatively, perhaps you wish to calculate the number of stars of a certain - type e.g. - the number of carbon stars or the number of K-type stars. - In this case you have to count both the probability of the existence of - the star -\begin_inset Formula $p_{i}$ -\end_inset - - and the time the star spends in the evolutionary phase of interest. - If we assume -\begin_inset Formula $S=1$ -\end_inset - - (i.e. - constant star formation) you should then count -\begin_inset Formula $\sum p_{i}\,\delta t\,\bar{\delta}$ -\end_inset - - where -\begin_inset Formula $\bar{\delta}=1$ -\end_inset - - if the star is interesting to you, but zero otherwise. -\end_layout - -\begin_layout Standard -As in the previous example, if -\begin_inset Formula $S$ -\end_inset - - is not simply a constant things get tricky. - But usually a constant star formation rate is -\begin_inset Quotes eld -\end_inset - -good enough -\begin_inset Quotes erd -\end_inset - - for e.g. - Galactic stellar population studies of anything but the youngest stars. - In other cases a starburst is more appropriate and you will have to factor - in a check on the time -\begin_inset Formula $t$ -\end_inset - - into -\begin_inset Formula $\bar{\delta}$ -\end_inset - - to match the present-day age of the population. - -\end_layout - -\begin_layout Subsection -GCE and the ensemble -\end_layout - -\begin_layout Standard -\begin_inset CommandInset label -LatexCommand label -name "sub:gce" - -\end_inset - -As already mentioned, Rob has written a Galactic Chemical Evolution code - to do much of the work described above for you. - In addition to (sort of!) self-consistently calculating the nucleosynthesis - and hence metallicity evolution in a Galaxy for arbitrary star formation, - gas infall and outflow rates, you can enable the -\begin_inset Quotes eld -\end_inset - -stellar ensemble -\begin_inset Quotes erd -\end_inset - - in -\emph on -binary_c/nucsyn -\emph default -. - This simply enables a large piece of logging code to output e.g. - stellar types, spectral types, explosion counts, etc. - Rob's GCE code is designed to follow these and do the convolution for you. - It runs in two modes. - The first is to use saved starburst data from previous grid runs. - This is fast but not entirely self-consistent (although often it is good - enough). - The second technique is to run the binary grids at each timestep of the - GCE code. - This is better, in that the metallicity is more self-consistent, but can - be very slow because the GCE code runtime is limited by the time it takes - to run an entire binary grid (which is usually hours). - In future it is hoped that the GCE code will be run on a cluster of machines - with sufficient CPU power to reduce the overhead of running a binary grid. - This will require some effort to reliably automate the process. -\end_layout - -\begin_layout Standard -\begin_inset Newpage pagebreak -\end_inset - - -\end_layout - -\begin_layout Standard -\begin_inset Newpage pagebreak -\end_inset - - -\end_layout - -\begin_layout Section -Your grid-xxx.pl script -\end_layout - -\begin_layout Standard -\begin_inset CommandInset label -LatexCommand label -name "sec:grid.pl" - -\end_inset - -This describes a simple, single-thread grid based on the hard-coded loop - code. - If you want a better grid, working on multi-core CPUs, learn about the - -\emph on -flexigrid -\emph default - as well (see Section -\begin_inset space ~ -\end_inset - - -\begin_inset CommandInset ref -LatexCommand ref -reference "sec:flexigrid" - -\end_inset - -). -\begin_inset Newline newline -\end_inset - - -\begin_inset Newline newline -\end_inset - -Before you start: you should copy the -\family typewriter -grid.pl -\family default - script in the -\family typewriter -binary_c -\family default - directory to a script of your own naming (usually grid- -\emph on -xxx -\emph default -.pl where you choose a suitable label to replace -\emph on -xxx -\emph default -). - Work on your copy, not the original! -\end_layout - -\begin_layout Subsection -Logging in -\emph on -binary_c -\emph default -or -\emph on -How to know when to add up the number of stars -\end_layout - -\begin_layout Standard -When -\emph on -binary_c -\emph default - is run for one star with the -\family typewriter -tbse -\family default - script the output is dumped to the screen (known in -\emph on -UNIX -\emph default - as -\family typewriter -stdout -\family default -). - A standard build of -\emph on -binary_c -\emph default - outputs very little information because it does not know what you wish - to know. - Every line that is output is expensive in terms of CPU time, and CPU time - is critical when running millions of stars. - This means you have to think carefully about what you will output from - -\emph on -binary_c -\emph default - and when. - Too much information slows things down, too little is useless -- you have - to decide. -\end_layout - -\begin_layout Standard -You will probably want to output one line of information per -\emph on - binary_c -\emph default -timestep. - This should be done in the -\family typewriter -iteration_logging -\family default - subroutine which is called every timestep. - Your logging code should look something like: -\end_layout - -\begin_layout Standard - -\family typewriter -printf( -\begin_inset Quotes eld -\end_inset - -MYLOG %g %g %g %i -\backslash -n -\begin_inset Quotes erd -\end_inset - -, -\end_layout - -\begin_layout Standard - -\family typewriter -stardata->model.model_time, -\end_layout - -\begin_layout Standard - -\family typewriter -stardata->model.probability, -\end_layout - -\begin_layout Standard - -\family typewriter -stardata->model.dt, -\end_layout - -\begin_layout Standard - -\family typewriter -stardata->star[1].mass, -\end_layout - -\begin_layout Standard - -\family typewriter -stardata->star[1].stellar_type); -\end_layout - -\begin_layout Standard -The string -\family typewriter -MYLOG -\family default - is critical: this is what will be recognised and used by -\emph on -binary_grid -\emph default -. - You should have a think (and consult Section -\begin_inset space ~ -\end_inset - - -\begin_inset CommandInset ref -LatexCommand ref -reference "sec:data-parsing" - -\end_inset - -) to determine whether you want to output either the probability ( -\family typewriter -stardata-> model.probability -\family default -) or both the probability and timestep ( -\family typewriter -stardata->model.dt -\family default -). - Often it is the number of stars in a particular phase that you want to - count, in which case you want to add up -\family typewriter -stardata-> (model.probability*stardata->model.dt) -\family default -. -\end_layout - -\begin_layout Subsection -Coupling your -\emph on -binary_c/nucsyn -\emph default - and your grid: -\family typewriter -tbse_line -\family default -and -\family typewriter - parse_bse -\end_layout - -\begin_layout Standard -Now you know how to make lines of logging information come out of the -\emph on -binary_c -\emph default - program. - It remains to couple this to the grid. - This is done through the -\family typewriter -tbse_line -\family default - subroutine in the -\family typewriter -parse_bse -\family default - function (see the example -\family typewriter -grid.pl -\family default -). - Each time -\family typewriter -tbse_line -\family default - is called it gets a line of output from -\emph on -binary_c -\emph default - and loads returns it (usually to -\family typewriter -$_ -\family default - the Perl default variable). - It is then up to you to decide what to with the data from -\family typewriter -tbse_line -\family default -. - -\end_layout - -\begin_layout Standard -There may be many lines of data pumped into -\family typewriter -tbse_line -\family default -, so you have to choose those labelled with your header string -- in the - above example this is -\family typewriter -MYLOG -\family default -. - This is best done with a Perl substitution-regular expression: the regular - expression matches -\family typewriter -MYLOG -\family default -, the substitution removes it (because it is not data). - In the following example note that the check for ' -\family typewriter -fin -\family default -' -\emph on -must -\emph default - be there. - -\emph on -binary_c -\emph default - returns a ' -\family typewriter -fin -\family default -' when the star has finished its evolution. - Without this it would be stuck in an infinite loop, so do not remove the - -\family typewriter -$brk -\family default - stuff. - -\begin_inset Newline newline -\end_inset - - -\end_layout - -\begin_layout Standard - -\family typewriter -while($brk==0) -\end_layout - -\begin_layout Standard - -\family typewriter -{ -\end_layout - -\begin_layout Standard - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -$_=tbse_line(); chomp; # get line of data from binary_c -\end_layout - -\begin_layout Standard - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -if($_ eq 'fin') -\end_layout - -\begin_layout Standard - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -{ -\end_layout - -\begin_layout Standard - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -$brk=1; # the end of output -\end_layout - -\begin_layout Standard - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -} -\end_layout - -\begin_layout Standard - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -elsif(s/^MYLOG //) # regular expression to match and remove MYLOG -\end_layout - -\begin_layout Standard - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -{ -\end_layout - -\begin_layout Standard - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -split; # convert data string to array -\end_layout - -\begin_layout Standard - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -#... - do stuff with @_ ... -\end_layout - -\begin_layout Standard - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -# e.g. - $_[0] is the time, $_[1] is the probability etc. -\end_layout - -\begin_layout Standard - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -} -\end_layout - -\begin_layout Standard -} -\end_layout - -\begin_layout Subsection -Adding things up -\end_layout - -\begin_layout Standard -So you have the probabilities (and maybe the timesteps) for each timestep - of -\emph on -binary_c -\emph default - and for each star. - What do you do now? Well, you have to create meaningful statistics by summing - up the results. - The easiest way to do this is to use a global hash as in the following - example which counts the number of different types of -\begin_inset Quotes eld -\end_inset - -low mass -\begin_inset Quotes erd -\end_inset - - and -\begin_inset Quotes eld -\end_inset - -high mass -\begin_inset Quotes erd -\end_inset - - stars: -\begin_inset Newline newline -\end_inset - - -\end_layout - -\begin_layout Standard - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -elsif(s/^MYLOG //) # regular expression to match and remove MYLOG -\end_layout - -\begin_layout Standard - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -{ -\end_layout - -\begin_layout Standard - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -split; # convert data string to array -\end_layout - -\begin_layout Standard - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -my $dtp=$_[1]*$_[2];# calculate dt * p -\end_layout - -\begin_layout Standard - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -if($_[3]>8.0) -\end_layout - -\begin_layout Standard - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -{ -\end_layout - -\begin_layout Standard - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -# high mass star -\end_layout - -\begin_layout Standard - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -$results{'high-mass'}+=$dtp; -\end_layout - -\begin_layout Standard - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -} -\end_layout - -\begin_layout Standard - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -else -\end_layout - -\begin_layout Standard - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -{ -\end_layout - -\begin_layout Standard - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -# low mass star -\end_layout - -\begin_layout Standard - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -$results{'low-mass'}+=$dtp; -\end_layout - -\begin_layout Standard - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\family default -} -\end_layout - -\begin_layout Standard - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -} -\begin_inset Newline newline -\end_inset - - -\end_layout - -\begin_layout Standard -At the end of the first section of the grid.pl script it says -\begin_inset Quotes eld -\end_inset - -put your output here -\begin_inset Quotes erd -\end_inset - -. - This is where you should output the results, e.g. - -\end_layout - -\begin_layout Standard - -\family typewriter -# put output here -\end_layout - -\begin_layout Standard - -\family typewriter -printf -\begin_inset Quotes eld -\end_inset - -Ratio of the number of high to low mass stars = %g -\backslash -n -\begin_inset Quotes erd -\end_inset - -, -\end_layout - -\begin_layout Standard - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -$results{'high-mass'}/$results{'low-mass'}; -\end_layout - -\begin_layout Subsection -More advanced accountancy -\end_layout - -\begin_layout Standard -Consider the previous example. - Perhaps instead of simply having -\begin_inset Quotes eld -\end_inset - -low -\begin_inset Quotes erd -\end_inset - - and -\begin_inset Quotes eld -\end_inset - -high -\begin_inset Quotes erd -\end_inset - - mass stars you actually want to calculate a histogram of number of stars - as a function of mass at a certain time. -\end_layout - -\begin_layout Standard -The problem of how to force -\emph on -binary_c -\emph default - to output at given times is a tricky one which is not dealt with here. - However, you should consider following the -\family typewriter -VROT_LOGGING -\family default - code in -\emph on -binary_c -\emph default - (see -\family typewriter -deltat.c -\family default -) which does just this. - Let us assume you have fixed -\emph on -binary_c/nucsyn -\emph default - so it outputs the mass of each star every -\begin_inset Formula $1\,\mathrm{Myr}$ -\end_inset - -. - You want to bin the masses at each timestep, so you will have a series - of histograms. - Note that -\family typewriter -$dtp -\family default - is not required because you are not counting the number of stars in a given - -\emph on -phase -\emph default - but rather an instantaneous property of the stars at a given time -\family typewriter -$t -\family default -. -\end_layout - -\begin_layout Standard -Something like this will do it: -\begin_inset Newline newline -\end_inset - - -\end_layout - -\begin_layout Standard - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -elsif(s/^MYLOG //) # regular expression to match and remove MYLOG -\end_layout - -\begin_layout Standard - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -{ -\end_layout - -\begin_layout Standard - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -split; # convert data string to array -\end_layout - -\begin_layout Standard - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -my $t=$_[0]; # time (an integer number of Myr since the starburst) -\end_layout - -\begin_layout Standard - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -my $p=$_[1]; # probability -\end_layout - -\begin_layout Standard - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -my $m=$_[3]; # stellar mass -\end_layout - -\begin_layout Standard - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\end_layout - -\begin_layout Standard - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -# bin stellar mass in 1Msun bins -\end_layout - -\begin_layout Standard - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -$m = int(0.5+$m); -\end_layout - -\begin_layout Standard - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\end_layout - -\begin_layout Standard - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -$results{'mass histogram'}{$t}{$m}+=$p; # construct histogram -\end_layout - -\begin_layout Standard - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -} -\end_layout - -\begin_layout Standard -Things to note include: -\end_layout - -\begin_layout Itemize -The mass is binned to the nearest integer. - You can construct a similar expression for an arbitrary bin width. - Why do we do this? Well, if we take the instantaneous mass of each star - in a population at a given time there will be a huge number of different - masses because mass loss may be effective. - This would give a histogram with -\begin_inset Formula $N\times N_{t}=n_{\mathrm{M1}}\times n_{\mathrm{M2}}\times n_{\mathrm{a}}\times N_{t}$ -\end_inset - - bins where -\begin_inset Formula $N_{t}$ -\end_inset - - is the number of timesteps of -\emph on -binary_c -\emph default - output. - This is too much data to deal with and negates the whole purpose of making - a histogram! Bin your data: it makes life a lot easier. -\end_layout - -\begin_layout Itemize -We could have similarly binned the time to include stars at an age -\begin_inset Formula $t$ -\end_inset - - to -\begin_inset Formula $t+\Delta t$ -\end_inset - - (in this case -\begin_inset Formula $\Delta t$ -\end_inset - - would be -\begin_inset Formula $1\,\mathrm{Myr}$ -\end_inset - -) but that smears out the results into -\begin_inset Formula $1\,\mathrm{Myr}$ -\end_inset - - bins. - In our case we have -\emph on -snapshots -\emph default -at a given time instead. -\end_layout - -\begin_layout Itemize -The time and mass are integers in this case, so we could have used arrays - (which have integer index) instead of hashes for the output, but if you - want finer resolution they will not be and hashes are -\emph on -required -\emph default -. - It is good to get into the habit. - -\end_layout - -\begin_layout Itemize -The 'mass histogram' hash label is not required in this simple example, - but in a real grid you may be constructing many different histograms, each - with different labels. -\end_layout - -\begin_layout Itemize -The results are saved in hash of hashes of hashes. - This is a typical example of a Perl nested variable, help for how to deal - with (and output) hashes of hashes is easily found with a simple web search - (or consult the excellent -\emph on -Programming Perl -\emph default -). -\end_layout - -\begin_layout Itemize -Beware resolution! Always test different resolutions and beware binning - and aliasing effects. -\end_layout - -\begin_layout Subsection -Save your data -- or process on the fly? -\end_layout - -\begin_layout Standard -Before running a grid you have to make the big decision: do you save your - data or process it all on the fly? There are advantages and disadvantages - to both, as described below. -\end_layout - -\begin_layout Subsubsection -Saving data -\end_layout - -\begin_layout Standard -\begin_inset CommandInset label -LatexCommand label -name "sub:saving_data" - -\end_inset - -In this case you run a grid and tag the initial parameters of each system - of interest (i.e. - the -\begin_inset Formula $M_{1}$ -\end_inset - -, -\begin_inset Formula $M_{2}$ -\end_inset - -, -\begin_inset Formula $a$ -\end_inset - - and -\begin_inset Formula $\delta V=\delta\ln M_{1}\,\delta\ln M_{2}\,\delta a$ -\end_inset - -). - -\emph on -You save these initial parameters into a large datafile. - -\emph default - The big advantage of this technique is that you can rerun the saved grid - -\emph on -from the datafile, -\emph default -possibly -\emph on - -\emph default -without running -\emph on -binary_c/nucsyn -\emph default - again, and with a different initial distribution function (e.g. - initial mass function) or very slightly different physics (on the assumption - that changing the physics will not change the systems which were saved). - -\end_layout - -\begin_layout Standard -You could save, as well as the initial parameters of the systems, the time - spent in the phase of interest, -\begin_inset Formula $\Delta t$ -\end_inset - -. - Each time the grid is rerun you would then calculate the probability -\begin_inset Formula $p_{i}$ -\end_inset - - for each system again, hence you know -\begin_inset Formula $p_{i}\Delta t$ -\end_inset - - which is your required -\begin_inset Quotes eld -\end_inset - -number of stars -\begin_inset Quotes erd -\end_inset - -. - You can either -\end_layout - -\begin_layout Enumerate -Change -\begin_inset Formula $p_{i}$ -\end_inset - - and recalculate your statistics. - This does -\emph on -not -\emph default -require the running of -\emph on -binary_c/nucsyn -\emph default - and is the fast option. -\end_layout - -\begin_layout Enumerate -Change -\begin_inset Formula $p_{i}$ -\end_inset - - and some physics, which requires rerunning of -\emph on -binary_c/nucsyn -\emph default -. - This is slower, but still faster than running the full grid. -\end_layout - -\begin_layout Standard -Saving the progenitor data set is a very useful way of saving time after - an initial high-resolution grid run. -\end_layout - -\begin_layout Subsubsection -On the fly data processing -\end_layout - -\begin_layout Standard -\begin_inset CommandInset label -LatexCommand label -name "sub:on-the-fly" - -\end_inset - - -\end_layout - -\begin_layout Standard -If you do not want to recalculate your answer with different initial functions, - you might be better off calculating the results you require -\begin_inset Quotes eld -\end_inset - -on the fly -\begin_inset Quotes erd -\end_inset - -. - This means you do your data processing -\emph on -in your grid script -\emph default -. - The main advantages to this are speed and data storage. - For example, if you have -\begin_inset Formula $10^{6}$ -\end_inset - - -\begin_inset space ~ -\end_inset - -stars in your grid, that is -\begin_inset Formula $10^{6}$ -\end_inset - - -\begin_inset space ~ -\end_inset - -lines of data -- this might be a lot of data. -\end_layout - -\begin_layout Standard -In some cases you -\emph on -must -\emph default - do this. - If you are looking at data which is time dependent then you will have -\begin_inset Formula $10^{6}\times N_{t}$ -\end_inset - - -\begin_inset space ~ -\end_inset - -lines of data, where -\begin_inset Formula $N_{t}$ -\end_inset - - is the number of timesteps during which your system is of interest. - -\begin_inset Formula $N_{t}$ -\end_inset - - may be many hundreds for a given system, hence the total number of lines - of data is of the order of -\begin_inset Formula $10^{8}$ -\end_inset - - and the data storage requirements become quite ridiculous. - For example, a typical line of data has about 200 characters, so -\begin_inset Formula $200\times10^{8}=2\times10^{10}\,\mathrm{bytes}$ -\end_inset - - of data, or -\begin_inset Formula $20\,\mbox{GB}$ -\end_inset - -. - The time it takes to process all this data may be longer than the time - to -\emph on -rerun -\emph default - -\emph on -binary_c/nucsyn -\emph default -for each system, especially if your data storage is non-local (e.g. - on an NFS (network) partition). - Furthermore, you might not have 20 -\begin_inset space ~ -\end_inset - -GB available to you\SpecialChar \ldots{} - -\end_layout - -\begin_layout Standard -You can save some space by outputting data every, say, Myr, but this may - not be the time resolution you require to catch systems of interest. -\end_layout - -\begin_layout Standard -\begin_inset Newpage pagebreak -\end_inset - - -\end_layout - -\begin_layout Section -Grid options -\end_layout - -\begin_layout Standard -\begin_inset CommandInset label -LatexCommand label -name "sec:grid-options" - -\end_inset - -The following summarises the -\family typewriter -%grid_options -\family default - hash elements. - Please note that some options are (perhaps) no longer used and are left - in this manual as a reference guide only. -\end_layout - -\begin_layout Description - -\family typewriter -adapt_sepdist -\family default - The default separation distribution runs from -\begin_inset Formula $3\,\mathrm{R}_{\odot}$ -\end_inset - - to -\begin_inset Formula $10^{4}\,\mathrm{R}_{\odot}$ -\end_inset - - but the lower limit may be too close to avoid immediate Roche-lobe overflow - (and contact/merger) in massive stars. - Use -\family typewriter -adapt_sepdist=1 -\family default - to avoid this situation by adaptively increasing the lower limit to avoid - instantaneous mergers. - (See -\family typewriter -sepdist_min -\family default -.) (Will not work with -\emph on -flexigrid -\emph default - -- you have to specify a function call yourself in that case.) -\end_layout - -\begin_layout Description - -\family typewriter -alarm_procedure -\family default - When a signal is captured (usually on a timeout) the alarm_procedure tells - us what to do. - If -\begin_inset Formula $0$ -\end_inset - - then the grid exits. - If -\begin_inset Formula $1$ -\end_inset - - it tries to restart on the next star (although this may be buggy it is - the default!). - Really you should fix the problem if there is a timeout because it should - not happen. -\end_layout - -\begin_layout Description - -\family typewriter -args -\family default - Not technically an option, but is the string of arguments which is passed - to -\emph on -binary_c/nucsyn -\emph default -. - Useful for logging or debugging. -\end_layout - -\begin_layout Description - -\family typewriter -binary -\family default - The duplicity. - If binary is 1 then the grid runs binary stars, if 0 then single stars. -\end_layout - -\begin_layout Description - -\family typewriter -colour -\family default - If -\family typewriter -colour=1 -\family default - then verbose output (see -\family typewriter -vb -\family default -) is in colour, using the -\family typewriter -Term::ANSIColor -\family default - Perl module. - This is recommended. -\end_layout - -\begin_layout Description - -\family typewriter -compatibility_mode -\family default - An old (probably now deprecated) option which deletes the -\family typewriter -nucsyn_metallicity -\family default - from -\family typewriter -bse_options -\family default -. - Should no longer be required, so set it to zero. -\end_layout - -\begin_layout Description - -\family typewriter -dm -\family default - Not really a grid option, but stores the current -\begin_inset Formula $\delta M=M\delta\ln M$ -\end_inset - -. - (Was once) useful for debugging. -\end_layout - -\begin_layout Description - -\family typewriter -exit_on_eval_failure -\family default - When each star is run, it is inside a -\emph on -Perl -\emph default - -\family typewriter -eval -\family default - construct. - If there is an error (i.e. - -\family typewriter -$@ -\family default - is not undef) -\emph on -and -\emph default - -\family typewriter -exit_on_eval_failure -\family default - is defined then the grid is stopped. - Otherwise, the grid goes on in the hope that the error does not persist - (possibly dubious!). -\end_layout - -\begin_layout Description - -\family typewriter -extra_flash_resolution -\family default - Use this option to provide extra mass resolution around -\begin_inset Formula $1.9\,\mathrm{M}_{\odot}$ -\end_inset - - (the upper mass of the helium flash) in the lookup table used for the -\family typewriter -time_adaptive_mass_grid -\family default - (see that option and -\family typewriter -stellar_lifetime_table_nm -\family default -). -\emph on - -\begin_inset space ~ -\end_inset - -Please use the flexigrid instead of this option. -\end_layout - -\begin_layout Description - -\family typewriter -fixed_m1 -\family default - Set to -\begin_inset Formula $1$ -\end_inset - - if there is only one -\begin_inset Formula $M_{1}$ -\end_inset - - in the binary grid, otherwise keep set to zero. -\emph on - -\begin_inset space ~ -\end_inset - -Please use the flexigrid instead of this option. -\end_layout - -\begin_layout Description - -\family typewriter -imf1 -\family default - The primary star initial mass, -\begin_inset Formula $M$ -\end_inset - - or -\begin_inset Formula $M_{1}$ -\end_inset - -, function/distribution, usually -\begin_inset Quotes eld -\end_inset - -ktg93 -\begin_inset Quotes erd -\end_inset - -. - See -\emph on -IMF.pm -\emph default - (Section -\begin_inset space ~ -\end_inset - - -\begin_inset CommandInset ref -LatexCommand ref -reference "sec:initial-dists" - -\end_inset - -). -\emph on - -\begin_inset space ~ -\end_inset - -Please use the flexigrid instead of this option. -\end_layout - -\begin_layout Description - -\family typewriter -imf2 -\family default - The secondary star mass (or mass ratio -\begin_inset Formula $q=M_{2}/M_{1}$ -\end_inset - -) function/distribution, usually -\begin_inset Quotes eld -\end_inset - -flatq -\begin_inset Quotes erd -\end_inset - -. - See -\emph on -IMF.pm -\emph default - (Section -\begin_inset space ~ -\end_inset - - -\begin_inset CommandInset ref -LatexCommand ref -reference "sec:initial-dists" - -\end_inset - -). -\emph on - -\begin_inset space ~ -\end_inset - -Please use the flexigrid instead of this option. -\end_layout - -\begin_layout Description - -\family typewriter -imf2_exponent -\family default - The exponent in the secondary star -\begin_inset Formula $q$ -\end_inset - - distribution if it is a power law (0 is flat). -\emph on - -\begin_inset space ~ -\end_inset - -Please use the flexigrid instead of this option. -\end_layout - -\begin_layout Description - -\family typewriter -imf2_minm -\family default - The minimum mass in the secondary star -\begin_inset Formula $q$ -\end_inset - - distribution, usually -\begin_inset Formula $0.1$ -\end_inset - -( -\begin_inset Formula $\mathrm{M}_{\odot}$ -\end_inset - -). -\emph on - -\begin_inset space ~ -\end_inset - -Please use the flexigrid instead of this option. -\end_layout - -\begin_layout Description - -\family typewriter -imf2_maxm -\family default - The maximum mass in the secondary star -\begin_inset Formula $q$ -\end_inset - - distribution, usually -\begin_inset Quotes eld -\end_inset - -auto -\begin_inset Quotes erd -\end_inset - - (which means use -\begin_inset Formula $M_{1}$ -\end_inset - - as the maximum). - You can, alternatively, set this to an actual number, in which case you'll - be running a square ( -\begin_inset Formula $M_{2}\leq M_{2,\mathrm{max}}$ -\end_inset - -) rather than triangular ( -\begin_inset Formula $M_{2}\leq M_{1}$ -\end_inset - -) grid so you'll be needlessly repeating systems and reducing the grid resolutio -n in -\begin_inset Formula $M_{2}$ -\end_inset - -. -\emph on - -\begin_inset space ~ -\end_inset - -Please use the flexigrid instead of this option. -\end_layout - -\begin_layout Description - -\family typewriter -imf2_minq -\family default - The minimum -\begin_inset Formula $q$ -\end_inset - - value allowed on the grid, usually -\family typewriter -undef -\family default - and ignored (overrides -\family typewriter -imf2_minq -\family default -). -\emph on - -\begin_inset space ~ -\end_inset - -Please use the flexigrid instead of this option. -\end_layout - -\begin_layout Description - -\family typewriter -imf2_maxq -\family default - The maximum -\begin_inset Formula $q$ -\end_inset - - value allowed on the grid, usually -\begin_inset Formula $1$ -\end_inset - -. - (Overrides -\family typewriter -imf2_maxm -\family default -) -\emph on - -\begin_inset space ~ -\end_inset - -Please use the flexigrid instead of this option. -\end_layout - -\begin_layout Description - -\family typewriter -lastargs -\family default - Very similar to log_args but at a slightly different place in the code. - Should be avoided, use -\family typewriter -log_args -\family default - instead. -\end_layout - -\begin_layout Description - -\family typewriter -libpath -\family default - Path to libraries to be included in the calling of the -\emph on -binary_c/nucsyn -\emph default - executable. - This harks back to the days when -\emph on -binary_c/nucsyn -\emph default - was built as a set of shared libraries. - These days it is built statically, so libpath is usually an empty string - (and hence is ignored). -\end_layout - -\begin_layout Description - -\family typewriter -log_args -\family default - If this is set to -\begin_inset Formula $1$ -\end_inset - - then the arguments passed to -\emph on -binary_c/nucsyn -\emph default - are saved in a file in -\family typewriter -/tmp/ -\family default - (usually -\family typewriter -/tmp/binary_c-args -\family default - or similar, with separate files for each thread). - This is very useful when the grid freezes as you can immediately see which - stellar system has caused the problem and then rerun it manually. - -\end_layout - -\begin_layout Description - -\family typewriter -log_normal_median -\family default - The median value of a log-normal mass distribution (see -\emph on -IMF -\emph default -.pm, Section -\begin_inset space ~ -\end_inset - - -\begin_inset CommandInset ref -LatexCommand ref -reference "sec:initial-dists" - -\end_inset - -). - -\emph on - -\begin_inset space ~ -\end_inset - -Please use the flexigrid instead of this option. -\end_layout - -\begin_layout Description - -\family typewriter -log_normal_dispersion -\family default - The dispersion of a log-normal mass distribution (see -\emph on -IMF -\emph default -.pm, Section -\begin_inset space ~ -\end_inset - - -\begin_inset CommandInset ref -LatexCommand ref -reference "sec:initial-dists" - -\end_inset - -). - -\emph on - Please use the flexigrid instead of this option. -\end_layout - -\begin_layout Description - -\family typewriter -masshash_function -\family default - This can be set to an alternative function to make the -\begin_inset Formula $M$ -\end_inset - - or -\begin_inset Formula $M_{1}$ -\end_inset - - -\family typewriter -%masshash -\family default -. - (The default is -\family typewriter -undef -\family default - so it is ignored.) -\emph on -Please use the flexigrid instead of this option. -\end_layout - -\begin_layout Description - -\family typewriter -mmax -\family default - The maximum mass at which the single -\begin_inset Formula $M$ -\end_inset - - or primary mass -\begin_inset Formula $M_{1}$ -\end_inset - - grid ends (in -\begin_inset Formula $M_{\odot}$ -\end_inset - -, default -\begin_inset Formula $80$ -\end_inset - -). - -\family typewriter - -\family default -\emph on -Please use the flexigrid instead of this option. -\end_layout - -\begin_layout Description - -\family typewriter -m2max -\family default - The maximum mass at which the secondary mass -\begin_inset Formula $M_{2}$ -\end_inset - - grid ends (in -\begin_inset Formula $M_{\odot}$ -\end_inset - -, default -\begin_inset Formula $80$ -\end_inset - -). - -\emph on -Please use the flexigrid instead of this option. -\end_layout - -\begin_layout Description - -\family typewriter -mmin -\family default - The minimum mass at which the single -\begin_inset Formula $M$ -\end_inset - - or primary -\begin_inset Formula $M_{1}$ -\end_inset - - mass grid begins (in -\begin_inset Formula $M_{\odot}$ -\end_inset - -, default -\begin_inset Formula $0.1$ -\end_inset - -). - -\emph on -Please use the flexigrid instead of this option. -\end_layout - -\begin_layout Description - -\family typewriter -m2min -\family default - The minimum mass at which the secondary mass -\begin_inset Formula $M_{2}$ -\end_inset - - grid begins (in -\begin_inset Formula $M_{\odot}$ -\end_inset - -, default -\begin_inset Formula $0.1$ -\end_inset - -). - -\emph on -Please use the flexigrid instead of this option. -\end_layout - -\begin_layout Description - -\family typewriter -m2zoom -\family default - If set to 1 then for -\begin_inset Formula $M_{2}/M_{1}=q>$ -\end_inset - -m2q_zoom_q the resolution is set to m2q_zoom_n. - This can be used to increase the number of stars in the high -\begin_inset Formula $q$ -\end_inset - -. - -\emph on -Please use the flexigrid instead of this option. -\end_layout - -\begin_layout Description - -\family typewriter -necc -\family default - The number of stars in the eccentricity -\begin_inset Formula $e$ -\end_inset - - dimension of the grid. - If -\begin_inset Formula $1$ -\end_inset - - then the eccentricity is constant (usually zero, depends on the -\family typewriter -bse_option -\family default -). - -\emph on - Please use the flexigrid instead of this option. -\end_layout - -\begin_layout Description - -\family typewriter -newline -\family default - If -\family typewriter -vb=1 -\family default - then the value of this option is used as the end of line character. - You can use either -\family typewriter - -\begin_inset Quotes eld -\end_inset - - -\backslash -x0d -\begin_inset Quotes erd -\end_inset - - -\family default - (just a carriage return) or -\family typewriter - -\begin_inset Quotes eld -\end_inset - - -\backslash -n -\begin_inset Quotes erd -\end_inset - - -\family default - which is the carriage return with a line feed (the usual concept of -\begin_inset Quotes eld -\end_inset - -new line -\begin_inset Quotes erd -\end_inset - -). -\end_layout - -\begin_layout Description - -\family typewriter -nice -\family default - A string containing the nice command used to run -\shape italic -binary_c/nucsyn -\shape default -. - Usually no nice is used, so this is ' -\family typewriter -nice -n +0 -\family default -'. - You can leave this as it is and run ' -\family typewriter -nice grid.pl -\family default -' if you want the whole grid to be -\begin_inset Quotes eld -\end_inset - -niced -\begin_inset Quotes erd -\end_inset - -. -\end_layout - -\begin_layout Description - -\family typewriter -nmlow -\family default - The grid uses the values in the -\family typewriter -@mlist -\family default - between index -\family typewriter -nmlow -\family default - and -\family typewriter -nmhigh -\family default -. - If zero then all stars are used. -\end_layout - -\begin_layout Description - -\family typewriter -nmhigh -\family default - See -\family typewriter -nmlow -\family default -. -\end_layout - -\begin_layout Description - -\family typewriter -nm -\family default - The number of single star masses -\begin_inset Formula $M$ -\end_inset - - used in the grid. -\emph on - -\begin_inset space ~ -\end_inset - -Please use the flexigrid instead of this option. -\end_layout - -\begin_layout Description - -\family typewriter -nm1 -\family default - The number of primary star masses -\begin_inset Formula $M_{1}$ -\end_inset - - used in the grid. -\emph on - -\begin_inset space ~ -\end_inset - -Please use the flexigrid instead of this option. -\end_layout - -\begin_layout Description - -\family typewriter -nmod -\family default - When -\family typewriter -vb=1 -\family default - information on the grid is output every -\family typewriter -nmod -\family default - models or, if -\family typewriter -nmod -\family default - is zero, once every second. -\end_layout - -\begin_layout Description - -\family typewriter -nper -\family default - The number of stars in the period -\begin_inset Formula $P$ -\end_inset - - dimension. -\emph on - -\begin_inset space ~ -\end_inset - -Please use the flexigrid instead of this option. -\end_layout - -\begin_layout Description - -\family typewriter -nsep -\family default - The number of stars in the separation -\begin_inset Formula $a$ -\end_inset - - dimension. -\emph on - -\begin_inset space ~ -\end_inset - -Please use the flexigrid instead of this option. -\end_layout - -\begin_layout Description - -\family typewriter -parse_bse_function_pointer -\family default - In your grid script you need to define a subroutine (also known as a function) - to be used for data parsing. - Usually this is called -\family typewriter -parse_bse -\family default -. - and is set with a line in -\emph on -grid-xxx.pl -\emph default - like this: -\begin_inset Newline newline -\end_inset - - -\family typewriter -$binary_grid::grid_options{'parse_bse_function_pointer'}= -\backslash -&parse_bse; -\family default - -\begin_inset Newline newline -\end_inset - -You have to provide a pointer to this function in order that the grid software - knows where to send the output of -\emph on -binary_c/nucsyn -\emph default -. -\end_layout - -\begin_layout Description - -\family typewriter -period_dist -\family default - You may want to use a period-based initial distribution instead of the - default separation distribution, e.g. - for the -\begin_inset CommandInset citation -LatexCommand citet -key "1991A&A...248..485D" - -\end_inset - - initial distribution. - In this case set -\family typewriter -sepdist -\family default - to -\family typewriter - -\begin_inset Quotes eld -\end_inset - -period -\begin_inset Quotes erd -\end_inset - - -\family default - and choose -\family typewriter -period_dist= -\begin_inset Quotes erd -\end_inset - -gaussian -\begin_inset Quotes erd -\end_inset - - -\family default -. - (See -\emph on -IMF.pm -\emph default - for options.) Note that a Gaussian distribution requires a given minimum - and maximum period to be specified (in order that it normalises to -\begin_inset Formula $1$ -\end_inset - -). -\end_layout - -\begin_layout Description - -\family typewriter -period_dist_log_min -\family default - Minimum log period ( -\begin_inset Formula $\log_{10}P$ -\end_inset - -) of the initial distribution in days. - -\emph on - -\begin_inset space ~ -\end_inset - -Please use the flexigrid instead of this option. -\end_layout - -\begin_layout Description - -\family typewriter -period_dist_log_max -\family default - Maximum log period ( -\begin_inset Formula $\log_{10}P$ -\end_inset - -) of the initial distribution in days. -\emph on - -\begin_inset space ~ -\end_inset - -Please use the flexigrid instead of this option. -\end_layout - -\begin_layout Description - -\family typewriter -period_dist_mean_log -\family default - (log) Mean of the Gaussian period distribution in days. -\emph on - -\begin_inset space ~ -\end_inset - -Please use the flexigrid instead of this option. -\end_layout - -\begin_layout Description - -\family typewriter -period_dist_sigma -\family default - The width of the period distribution Gaussian (log days). -\emph on - -\begin_inset space ~ -\end_inset - -Please use the flexigrid instead of this option. -\end_layout - -\begin_layout Description - -\family typewriter -period_log_min -\family default - The minimum log period (days) in the period grid (not the initial distribution). -\emph on - -\begin_inset space ~ -\end_inset - -Please use the flexigrid instead of this option. -\end_layout - -\begin_layout Description - -\family typewriter -period_log_max -\family default - The maximum log period (days) in the period grid (not the initial distribution). -\emph on - -\begin_inset space ~ -\end_inset - -Please use the flexigrid instead of this option. -\end_layout - -\begin_layout Description - -\family typewriter -plaw_m0 -\family default - Minimum mass of the three-part power law -\begin_inset CommandInset citation -LatexCommand citet* -key "KTG1993MNRAS-262-545K" - -\end_inset - - initial mass function ( -\begin_inset Formula $0.1\,\mathrm{M}_{\odot}$ -\end_inset - -). -\emph on - -\begin_inset space ~ -\end_inset - -Please use the flexigrid instead of this option. -\end_layout - -\begin_layout Description - -\family typewriter -plaw_m1 -\family default - Mass break 1 of the three-part power law -\begin_inset CommandInset citation -LatexCommand citet* -key "KTG1993MNRAS-262-545K" - -\end_inset - - initial mass function ( -\begin_inset Formula $0.5\,\mathrm{M}_{\odot}$ -\end_inset - -). -\emph on - -\begin_inset space ~ -\end_inset - -Please use the flexigrid instead of this option. -\end_layout - -\begin_layout Description - -\family typewriter -plaw_m2 -\family default - Mass break 2 of the three-part power law -\begin_inset CommandInset citation -LatexCommand citet* -key "KTG1993MNRAS-262-545K" - -\end_inset - - initial mass function ( -\begin_inset Formula $1.0\,\mathrm{M}_{\odot}$ -\end_inset - -). -\emph on - -\begin_inset space ~ -\end_inset - -Please use the flexigrid instead of this option. -\end_layout - -\begin_layout Description - -\family typewriter -plaw_mmax -\family default - Maximum mass of the three-part power law -\begin_inset CommandInset citation -LatexCommand citet* -key "KTG1993MNRAS-262-545K" - -\end_inset - - initial mass function ( -\begin_inset Formula $80\,\mathrm{M}_{\odot}$ -\end_inset - -). -\emph on - -\begin_inset space ~ -\end_inset - -Please use the flexigrid instead of this option. -\end_layout - -\begin_layout Description - -\family typewriter -plaw_p -\family default - Slope of the (single) power-law initial mass function (e.g. - -\begin_inset Formula $-2.35$ -\end_inset - - for Salpeter). -\emph on - -\begin_inset space ~ -\end_inset - -Please use the flexigrid instead of this option. -\end_layout - -\begin_layout Description - -\family typewriter -plaw_p1 -\family default - Slope 1 of the three-part power law -\begin_inset CommandInset citation -LatexCommand citet* -key "KTG1993MNRAS-262-545K" - -\end_inset - - initial mass function ( -\begin_inset Formula $-1.3$ -\end_inset - -). -\emph on - -\begin_inset space ~ -\end_inset - -Please use the flexigrid instead of this option. -\end_layout - -\begin_layout Description - -\family typewriter -plaw_p2 -\family default - Slope 2 of the three-part power law -\begin_inset CommandInset citation -LatexCommand citet* -key "KTG1993MNRAS-262-545K" - -\end_inset - - initial mass function ( -\begin_inset Formula $-2.2$ -\end_inset - -). -\emph on - -\begin_inset space ~ -\end_inset - -Please use the flexigrid instead of this option. -\end_layout - -\begin_layout Description - -\family typewriter -plaw_p3 -\family default - Slope 3 of the three-part power law -\begin_inset CommandInset citation -LatexCommand citet* -key "KTG1993MNRAS-262-545K" - -\end_inset - - initial mass function ( -\begin_inset Formula $-2.7$ -\end_inset - -). -\emph on - -\begin_inset space ~ -\end_inset - -Please use the flexigrid instead of this option. -\end_layout - -\begin_layout Description - -\family typewriter -prob1 -\family default - If this is set to -\begin_inset Formula $1$ -\end_inset - - then all probabilities are -\begin_inset Formula $1.0$ -\end_inset - - (i.e. - -\family typewriter -calc_prob -\family default - is ignored). -\end_layout - -\begin_layout Description - -\family typewriter -prog -\family default - The -\emph on -binary_c/nucsyn -\emph default - executable name, usually ' -\family typewriter -binary_c -\family default -'. - See also -\family typewriter -rootpath -\family default -. -\end_layout - -\begin_layout Description - -\family typewriter -progenitor -\family default - Not really a grid option, but stores the system information ( -\begin_inset Formula $M$ -\end_inset - - or -\begin_inset Formula $M_{1}$ -\end_inset - -, -\begin_inset Formula $M_{2}$ -\end_inset - -, -\begin_inset Formula $a$ -\end_inset - -, -\begin_inset Formula $P$ -\end_inset - -, -\begin_inset Formula $e$ -\end_inset - -, -\begin_inset Formula $p$ -\end_inset - - etc.) -- useful for debugging or logging. -\end_layout - -\begin_layout Description - -\family typewriter -progenitor_hash -\family default - As progenitor but stores each item in a hash. -\end_layout - -\begin_layout Description - -\family typewriter -qmax -\family default - The maximum value of -\begin_inset Formula $q=M_{1}/M_{2}$ -\end_inset - - allowed in the grid, usually -\begin_inset Formula $1$ -\end_inset - -. -\end_layout - -\begin_layout Description - -\family typewriter -q_mean -\family default - When using a -\family typewriter -imf2= -\begin_inset Quotes erd -\end_inset - -gaussian -\begin_inset Quotes erd -\end_inset - - -\family default - the secondary mass ratio -\begin_inset Formula $q$ -\end_inset - - distribution is a Gaussian with centre -\family typewriter -q_mean -\family default - and width -\family typewriter -q_sigma -\family default -. - Useful for setting up a secondary mass distribution according to -\begin_inset CommandInset citation -LatexCommand citet -key "1991A&A...248..485D" - -\end_inset - -. - See also Section -\begin_inset space ~ -\end_inset - - -\begin_inset CommandInset ref -LatexCommand ref -reference "sec:initial-dists" - -\end_inset - -. -\emph on - -\begin_inset space ~ -\end_inset - -Please use the flexigrid instead of this option. -\end_layout - -\begin_layout Description - -\family typewriter -q_sigma -\family default - See -\family typewriter -q_mean -\family default -. -\emph on - -\begin_inset space ~ -\end_inset - -Please use the flexigrid instead of this option. -\end_layout - -\begin_layout Description - -\family typewriter -ref_tick_file -\family default - File from which timer (tick count) information is loaded. - See -\family typewriter -tick_counts -\family default -. - -\emph on - -\begin_inset space ~ -\end_inset - -Please use the flexigrid instead of this option -- -\emph default - -\begin_inset space ~ -\end_inset - -tick counts were used in the old -\family typewriter -threaded_grid -\family default - but are no longer required -\emph on -. -\end_layout - -\begin_layout Description - -\family typewriter -repeat -\family default - The number of times -\family typewriter -tbse() -\family default - is called for each grid point, default is -\begin_inset Formula $1$ -\end_inset - -. - This is useful for increasing the resolution in situations where Monte-Carlo - methods are used such as the random supernova or white dwarf kicks. -\end_layout - -\begin_layout Description - -\family typewriter -rootpath -\family default - The directory in which the -\emph on -binary_c/nucsyn -\emph default - code source and executable reside. - See also -\family typewriter -prog -\family default -. -\end_layout - -\begin_layout Description - -\family typewriter -runtime_function_pointer -\family default - A custom function which returns the time it takes (in CPU seconds) to run - a star of a given mass, used to split the single/primary mass range into - chunks and hence for load balancing in the threaded grid. - This is the old way of doing things, newer grids should use the tick counts - to time the runs of a test grid. - -\emph on - -\begin_inset space ~ -\end_inset - -Please use the flexigrid instead of this option. -\end_layout - -\begin_layout Description - -\family typewriter -runtime_lowmass -\family default - The runtime for a low-mass star that would otherwise never be run. - -\begin_inset Newline newline -\end_inset - -See -\family typewriter -runtime_function_pointer -\family default -. -\emph on - -\begin_inset space ~ -\end_inset - -Please use the flexigrid instead of this option. -\end_layout - -\begin_layout Description - -\family typewriter -secondary_mass_generator_function -\family default - Function to generate the list of secondary masses. - Usually this is set to the default function -\family typewriter - -\backslash -&populate_m2list -\family default -. -\emph on - -\begin_inset space ~ -\end_inset - -Please use the flexigrid instead of this option. -\end_layout - -\begin_layout Description - -\family typewriter -sepdist -\family default - The initial separation distribution, usually -\family typewriter - -\begin_inset Quotes eld -\end_inset - -flat -\begin_inset Quotes erd -\end_inset - - -\family default -, see -\emph on -IMF.pm -\emph default - (Section -\begin_inset space ~ -\end_inset - - -\begin_inset CommandInset ref -LatexCommand ref -reference "sec:initial-dists" - -\end_inset - -). -\emph on - -\begin_inset space ~ -\end_inset - -Please use the flexigrid instead of this option. -\end_layout - -\begin_layout Description - -\family typewriter -sepdist_exponent -\family default - If the separation distribution is a power law, the exponent is given by - this option. -\emph on - -\begin_inset space ~ -\end_inset - -Please use the flexigrid instead of this option. -\end_layout - -\begin_layout Description - -\family typewriter -sepdist_min -\family default - The minimum initial separation (solar radii) in the initial separation - distribution (but -\emph on -not -\emph default - the grid). -\emph on - -\begin_inset space ~ -\end_inset - -Please use the flexigrid instead of this option. -\end_layout - -\begin_layout Description - -\family typewriter -sepdist_max -\family default - The maximum initial separation (solar radii) in the initial separation - distribution (but -\emph on -not -\emph default - the grid). -\emph on - -\begin_inset space ~ -\end_inset - -Please use the flexigrid instead of this option. -\end_layout - -\begin_layout Description - -\family typewriter -sepmax -\family default - The maximum separation -\begin_inset Formula $a$ -\end_inset - - of the grid (solar radii). - -\emph on - -\begin_inset space ~ -\end_inset - -Please use the flexigrid instead of this option. -\end_layout - -\begin_layout Description - -\family typewriter -sepmin -\family default - The minimum separation -\begin_inset Formula $a$ -\end_inset - - of the grid (solar radii). -\emph on - -\begin_inset space ~ -\end_inset - -Please use the flexigrid instead of this option. -\end_layout - -\begin_layout Description - -\family typewriter -stellar_lifetime_table_nm -\family default - When the time adaptive mass grid is used (see -\family typewriter -time_adaptive_mass_grid -\family default -) a function is required to convert from stellar mass to stellar lifetimes. - This is interpolated from a (small) table of (single-star) models run at - the beginning of the grid. - -\family typewriter -stellar_lifetime_table_nm -\family default - is (approximately) the number of stars in this table, although -\family typewriter -time_adaptive_mass_grid_nlow _mass_stars -\family default - is the number of stars at low-mass in the table (because this probably - requires extra resolution due to -\begin_inset Formula $t\sim M^{3}$ -\end_inset - -) and there can also be extra stars around the helium flash lifetime (see - -\family typewriter -extra_flash_resolution -\family default -). -\end_layout - -\begin_layout Description - -\family typewriter -test -\family default - If test is set to 1 then the grid is run without calling tbse for each - system. - This is useful for testing the grid or calculating the total mass in stars. -\end_layout - -\begin_layout Description - -\family typewriter -test_grid_function_pointer -\family default - A pointer to a function which is called for each star in a test grid. - Ignored if -\family typewriter -undef -\family default -. -\end_layout - -\begin_layout Description - -\family typewriter -test_grid_mmax -\family default - The maximum single/primary mass used when running the test grid. -\end_layout - -\begin_layout Description - -\family typewriter -test_grid_mmin -\family default - The minimum single/primary mass used when running the test grid. -\end_layout - -\begin_layout Description - -\family typewriter -test_grid_only -\family default - If 1 then the code exits immediately after running the test grid. -\end_layout - -\begin_layout Description - -\family typewriter -thread_max_freeze_time_before_warning -\family default - The maximum time a thread loops its calls to -\family typewriter -tbse() -\family default - before a warning is issued (seconds, default 10). -\end_layout - -\begin_layout Description - -\family typewriter -thread_num -\family default - Not really an option, but stores the thread number of the current grid, - or -\family typewriter -undef -\family default - if threads are not being used. -\end_layout - -\begin_layout Description - -\family typewriter -thread_precreate_function_pointer -\family default - A pointer to a function to be called just before -\family typewriter -threads->create -\family default - is used to start a thread. - Ignored if -\family typewriter -undef -\family default -. -\end_layout - -\begin_layout Description - -\family typewriter -thread_prejoin_function_pointer -\family default - A pointer to a function called just before a thread is -\family typewriter -join -\family default -ed. - Ignored if -\family typewriter -undef -\family default -. -\end_layout - -\begin_layout Description - -\family typewriter -thread_presleep -\family default -A thread waits for this length of time (in seconds) before it starts in - order that all other threads have time to start before any output is logged - to the screen. - As such this is just to keep output pretty and should be small (default - 1 second). -\end_layout - -\begin_layout Description - -\family typewriter -thread_postjoin_function_pointer -\family default - A pointer to a function called just after a thread is -\family typewriter -join -\family default -ed. - Ignored if -\family typewriter -undef -\family default -. -\end_layout - -\begin_layout Description - -\family typewriter -thread_postrun_function_pointer -\family default - A pointer to a function to be called just after a -\family typewriter -thread->create -\family default - call (and just after -\family typewriter -$@ -\family default - is checked for a thread-creation error). - Ignored if -\family typewriter -undef -\family default -. -\end_layout - -\begin_layout Description - -\family typewriter -threads_entry_fun -\family default - A pointer to a function called from inside a thread just before grid() - is called. -\end_layout - -\begin_layout Description - -\family typewriter -threads_flush_fun -\family default - A pointer to a function called from inside a thread just after grid() returns. -\end_layout - -\begin_layout Description - -\family typewriter -threads_join_function_pointer -\family default - When using a threaded grid you have to define a subroutine (also known - as a function) pointer which points to the function to be called after - each thread have finished. - This function is responsible for -\begin_inset Quotes eld -\end_inset - -joining -\begin_inset Quotes erd -\end_inset - - the threads, which means it collects the results from the thread and adds - them to the global results. - This is usually a function called -\family typewriter -join_thread -\family default - and is set with a line in grid-xxx.pl similar to: -\begin_inset Newline newline -\end_inset - - -\family typewriter -$binary_grid::grid_options{'threads_join_function_pointer'}= -\backslash -&join_thread; -\end_layout - -\begin_layout Description - -\family typewriter -threads_stack_size -\family default - The stack size (in MBytes) for each of the Perl threads launched when -\family typewriter - -\begin_inset Newline newline -\end_inset - -threaded_grid -\family default - is used (see Section -\begin_inset space ~ -\end_inset - - -\begin_inset CommandInset ref -LatexCommand ref -reference "sec:threads" - -\end_inset - -). - Default is 32 (MBytes). -\end_layout - -\begin_layout Description - -\family typewriter -tick_counts -\family default - When threaded grids are used, the time it takes to run a system can be - computed using the tick_counts method. - With sufficiently accurate timing the load of each thread can be calculated - in advance and the mass grid split up accordingly. - This currently works only on CPUs which support the -\emph on -binary_c/nucsyn -\emph default - code options (see -\family typewriter -code_options.h -\family default -) -\family typewriter -RDTSC -\family default - and -\family typewriter -RDTSC_TIMER_PER_SYSTEM -\family default - (i.e. - Intel/AMD and compatible x86 architectures). - Note that if -\family typewriter -tick_counts -\family default - is 1 then tick clounts are merely saved, to -\emph on -use -\emph default -them you have to set -\family typewriter -use_ref_tick_counts -\family default - to 1. - This means you can rerun the grid without rerunning the tick count test - grid (instead the file is used, -\begin_inset Newline newline -\end_inset - -see -\family typewriter -tick_counts_file -\family default -). -\end_layout - -\begin_layout Description - -\family typewriter -tick_counts_file -\family default - File in which the timer (tick count) information is saved. -\end_layout - -\begin_layout Description - -\family typewriter -time_adaptive_mass_grid -\family default - This activates the time-adaptive mass grid such that the initial single/primary - masses -\begin_inset Formula $M_{1}$ -\end_inset - - are chosen to given equal -\begin_inset Quotes eld -\end_inset - -output -\begin_inset Quotes erd -\end_inset - - per unit time. - In this case -\begin_inset Quotes eld -\end_inset - -output -\begin_inset Quotes erd -\end_inset - - means stellar yield (i.e. - mass ejected) but this mostly comes at the end of the stellar evolution, - so the -\family typewriter -time_adaptive_mass_grid -\family default - can be used for other things such as supernovae which also occur then. - See the other -\family typewriter -time_adaptive_mass_grid -\family default - options and -\family typewriter -stellar_lifetime_table_nm -\family default -. -\end_layout - -\begin_layout Description - -\family typewriter -time_adaptive_mass_grid_step -\family default - The step in time -\begin_inset Formula $\Delta t$ -\end_inset - - which is converted to a corresponding -\begin_inset Formula $\Delta M_{1}$ -\end_inset - - in the -\family typewriter -time_adaptive_mass_grid -\family default - (see previous). -\end_layout - -\begin_layout Description - -\family typewriter -time_adaptive_mass_grid_log10_time -\family default - If this is true then instead of -\begin_inset Formula $\Delta M_{1}$ -\end_inset - - giving equal spacing in time -\begin_inset Formula $t$ -\end_inset - - instead equal spacing is calculated in -\begin_inset Formula $\log t$ -\end_inset - -. -\end_layout - -\begin_layout Description - -\family typewriter -time_adaptive_mass_grid_log10_step -\family default - -\begin_inset Formula $\Delta\log t$ -\end_inset - - for the previous entry. -\end_layout - -\begin_layout Description - -\family typewriter -time_adaptive_mass_grid_nlow_mass_stars -\family default - The number of low-mass stars run in the test grid which calculates stellar - lifetimes. - See -\family typewriter -stellar_lifetime_table_nm -\family default -. -\end_layout - -\begin_layout Description - -\family typewriter -timeout -\family default - When possible the grid sets an alarm (a Linux/UNIX signal) which means - that warnings are given and perhaps the grid stopped after -\family typewriter -timeout -\family default - seconds. - Set to zero to ignore, usually 30 is enough. - This assumes your -\emph on - binary_c/nucsyn -\emph default - process takes less than -\family typewriter -timeout -\family default - seconds to run a system so if you have problems with this please check - your system to make sure you have the CPU time you need. -\end_layout - -\begin_layout Description - -\family typewriter -use_ref_tick_counts -\family default - Switches on the use of tick count information for load balancing. - See -\family typewriter -tick_counts -\family default -. -\emph on - -\begin_inset space ~ -\end_inset - -Please use the flexigrid instead of this option. -\end_layout - -\begin_layout Description - -\family typewriter -vb -\family default - Verbosity level. - With -\family typewriter -vb=1 -\family default - you get some output about the grid, i.e. - the number of stars run, the number to go, the current -\begin_inset Formula $M$ -\end_inset - -, or -\begin_inset Formula $M_{1}$ -\end_inset - -, -\begin_inset space ~ -\end_inset - - -\begin_inset Formula $M_{2}$ -\end_inset - - and -\begin_inset Formula $a$ -\end_inset - -, an estimate of the time taken, time remaining and the time at which the - grid is expected to finish. - You may also get information about memory usage (if available). - Make sure your terminal window is quite wide to accommodate the information! - If -\family typewriter -vb=2 -\family default - you will get additional information about each system. - This is very useful for determining which stellar system is causing the - code to freeze and/or crash. - See also -\family typewriter -nmod -\family default -, -\family typewriter -colour -\family default - and -\family typewriter -log_args -\family default -. - Some verbose logging is only switched on if -\family typewriter -vb=3 -\family default -, although this should be considered experimental. -\end_layout - -\begin_layout Standard -\begin_inset Newpage pagebreak -\end_inset - - -\end_layout - -\begin_layout Section -Flexigrid -\end_layout - -\begin_layout Standard -\begin_inset CommandInset label -LatexCommand label -name "sec:flexigrid" - -\end_inset - -As of summer 2011, the -\begin_inset Quotes eld -\end_inset - -flexigrid -\begin_inset Quotes erd -\end_inset - - was developed. - This is an attempt to replace much of the old grid framework with a new, - dynamic set of instructions which are much more flexible. - The key concepts are the following: -\end_layout - -\begin_layout Itemize -When a flexigrid is run, it sets up -\begin_inset Formula $n$ -\end_inset - - threads each of which runs a star (or group of stars) at a time. - This is done -\emph on -as soon as a thread is free -\emph default - so load balancing is as good as it is possible to be. -\end_layout - -\begin_layout Itemize -Flexigrid sets up its -\begin_inset Formula $M_{1}-M_{2}-a$ -\end_inset - - etc. - grid -\emph on -dynamically -\emph default -. - It does this by writing the grid code itself and then compiling it with - Perl's -\emph on -eval -\emph default - command. - This means it is truly flexible, you can add or remove -\emph on -any variable you like -\emph default - to the grid and do not have to write any new code in the -\emph on -binary_grid -\emph default - module! -\end_layout - -\begin_layout Itemize -The standard version of flexigrid uses a multithreaded, local binary_c model. - However, in development is a binary_c-daemon which distributes the load - across remote machines on a network. -\end_layout - -\begin_layout Itemize -The grid spacing is now given by a Perl function and hence is -\emph on -not -\emph default - fixed. - -\end_layout - -\begin_layout Itemize -Probabilities are calculated more efficiently in an attempt to phase out - the -\emph on -IMF -\emph default - module in favour of the -\emph on -distribution_functions -\emph default - module. -\end_layout - -\begin_layout Subsection -Setup in your grid script -\end_layout - -\begin_layout Standard -You need to do two things: -\end_layout - -\begin_layout Enumerate -Call -\family typewriter -flexigrid( -\emph on -n -\emph default -); -\family default - instead of -\family typewriter -threaded_grid( -\emph on -n -\emph default -); -\end_layout - -\begin_layout Enumerate -Set up the grid in the -\family typewriter -grid_options -\family default -hash -\end_layout - -\begin_layout Standard -The call to -\family typewriter -flexigrid -\family default - is simple enough, where the argument is (as with -\family typewriter -threaded_grid -\family default -) the number of threads. - Next, some variables must be set in the grid_options hash in order that - the grid can be created. -\end_layout - -\begin_layout Subsubsection -Grid variables: 1D example -\end_layout - -\begin_layout Standard -Setting up which variables you use is best defined by example. - Let's start with -\begin_inset Formula $M_{1}$ -\end_inset - - which you will usually require. - First, define the grid resolution as $n -\begin_inset Formula $\times$ -\end_inset - -$n -\begin_inset Formula $\times$ -\end_inset - -$n (here -\begin_inset Formula $10\times10\times10$ -\end_inset - -) -\end_layout - -\begin_layout Standard - -\family typewriter -$n=10; -\family default - -\begin_inset Newline newline -\end_inset - -Next, set up the variable number corresponding to the grid variable. - Each grid variable must have a unique number, starting with 0 and working - upward. - -\end_layout - -\begin_layout Standard - -\family typewriter -my $nvar=0; -\family default - -\begin_inset Newline newline -\end_inset - - -\begin_inset Newline newline -\end_inset - -Now use an -\emph on -anonymous hash -\emph default - in the grid option {'flexigrid'}{'grid variable '.$nvar} to give the options: -\begin_inset Newline newline -\end_inset - - -\end_layout - -\begin_layout Standard - -\family typewriter -\begin_inset Box Frameless -position "t" -hor_pos "c" -has_inner_box 1 -inner_pos "t" -use_parbox 0 -use_makebox 0 -width "100col%" -special "none" -height "1in" -height_special "totalheight" -status open - -\begin_layout Plain Layout - -\family typewriter -# Mass 1 -\end_layout - -\begin_layout Plain Layout - -\family typewriter -$binary_grid::grid_options{'flexigrid'}{'grid variable '.$nvar++}= -\end_layout - -\begin_layout Plain Layout - -\family typewriter -{ -\end_layout - -\begin_layout Plain Layout - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -'name'=>'lnm1', -\end_layout - -\begin_layout Plain Layout - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -'longname'=>'Primary_Mass', -\end_layout - -\begin_layout Plain Layout - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -'range' => ["log($binary_grid::grid_options{'mmin'})", -\end_layout - -\begin_layout Plain Layout - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -"log($binary_grid::grid_options{'mmax'})"], -\end_layout - -\begin_layout Plain Layout - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -'resolution'=>$n, -\end_layout - -\begin_layout Plain Layout - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -'spacingfunc'=>"const(log($binary_grid::grid_options{'mmin'}),log($binary_grid:: -grid_options{'mmax'}),$n)", -\end_layout - -\begin_layout Plain Layout - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -'precode'=>"my -\backslash -$m1=exp( -\backslash -$lnm1);my -\backslash -$eccentricity=0.0;", -\end_layout - -\begin_layout Plain Layout - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -'probdist'=>"ktg93( -\backslash -$m1)* -\backslash -$m1", -\end_layout - -\begin_layout Plain Layout - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -'dphasevol'=>" -\backslash -$dlnm1 " -\end_layout - -\begin_layout Plain Layout - -\family typewriter -}; -\end_layout - -\end_inset - - -\family default -(Note the -\family typewriter -++ -\family default - after -\family typewriter -$nvar -\family default - which raises the variable number for the next variable. -\family typewriter -) -\begin_inset Newline newline -\end_inset - - -\end_layout - -\begin_layout Standard -What does this mean? -\end_layout - -\begin_layout Labeling -\labelwidthstring 00.00.0000 -name -\begin_inset space ~ -\end_inset - - -\emph on -string -\emph default - This is the variable name. - It should be parsable in Perl, e.g. - in the above case it is expanded to -\family typewriter -$lnm1 -\family default - in the gridcode. -\end_layout - -\begin_layout Labeling -\labelwidthstring 00.00.0000 -longname -\begin_inset space ~ -\end_inset - - -\emph on -string -\emph default - This is a long (human-readable) name used in logging. - It should contain no spaces (use underscores). -\end_layout - -\begin_layout Labeling -\labelwidthstring 00.00.0000 -range -\begin_inset space ~ -\end_inset - - -\emph on -x -\emph default - -\begin_inset space ~ -\end_inset - - -\emph on -y -\emph default - This defines the range of the grid, from -\emph on -x -\emph default - to -\emph on -y. - -\emph default - In the above case from -\family typewriter -log(0.1) -\family default - to -\family typewriter -log(80.0) -\family default -. - (We are using a grid in -\emph on -log -\emph default - -\begin_inset Formula $M_{1}$ -\end_inset - -.) Note that this is an -\emph on -anonymous array -\emph default -. - which must be declared with -\family typewriter -[ -\emph on -min -\emph default -, -\emph on -max -\emph default -] -\family default -. -\end_layout - -\begin_layout Labeling -\labelwidthstring 00.00.0000 -resolution -\begin_inset space ~ -\end_inset - - -\emph on -n -\emph default -This is the grid resolution, given above by -\family typewriter -$n -\family default -. -\end_layout - -\begin_layout Labeling -\labelwidthstring 00.00.0000 -spacingfunc -\begin_inset space ~ -\end_inset - - -\emph on -func -\emph default -This defines the spacing function which should be in the -\emph on -spacing_functions -\emph default - Perl module. - In the above example the spacing is constant between -\family typewriter -log(0.1) -\family default -and -\family typewriter - log(80.0) -\family default -with -\family typewriter - $n -\family default -steps. -\end_layout - -\begin_layout Labeling -\labelwidthstring 00.00.0000 -precode -\begin_inset space ~ -\end_inset - - -\emph on -code -\emph default -This is code executed before the next part of the grid is set up. - In our case we have to specify -\family typewriter -$m1 -\family default - because we have only calculated -\family typewriter -$lnm1 -\family default -. - We also set up the eccentricity because there is no grid for this and it - is required. - -\end_layout - -\begin_layout Labeling -\labelwidthstring 00.00.0000 -postcode -\begin_inset space ~ -\end_inset - - -\emph on -code -\emph default -This is code executed after the next part of the grid is set up. - (In our case there is no -\emph on -postcode -\emph default -). -\end_layout - -\begin_layout Labeling -\labelwidthstring 00.00.0000 -probdist -\begin_inset space ~ -\end_inset - - -\emph on -func -\emph default -This is a probability distribution function as given in the -\emph on -distribution_functions -\emph default - Perl module. - In the above we use the -\family typewriter -ktg93 -\family default - (Kroupa, Tout, Gilmore 1993 IMF) function. - -\end_layout - -\begin_layout Labeling -\labelwidthstring 00.00.0000 -dphasevol -\begin_inset space ~ -\end_inset - - -\emph on -expression -\emph default -This defines the contribution to the phase volume from this variable. - In general this is just -\family typewriter -$dlnm1 -\family default - (i.e. - should be -\family typewriter -$d -\emph on -name -\family default -\emph default -) but you can set it to whatever you like. - -\end_layout - -\begin_layout Subsection -3D grid example -\end_layout - -\begin_layout Standard -The next step is to set up the further grid variables. - Usually these are -\begin_inset Formula $M_{2}$ -\end_inset - - and -\begin_inset Formula $a$ -\end_inset - -, as defined in the code below. -\end_layout - -\begin_layout Standard - -\family typewriter -\begin_inset Box Frameless -position "t" -hor_pos "c" -has_inner_box 1 -inner_pos "t" -use_parbox 0 -use_makebox 0 -width "100col%" -special "none" -height "1in" -height_special "totalheight" -status open - -\begin_layout Plain Layout - -\family typewriter -# Binary stars: Mass 2 and Separation -\end_layout - -\begin_layout Plain Layout - -\family typewriter -if($binary_grid::grid_options{'binary'}) -\end_layout - -\begin_layout Plain Layout - -\family typewriter -{ -\end_layout - -\begin_layout Plain Layout - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -$binary_grid::grid_options{'flexigrid'}{'grid variable '.$nvar++}= -\end_layout - -\begin_layout Plain Layout - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -{ -\end_layout - -\begin_layout Plain Layout - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -'name'=>'m2', -\end_layout - -\begin_layout Plain Layout - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -'longname'=>'Secondary_mass', -\end_layout - -\begin_layout Plain Layout - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -'range'=>[$binary_grid::grid_options{'m2min'},'$m1'], -\end_layout - -\begin_layout Plain Layout - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -'resolution'=>$n, -\end_layout - -\begin_layout Plain Layout - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -'spacingfunc'=>"const($binary_grid::grid_options{'m2min'}, -\backslash -$m1,$n)", -\end_layout - -\begin_layout Plain Layout - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -'probdist'=>"const($binary_grid::grid_options{'m2min'}, -\backslash -$m1)", -\end_layout - -\begin_layout Plain Layout - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -'dphasevol','$dm2' -\end_layout - -\begin_layout Plain Layout - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -}; -\end_layout - -\begin_layout Plain Layout - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -$binary_grid::grid_options{'flexigrid'}{'grid variable '.$nvar++}= -\end_layout - -\begin_layout Plain Layout - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -{ -\end_layout - -\begin_layout Plain Layout - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -'name'=>'lnsep', -\end_layout - -\begin_layout Plain Layout - -\family typewriter -'longname'=>'ln(Orbital_Separation)', -\end_layout - -\begin_layout Plain Layout - -\family typewriter -'range'=>['log(3.0)','log(1e4)'], -\end_layout - -\begin_layout Plain Layout - -\family typewriter -'resolution',$n, -\end_layout - -\begin_layout Plain Layout - -\family typewriter -'spacingfunc',"const(log(3.0),log(1e4),$n)", -\end_layout - -\begin_layout Plain Layout - -\family typewriter -'precode'=>"my -\backslash -$sep=exp( -\backslash -$lnsep);my -\backslash -$per=calc_period_from_sep( -\backslash -$m1, -\backslash -$m2, -\backslash -$sep);", -\end_layout - -\begin_layout Plain Layout - -\family typewriter -'probdist'=>'const(log(3.0),log(1e4))', -\end_layout - -\begin_layout Plain Layout - -\family typewriter -'dphasevol'=>'$dlnsep' -\end_layout - -\begin_layout Plain Layout - -\family typewriter -} -\end_layout - -\begin_layout Plain Layout - -\family typewriter -} -\end_layout - -\end_inset - - -\end_layout - -\begin_layout Standard -The above setup has the same general form as for -\begin_inset Formula $M_{1}$ -\end_inset - - but with different spacing functions (the -\emph on -const -\emph default - spacing function is used, for -\begin_inset Formula $M_{2}$ -\end_inset - - in the range -\begin_inset Formula $0.1$ -\end_inset - - to -\begin_inset Formula $M_{1}$ -\end_inset - - and for -\begin_inset Formula $\ln a$ -\end_inset - - in the range -\begin_inset Formula $3$ -\end_inset - - to -\begin_inset Formula $10^{4}$ -\end_inset - -). -\end_layout - -\begin_layout Subsection -Gridcode -\end_layout - -\begin_layout Standard -The complete example from the above is -\begin_inset Newline newline -\end_inset - - -\begin_inset Newline newline -\end_inset - - -\begin_inset Box Frameless -position "t" -hor_pos "c" -has_inner_box 1 -inner_pos "t" -use_parbox 0 -use_makebox 0 -width "100col%" -special "none" -height "1in" -height_special "totalheight" -status open - -\begin_layout Plain Layout - -\family typewriter -$n=10; # grid resolution -\begin_inset Newline newline -\end_inset - -my $nvar=0; # variable number -\end_layout - -\begin_layout Plain Layout - -\family typewriter -# Mass 1 -\end_layout - -\begin_layout Plain Layout - -\family typewriter -$binary_grid::grid_options{'flexigrid'}{'grid variable '.$nvar++}= -\end_layout - -\begin_layout Plain Layout - -\family typewriter -{ -\end_layout - -\begin_layout Plain Layout - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -'name'=>'lnm1', -\end_layout - -\begin_layout Plain Layout - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -'longname'=>'Primary_Mass', -\end_layout - -\begin_layout Plain Layout - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -'range' => ["log($binary_grid::grid_options{'mmin'})", -\end_layout - -\begin_layout Plain Layout - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -"log($binary_grid::grid_options{'mmax'})"], -\end_layout - -\begin_layout Plain Layout - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -'resolution'=>$n, -\end_layout - -\begin_layout Plain Layout - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -'spacingfunc'=>"const(log($binary_grid::grid_options{'mmin'}),log($binary_grid:: -grid_options{'mmax'}),$n)", -\end_layout - -\begin_layout Plain Layout - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -'precode'=>"my -\backslash -$m1=exp( -\backslash -$lnm1);my -\backslash -$eccentricity=0.0;", -\end_layout - -\begin_layout Plain Layout - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -'probdist'=>"ktg93( -\backslash -$m1)* -\backslash -$m1", -\end_layout - -\begin_layout Plain Layout - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -'dphasevol'=>" -\backslash -$dlnm1 " -\end_layout - -\begin_layout Plain Layout - -\family typewriter -}; -\end_layout - -\begin_layout Plain Layout - -\family typewriter -# Binary stars: Mass 2 and Separation -\end_layout - -\begin_layout Plain Layout - -\family typewriter -if($binary_grid::grid_options{'binary'}) -\end_layout - -\begin_layout Plain Layout - -\family typewriter -{ -\end_layout - -\begin_layout Plain Layout - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -$binary_grid::grid_options{'flexigrid'}{'grid variable '.$nvar++}= -\end_layout - -\begin_layout Plain Layout - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -"name m2 longname Secondary_mass range 0.1 -\backslash -$m1 resolution $n spacingfunc const(0.1, -\backslash -$m1,$n) probdist const(0.1/ -\backslash -$m1,1.0) dphasevol -\backslash -$dm2 "; -\end_layout - -\begin_layout Plain Layout - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -$binary_grid::grid_options{'flexigrid'}{'grid variable '.$nvar++}= -\end_layout - -\begin_layout Plain Layout - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -"name lnsep longname ln(Orbital_Separation) range log(3.0) log(1e4) resolution - $n spacingfunc const(log(3.0),log(1e4),$n) precode my -\backslash -$sep=exp( -\backslash -$lnsep);my -\backslash -$per=calc_period_from_sep( -\backslash -$m1, -\backslash -$m2, -\backslash -$sep); probdist const(log(3.0),log(1e4)) dphasevol -\backslash -$dlnsep "; -\end_layout - -\begin_layout Plain Layout - -\family typewriter -} -\end_layout - -\end_inset - - -\begin_inset Newline newline -\end_inset - -When you run -\family typewriter -flexigrid(2); -\family default - in your grid script, a (flexi)grid with two threads will be run. - You can find the code that is constructed by the -\emph on -binary_grid -\emph default - module in the file -\family typewriter -/tmp/gridcode -\family default - (view it with -\emph on -less -\emph default - or some other tool that can parse ANSI colours, or set -\family typewriter -$binary_grid::grid_options{'colour'}=0; -\family default -). -\end_layout - -\begin_layout Subsection -Technical details -\end_layout - -\begin_layout Standard -This code is, of course, still under development. - Please use it with care! -\end_layout - -\begin_layout Itemize -I have replaced calls to tbse with calls to run_binary_c which is a more - flexible function (and will be used by the binary_c daemon once the remote-mach -ine version is complete). -\end_layout - -\begin_layout Itemize -$starcount should equal the number of stars run on the grid. - -\end_layout - -\begin_layout Itemize -@starcount stores the number of stars run in each subgrid. -\end_layout - -\begin_layout Itemize -The array @prob stores the contribution to the probability from each variable - separately (except the final variable, for which $prob is calculated). - This assumes, as always, that the probability density functions are separable. -\end_layout - -\begin_layout Standard -\begin_inset Newpage pagebreak -\end_inset - - -\end_layout - -\begin_layout Section -Initial distributions (IMF etc.) -\end_layout - -\begin_layout Standard -\begin_inset CommandInset label -LatexCommand label -name "sec:initial-dists" - -\end_inset - -The initial distributions of stellar masses, mass ratios, separations and - periods are handled by the -\emph on -IMF.pm -\emph default - Perl module. - The general idea is that given a set of stellar parameters -\begin_inset Formula $M_{1}$ -\end_inset - -, -\begin_inset Formula $M_{2}$ -\end_inset - - and -\begin_inset Formula $a$ -\end_inset - - (or -\begin_inset Formula $P$ -\end_inset - -) and phase volume -\begin_inset Formula $\delta\ln M_{1}$ -\end_inset - -, -\begin_inset Formula $\delta\ln M_{2}$ -\end_inset - - and -\begin_inset Formula $\delta\ln a$ -\end_inset - - (or -\begin_inset Formula $\delta\ln P$ -\end_inset - -) the probability of existence of star -\begin_inset Formula $i$ -\end_inset - - is calculated from -\end_layout - -\begin_layout Standard -\begin_inset Formula -\begin{eqnarray} -p_{i} & = & \Psi(M_{1})\Phi(M_{2})\chi(a)\,\delta\ln M_{1}\,\delta\ln M_{2}\,\delta\ln a\nonumber \\ - & = & \Psi\Phi\chi\delta\ln V\label{eq:prob-eq} -\end{eqnarray} - -\end_inset - -where -\begin_inset Formula $\delta\ln V$ -\end_inset - - is the 'logphasevol' (as stored in the progenitor hash, see Section -\begin_inset space ~ -\end_inset - - -\begin_inset CommandInset ref -LatexCommand ref -reference "sec:grid-options" - -\end_inset - -). - The functions -\begin_inset Formula $\Psi$ -\end_inset - -, -\begin_inset Formula $\Phi$ -\end_inset - - and -\begin_inset Formula $\chi$ -\end_inset - - are not necessarily independent (e.g. - -\begin_inset Formula $\Phi(M_{2})$ -\end_inset - - may actually be -\begin_inset Formula $\Phi(q=M_{2}/M_{1})$ -\end_inset - - in which case it depends on -\begin_inset Formula $M_{1}$ -\end_inset - -) but the assumption we make is that -\begin_inset Formula $p_{i}$ -\end_inset - - is separable. - Note that -\begin_inset Formula $\sum p_{i}$ -\end_inset - - must add to one, i.e. - -\begin_inset Formula $\int p\, dV=1$ -\end_inset - -. - In general, each of the distributions must also satisfy -\begin_inset Formula $\int\Psi(M_{1})dM_{1}=\int\Psi(M_{2})dM_{2}=\int\chi(a)da=1$ -\end_inset - - where the integrals are from -\begin_inset Formula $-\infty$ -\end_inset - - to -\begin_inset Formula $+\infty$ -\end_inset - -. -\end_layout - -\begin_layout Standard -There are many forms for each initial distributions and they depend on which - authors you believe and/or which stars you are looking at (e.g. - low- or high-mass stars). - There is no one true answer -- yet! -\end_layout - -\begin_layout Subsection -The distribution_functions module -\end_layout - -\begin_layout Standard -In earlier versions of binary_grid, the distribution functions were built - into the -\begin_inset Quotes eld -\end_inset - -IMF -\begin_inset Quotes erd -\end_inset - - module. - In the latest binary_grid, however, which uses Flexigrid (see Section -\begin_inset space ~ -\end_inset - - -\begin_inset CommandInset ref -LatexCommand ref -reference "sec:flexigrid" - -\end_inset - -) these distribution functions are found in the distribution_functions module - instead. - This is much more flexible, for example it allows the functions -\begin_inset Formula $\Psi$ -\end_inset - -, -\begin_inset Formula $\Phi$ -\end_inset - -, -\begin_inset Formula $\chi$ -\end_inset - - etc. - to be completely arbitrary. -\end_layout - -\begin_layout Subsection -Predefined functions -\end_layout - -\begin_layout Description -const( -\begin_inset Formula $a$ -\end_inset - -, -\begin_inset Formula $b$ -\end_inset - -, -\begin_inset Formula $x$ -\end_inset - -) Returns a constant distribution function between -\begin_inset Formula $x$ -\end_inset - - and -\begin_inset Formula $y$ -\end_inset - - i.e. - returns -\begin_inset Formula $1/(b-a)$ -\end_inset - -. - -\begin_inset Formula $x$ -\end_inset - - is optional, if given then a result is returned only if -\begin_inset Formula $a\geq x\geq b$ -\end_inset - -, otherwise zero. - (This is useful for specifying a flat- -\begin_inset Formula $q$ -\end_inset - - distribution for the secondary mass or a flat- -\begin_inset Formula $\ln a$ -\end_inset - - separation distribution.) -\end_layout - -\begin_layout Description -powerlaw( -\begin_inset Formula $a$ -\end_inset - -, -\begin_inset Formula $b$ -\end_inset - -, -\begin_inset Formula $k$ -\end_inset - -, -\begin_inset Formula $x$ -\end_inset - -) A power-law distribution in -\begin_inset Formula $x$ -\end_inset - - between -\begin_inset Formula $a$ -\end_inset - - and -\begin_inset Formula $b$ -\end_inset - - with slope -\begin_inset Formula $k$ -\end_inset - -, zero if out of range. -\end_layout - -\begin_layout Description -three_part_power_law( -\begin_inset Formula $x$ -\end_inset - -, -\begin_inset Formula $x_{0}$ -\end_inset - -, -\begin_inset Formula $x_{1}$ -\end_inset - -, -\begin_inset Formula $x_{2}$ -\end_inset - -, -\begin_inset Formula $x_{\mathrm{max}}$ -\end_inset - -, -\begin_inset Formula $p_{1}$ -\end_inset - -, -\begin_inset Formula $p_{2}$ -\end_inset - -, -\begin_inset Formula $p_{3}$ -\end_inset - -, -\family typewriter -$consts -\family default -) A three-part power-law distrubition between -\begin_inset Formula $x_{0}$ -\end_inset - - and -\begin_inset Formula $x_{\mathrm{max}}$ -\end_inset - -, with slopes -\begin_inset Formula $p_{i}$ -\end_inset - - between -\begin_inset Formula $x_{i-1}$ -\end_inset - - and -\begin_inset Formula $x_{i}$ -\end_inset - - ( -\begin_inset Formula $i=1,2,3$ -\end_inset - -), zero otherwise. -\begin_inset Newline newline -\end_inset - - -\family typewriter -$consts -\family default - is optional: it can be built by calling -\family typewriter -initialize_three_part_power_law(@opts,$consts) -\family default - before calling -\family typewriter -three_part_power_law() -\family default - (where -\family typewriter -@opts -\family default - contains -\begin_inset Formula $x$ -\end_inset - -, -\begin_inset Formula $x_{0}$ -\end_inset - -, -\begin_inset Formula $x_{1}$ -\end_inset - -, -\begin_inset Formula $x_{2}$ -\end_inset - -, -\begin_inset Formula $x_{\mathrm{max}}$ -\end_inset - -, -\begin_inset Formula $p_{1}$ -\end_inset - -, -\begin_inset Formula $p_{2}$ -\end_inset - -, -\begin_inset Formula $p_{3}$ -\end_inset - -). - Why do this? Well, for a general three-part power law, you have to normalise - -- this imposes a calculation overhead. - You can put the results of the normalisation in -\family typewriter -$consts -\family default - and -- if the power-law you use is a constant, you do not have to calculate - these normalisation constants again\SpecialChar \@. - The -\family typewriter -ktg93() -\family default - function does exactly what is described above (see the module code for - details). -\end_layout - -\begin_layout Description -ktg93( -\begin_inset Formula $M$ -\end_inset - -) A wrapper function to use the Kroupa, Tout & Gilmore 1993 initial mass - function for mass -\begin_inset Formula $M$ -\end_inset - -. - All the constants are set up for you, you just have to specify the mass - -\begin_inset Formula $M$ -\end_inset - -. - Easy! -\end_layout - -\begin_layout Standard -\begin_inset Newpage pagebreak -\end_inset - - -\end_layout - -\begin_layout Section -Debugging options -\end_layout - -\begin_layout Standard -\begin_inset CommandInset label -LatexCommand label -name "sec:debugging" - -\end_inset - -This section provides a summary of debugging options and suggestions for - ways to fix your code (or -\emph on -binary_grid -\emph default -!). - -\end_layout - -\begin_layout Itemize - -\family typewriter -$binary_grid::grid_options{'vb'} -\family default - controls the amount of grid output to the screen, usually lines showing - the number of stars evolved, the total number in the grid, the current - time, -\begin_inset Formula $M_{1}$ -\end_inset - -, -\begin_inset Formula $M_{2}$ -\end_inset - -, -\begin_inset Formula $a$ -\end_inset - -, -\begin_inset Formula $P$ -\end_inset - - and -\begin_inset Formula $Z$ -\end_inset - -, the probability, the total grid probability, -\begin_inset Formula $\%$ -\end_inset - - grid completion, estimated time until arrival (finish) i.e. - -\emph on -ETA -\emph default -, -\emph on -tpr -\emph default - (time per run), ETF (estimated time at which it will finish) and memory - usage. - If set to 1 it shows output every second or every -\family typewriter -$binary_grid::grid_options{'nmod'} -\family default - models. - If -\family typewriter -vb -\family default - is set to -\family typewriter -2 -\family default - then more output, showing the arguments sent to -\emph on -binary_c/nucsyn -\emph default -, will be dumped onto the screen for each model. - This is only useful for small grids, for large grids it will overwhelm - you. - It is possible to set -\family typewriter -vb=3 -\family default - but this is experimental. -\end_layout - -\begin_layout Itemize - -\family typewriter -$binary_grid::grid_options{'log_args'} -\family default - will output the arguments sent to -\emph on -binary_c/nucsyn -\emph default - in files in -\family typewriter -/tmp/ -\family default -. - In unthreaded grids these go in -\family typewriter -/tmp/binary_c.lastargs -\family default - while in threaded grids -\family typewriter -/tmp/binary_c.thread_$n.lastargs -\family default - where -\family typewriter -$n -\family default - is the thread number. - This is a more practical approach to debugging individual systems in large - grids than -\family typewriter -vb=2 -\family default -. - It is also useful in the case where your code freezes, because as long - as the code is frozen you can access the final model (for each thread) - in the files and then rerun them with -\family typewriter -tbse -\family default - to see where it went wrong. -\end_layout - -\begin_layout Itemize - -\family typewriter -$binary_grid::grid_options{'args'} -\family default - stores a single string with the raw arguments that were passed into -\emph on -binary_c/nucsyn -\emph default -. - This is useful if you want to do some debugging in the parse_bse function - (which has access to this variable). -\end_layout - -\begin_layout Itemize - -\family typewriter -$binary_grid::grid_options{'progenitor'} -\family default - stores the progenitor information in a single string, in the following - order: binarity, -\begin_inset Formula $M_{1}$ -\end_inset - -, -\begin_inset Formula $M_{2}$ -\end_inset - -, -\begin_inset Formula $P$ -\end_inset - -, -\begin_inset Formula $a$ -\end_inset - -, -\begin_inset Formula $e$ -\end_inset - -, -\begin_inset Formula $Z$ -\end_inset - -, -\begin_inset Formula $P$ -\end_inset - - and -\begin_inset Formula $\delta\ln V$ -\end_inset - - (the ' -\family typewriter -logphasevol -\family default -'= -\begin_inset Formula $\delta\ln M_{1}\delta\ln M_{2}\delta a$ -\end_inset - -). - If the star is a single star ( -\family roman -binarity -\family typewriter -==0 -\family default -) then -\begin_inset Formula $M_{2}$ -\end_inset - -, -\begin_inset Formula $P$ -\end_inset - -, -\begin_inset Formula $a$ -\end_inset - - and -\begin_inset Formula $e$ -\end_inset - - are omitted and -\begin_inset Formula $\delta\ln V=\delta\ln M$ -\end_inset - -. - This data is accessible from -\family typewriter -parse_bse -\family default -. -\end_layout - -\begin_layout Itemize -The hash-in-a-hash -\family typewriter - -\begin_inset Newline newline -\end_inset - -%binary_grid::grid_options{'progenitor_hash'}{ -\begin_inset Formula $\dots$ -\end_inset - -} -\family default - -\begin_inset Newline newline -\end_inset - -contains the same information as the progenitor string (above) in a more - accessible form: the hash -\emph on -keys -\emph default - are binarity, -\begin_inset Formula $M_{1}$ -\end_inset - -, -\begin_inset Formula $M_{2}$ -\end_inset - -, -\begin_inset Formula $P$ -\end_inset - -, -\begin_inset Formula $a$ -\end_inset - -, -\begin_inset Formula $e$ -\end_inset - -, -\begin_inset Formula $Z$ -\end_inset - -, -\begin_inset Formula $P$ -\end_inset - - and -\begin_inset Formula $\delta\ln V$ -\end_inset - -, and the values contain the appropriate data. - Again, this is accessible from -\family typewriter -parse_bse -\family default -. -\end_layout - -\begin_layout Itemize -Use the -\family typewriter -test_grid -\family default - if you are running a full grid and want to test if your initial distributions - integrate such that -\begin_inset Formula $\sum_{i}p_{i}=1$ -\end_inset - -. -\end_layout - -\begin_layout Itemize -Use the -\family typewriter -timeout -\family default - feature if your code is freezing. - This is -\emph on -not -\emph default - the same as fixing your problem, but you may be able to stop the code from - using all your CPU when it freezes! -\end_layout - -\begin_layout Standard -\begin_inset Newpage pagebreak -\end_inset - - -\end_layout - -\begin_layout Section -Future Plans -\end_layout - -\begin_layout Standard -\begin_inset CommandInset label -LatexCommand label -name "sec:future-plans" - -\end_inset - - -\end_layout - -\begin_layout Itemize -The period and separation grid functions could be extended to include other - distributions. -\end_layout - -\begin_layout Itemize -A graphical frontend would be good! -\end_layout - -\begin_layout Itemize -There once was an adaptive grid which zoomed into areas of special interest, - should this be resurrected? -\end_layout - -\begin_layout Standard -\begin_inset Newpage pagebreak -\end_inset - - -\end_layout - -\begin_layout Section -FAQ -\end_layout - -\begin_layout Standard -\begin_inset CommandInset label -LatexCommand label -name "sec:FAQ" - -\end_inset - - -\end_layout - -\begin_layout Description -Why -\begin_inset space ~ -\end_inset - -not -\begin_inset space ~ -\end_inset - -Monte -\begin_inset space ~ -\end_inset - -Carlo? The alternative to running a grid is a Monte Carlo method, where - you throw systems in according to some initial distribution and a random - number generator. - In the high number limit this should give the -\emph on -same -\emph default - -\emph on -result -\emph default -as a grid. - However, in the low-number limit, the results are probably going to be - different, and this is when you test your code. - The big advantage of a grid is that you have a good handle on -\emph on -errors -\emph default - due to the finite resolution of your sampling of the initial distribution(s) - without the smearing out of a Monte Carlo approach. - Furthermore, MC may accidentally miss part of the initial parameter space - (it is, after all, random) which you know is covered by a grid approach - (at least to within a known error e.g. - -\begin_inset Formula $\delta\ln M_{1}$ -\end_inset - -). - You are also guaranteed, on a grid, to sample even the rare systems which - would be sparsely populated (if at all) in an MC simulation. - Such systems will have a small probability per star, -\begin_inset Formula $p_{i}$ -\end_inset - -, but on the other hand these might be the systems of particular interest - to you! -\begin_inset Newline newline -\end_inset - -Note that as of August 2012, Monte Carlo simulations are available with - the -\emph on -flexigrid. -\end_layout - -\begin_layout Description -Why -\begin_inset space ~ -\end_inset - -MC -\begin_inset space ~ -\end_inset - -SN -\begin_inset space ~ -\end_inset - -kicks? Traditionally supernova (and white dwarf) kicks have had their velocity - chosen in a Monte-Carlo way, rather than on a grid. - This was left as-is because there are four dimensions for each kick, which - -- given a coarse grid of -\begin_inset Formula $10\times10\times10\times10$ -\end_inset - - -- means the parameter space expands by a factor of -\begin_inset Formula $1,\,000$ -\end_inset - - for stars with kicks. - The runtime increase is not worth the effort as in order to finish anything - in your lifetime you would have to either buy a supercomputer or run such - a coarse grid in the original parameters that the whole exercise becomes - pointless. - The brute force resolution test is what you need here: just keep increasing - the resolution until the numbers converge. - It helps if you are clever about it: if you're interested in supernovae - only then -\begin_inset Formula $M_{1}$ -\end_inset - - is probably the dimension that requires the most resolution, or perhaps - -\begin_inset Formula $M_{2}$ -\end_inset - -, but probably not -\begin_inset Formula $a$ -\end_inset - -. -\end_layout - -\begin_layout Description -Zombie -\begin_inset space ~ -\end_inset - -binary_c -\begin_inset space ~ -\end_inset - -processes When the grid exits abnormally, or is killed, a -\emph on -binary_c/nucsyn -\emph default - process may be left behind in an infinite loop state and as such will take - up your precious CPU time. - You will have to kill it manually -\emph on -if you are sure it is not doing anything with another grid process! -\emph default -(Be careful and do -\emph on -not -\emph default - do -\begin_inset Quotes eld -\end_inset - -killall binary_c -\begin_inset Quotes erd -\end_inset - - as root\SpecialChar \ldots{} -) -\end_layout - -\begin_layout Description -Zombie -\begin_inset space ~ -\end_inset - -Perl -\begin_inset space ~ -\end_inset - -processes These should die naturally when the grid finishes and the Perl - script exits. - They are harmless and have never been seen to consume CPU time. -\end_layout - -\begin_layout Standard -\begin_inset Newpage pagebreak -\end_inset - - -\end_layout - -\begin_layout Section -Threaded grids -\end_layout - -\begin_layout Standard - -\emph on -This section is deprecated. - You should use the flexigrid as described above in Section -\begin_inset space ~ -\end_inset - - -\begin_inset CommandInset ref -LatexCommand ref -reference "sec:flexigrid" - -\end_inset - - -\end_layout - -\begin_layout Standard -\begin_inset CommandInset label -LatexCommand label -name "sec:threads" - -\end_inset - -When -\emph on -binary_grid -\emph default - was originally developed, multi-core CPUs were unheard of and multi-CPU - systems rare. - However, these days they are common, so a simple technique was developed - to make the grid function on multi-CPU/core systems. - The grid over single-star masses, -\begin_inset Formula $M$ -\end_inset - -, or primary-star masses, -\begin_inset Formula $M_{1}$ -\end_inset - -, is now split into chunks and each chunk given to a CPU via a native Perl - -\begin_inset Quotes eld -\end_inset - -thread -\begin_inset Quotes erd -\end_inset - - (see e.g. - -\begin_inset Flex URL -status collapsed - -\begin_layout Plain Layout - -http://search.cpan.org/~jdhedden/threads-1.79/lib/threads.pm -\end_layout - -\end_inset - -, you will need to have a thread-capable Perl and install the -\family typewriter -threads-shared -\family default - module). - The difficult trick is to make the chunks equal in runtime and to perform - the accounting when -\begin_inset Quotes eld -\end_inset - -joining -\begin_inset Quotes erd -\end_inset - - the results of the threads. -\end_layout - -\begin_layout Subsection -The threaded grid -\end_layout - -\begin_layout Standard -\begin_inset CommandInset label -LatexCommand label -name "sub:threaded-grid" - -\end_inset - -From the perspective of the user, only a few things have to change in order - to use a threaded grid. - In -\emph on -grid-xxx.pl -\emph default - you just have to set -\family typewriter -$usethreads=1 -\family default -. - This calls the following code: -\begin_inset Newline newline -\end_inset - - -\end_layout - -\begin_layout Standard - -\family typewriter -if($usethreads) -\end_layout - -\begin_layout Standard - -\family typewriter -{ -\end_layout - -\begin_layout Standard - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -use threads; -\end_layout - -\begin_layout Standard - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -threaded_grid(); -\end_layout - -\begin_layout Standard - -\family typewriter -} -\begin_inset Newline newline -\end_inset - - -\family default - -\begin_inset Newline newline -\end_inset - -The -\family typewriter -threaded_grid -\family default - function takes an argument which is the number of threads. - If no argument is given the number of threads is automatically allocated - (usually from the number of CPUs, if that information is available). - -\end_layout - -\begin_layout Standard -Nothing else needs to change, except that you have to save data in a specific - format in -\family typewriter -parse_bse -\family default - and set up a -\family typewriter -join -\family default - function. - These are described in the following sections. -\end_layout - -\begin_layout Standard -A good example of a threaded grid is provided in the -\emph on -grid-hrd.pl -\emph default - script which was used to make multi-dimensional HR diagrams (also in time - and -\begin_inset Formula $\log g$ -\end_inset - -). - -\end_layout - -\begin_layout Subsection -Setting up your parse_bse -\end_layout - -\begin_layout Standard -\begin_inset CommandInset label -LatexCommand label -name "sub:parse-bse-threads" - -\end_inset - -The -\family typewriter -parse_bse -\family default - function is basically the same as with a single-thread grid, except that - you -\emph on -must -\emph default - save your results in a hash -\family typewriter -%h -\family default -. - Once the thread has run its sub-grid, it sends the results to the join - function (see the next section) which takes the -\family typewriter -%h -\family default - hash and adds it to the global results. -\end_layout - -\begin_layout Standard -The hash -\family typewriter -%h -\family default - can be used to store multi-dimensional data, e.g. - distributions (histograms). - In some cases you'll want to store numbers of stars, something like: -\begin_inset Newline newline -\end_inset - - -\end_layout - -\begin_layout Standard - -\family typewriter -$dtp = $p * $dt; -\end_layout - -\begin_layout Standard - -\family typewriter -$h{'R star'} += $dtp; -\family default - -\begin_inset Newline newline -\end_inset - - -\begin_inset Newline newline -\end_inset - -Perhaps you want to make histograms, e.g. - a luminosity function: -\begin_inset Newline newline -\end_inset - - -\end_layout - -\begin_layout Standard - -\family typewriter -$h{'Luminosity function'}{'10-20'}+=$dtp; -\family default - -\begin_inset Newline newline -\end_inset - - -\begin_inset Newline newline -\end_inset - -Perhaps you want to make histograms at given times: -\begin_inset Newline newline -\end_inset - - -\end_layout - -\begin_layout Standard - -\family typewriter -$h{'Luminosity function'}{'20 Myr'}{'30-40'}+=$dtp; -\family default - -\begin_inset Newline newline -\end_inset - - -\begin_inset Newline newline -\end_inset - - -\end_layout - -\begin_layout Standard -Similarly you can make -\begin_inset Formula $n$ -\end_inset - --dimensional hashes of hashes of hashes (or arrays!). - Perl is good for that. -\end_layout - -\begin_layout Subsection -Joining the results -\end_layout - -\begin_layout Standard -\begin_inset CommandInset label -LatexCommand label -name "sub:thread-join" - -\end_inset - -Once your thread has finished running its stars, it calls the join thread - function. - This is set in your grid-xxx.pl with a line like the following: -\begin_inset Newline newline -\end_inset - - -\end_layout - -\begin_layout Standard - -\family typewriter -$binary_grid::grid_options{'threads_join_function_pointer'}= -\backslash -&join_thread; -\family default - -\begin_inset Newline newline -\end_inset - - -\begin_inset Newline newline -\end_inset - -You have to write join_thread yourself. - It should take a pointer to a hash ( -\family typewriter -%h -\family default - in the thread, which must be dereferenced as -\family typewriter -%$h -\family default - in the join function). - It should look something like the following: -\begin_inset Newline newline -\end_inset - - -\end_layout - -\begin_layout Standard - -\family typewriter -sub join_thread -\end_layout - -\begin_layout Standard - -\family typewriter -{ -\end_layout - -\begin_layout Standard - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -# function which is called when a thread is joined: -\end_layout - -\begin_layout Standard - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -# Note that $h is a hash pointer which is used by binary_c threads -\end_layout - -\begin_layout Standard - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -# to collect data. - It dies when it goes out of scope, probably -\end_layout - -\begin_layout Standard - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -# after this function. -\begin_inset Newline newline -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\end_layout - -\begin_layout Standard - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -my $h=shift; -\begin_inset Newline newline -\end_inset - - -\end_layout - -\begin_layout Standard - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -# save the results -\begin_inset Newline newline -\end_inset - - -\end_layout - -\begin_layout Standard - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -foreach my $k (keys %$h) -\end_layout - -\begin_layout Standard - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -{ -\end_layout - -\begin_layout Standard - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -# add the data from %$h into a global hash -\end_layout - -\begin_layout Standard - -\family typewriter -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - - -\begin_inset space ~ -\end_inset - -} -\end_layout - -\begin_layout Standard - -\family typewriter -} -\family default - -\begin_inset Newline newline -\end_inset - - -\begin_inset Newline newline -\end_inset - -At present you will have to determine whether the hash is a simple hash, - hash of hashes, etc. - from the value of the string in -\family typewriter -$k -\family default -. - It may well be possible to automate this process, but so far that level - of sophistication has not proven necessary. - One way to do it may be to prepend the hash keys with a (e.g.) 'scalar', - 'array' or 'hash' string. -\end_layout - -\begin_layout Standard -Once all your threads have finished, control is restored to your -\emph on -grid-xxx.pl -\emph default - script and you can output the results from global hash. -\end_layout - -\begin_layout Subsection -Load balancing -\end_layout - -\begin_layout Standard -\begin_inset CommandInset label -LatexCommand label -name "sub:load-balancing" - -\end_inset - -The other difficulty with running threaded grids is to spread the workload - equally over the different CPUs/cores. - Because the grid is split according to primary/single-star mass -\begin_inset Formula $M_{1}$ -\end_inset - - we really need the workload for a given -\emph on -stellar mass -\emph default -. - There are two methods to doing this. - Both assume that the runtime as a function of -\begin_inset Formula $M_{1}$ -\end_inset - - is representative of the runtime of systems with parameters -\begin_inset Formula $M_{1}$ -\end_inset - -, -\begin_inset Formula $M_{2}$ -\end_inset - - and -\begin_inset Formula $a$ -\end_inset - -, i.e. - that single-star runtimes are representative of binary-star systems with - the same primary mass. - This seems to work well enough for the technique to work. -\end_layout - -\begin_layout Subsubsection -The function approximation -\end_layout - -\begin_layout Standard -You can provide a -\emph on -function -\emph default - which returns the runtime (in arbitrary units) as a function of -\begin_inset Formula $\log_{10}M$ -\end_inset - -. - This is not recommended but if you want to give it a try you can set -\family typewriter - -\begin_inset Newline newline -\end_inset - -$binary_grid::grid_options{'runtime_function_pointer'} -\family default - -\begin_inset Newline newline -\end_inset - -to point to the -\family typewriter -MS_lifetime -\family default - function in -\emph on -binary_grid -\emph default -, or write your own function. - Of course, this function has to be bug-free and accurate for your choice - of input physics. - -\family typewriter -MS_lifetime -\family default - takes into account (roughly) changes in metallicity, but that is all. -\end_layout - -\begin_layout Subsubsection -The timed-run approach -\end_layout - -\begin_layout Standard -The alternative approach is more accurate and takes into account changes - in the physics of your simulation. - To determine the runtime as a function of mass, a number of test models - are run. - The runtimes are put into a table which is then interpolated in order to - find the runtime as a function of mass for any mass. -\end_layout - -\begin_layout Standard -In order to use the timed-run approach, -\emph on -binary_c/nucsyn -\emph default - must be equipped to tell -\emph on -binary_grid -\emph default - the runtime of each star that it evolves. - The most common way to do this is to build in support for the -\family typewriter -RDTSC_TIMER -\family default - (and -\family typewriter -RDTSC_TIMER_PER_SYSTEM -\family default -) in -\family typewriter -code_options.h -\family default -. - This uses the Intel tick counter to tell you how many cycles have passed - for each system that is evolved, the -\begin_inset Quotes eld -\end_inset - -tick count -\begin_inset Quotes erd -\end_inset - -. - On running a single system with tbse you should see something like: -\begin_inset Newline newline -\end_inset - - -\end_layout - -\begin_layout Standard - -\family typewriter -Tick count 275804808, ~ runtime = 0.108842 repeat=1 -\family default - -\begin_inset Newline newline -\end_inset - - -\begin_inset Newline newline -\end_inset - - -\emph on -Binary_grid -\emph default - can use this information to construct a table of runtimes and then interpolate - on this to balance the loads equally across the threads. - Note that -\family typewriter -CPUFREQ -\family default - must be defined (in MHz, usually at code -\emph on -configure -\emph default - time) for a true runtime to be output, otherwise only the -\begin_inset Quotes eld -\end_inset - -tick count -\begin_inset Quotes erd -\end_inset - - will be available. -\end_layout - -\begin_layout Standard -On CPUs other than the Intel-compatibles you will have to use a different - timer. - You could try the virtual timer ( -\family typewriter -CC_TIMER -\family default - in -\family typewriter -code_options.h -\family default -) or write your own code for it (see the code in -\family typewriter -main.c -\family default -). -\end_layout - -\begin_layout Subsection -Thread timeout -\end_layout - -\begin_layout Standard -If a thread should appear to be -\begin_inset Quotes eld -\end_inset - -stuck -\begin_inset Quotes erd -\end_inset - - (i.e. - it contributes no output) after -\begin_inset Newline newline -\end_inset - - -\family typewriter -$binary_grid::grid_options{'thread_max_freeze_time_before_warning'} -\family default - seconds, a warning will be sent to the screen. -\end_layout - -\begin_layout Subsection -Thread flushing -\end_layout - -\begin_layout Standard -If you define a function pointed to by -\family typewriter -$binary_grid::grid_options{'threads_flush_func'} -\family default - this will be called at the end of the run of each thread (the -\begin_inset Quotes eld -\end_inset - -flush -\begin_inset Quotes erd -\end_inset - - stage) with a pointer to the -\family typewriter -%h -\family default - data hash passed as the only argument. -\end_layout - -\begin_layout Standard -\begin_inset Newpage pagebreak -\end_inset - - -\end_layout - -\begin_layout Standard - -\size scriptsize -\begin_inset CommandInset bibtex -LatexCommand bibtex -bibfiles "references" -options "apalike" - -\end_inset - - -\end_layout - -\end_body -\end_document diff --git a/doc/deprecated/binary_grid_images b/doc/deprecated/binary_grid_images deleted file mode 120000 index c2b4104c2448e139c5097787605c87218093ba6e..0000000000000000000000000000000000000000 --- a/doc/deprecated/binary_grid_images +++ /dev/null @@ -1 +0,0 @@ -../binary_grid_images/ \ No newline at end of file diff --git a/doc/deprecated/helpwiththecode.pdf b/doc/deprecated/helpwiththecode.pdf deleted file mode 100644 index d0a9b810a299ccdd0d465b7217abc7b71c486a61..0000000000000000000000000000000000000000 Binary files a/doc/deprecated/helpwiththecode.pdf and /dev/null differ diff --git a/doc/deprecated/nucsyn_manual.lyx b/doc/deprecated/nucsyn_manual.lyx deleted file mode 100644 index 6e51a0fc4ef740972bfa932ba522fcb9ed7a0cc4..0000000000000000000000000000000000000000 --- a/doc/deprecated/nucsyn_manual.lyx +++ /dev/null @@ -1,9140 +0,0 @@ -#LyX 2.1 created this file. For more info see http://www.lyx.org/ -\lyxformat 474 -\begin_document -\begin_header -\textclass scrartcl -\begin_preamble - -\newcommand{\mnras}{MNRAS} -\newcommand{\apj}{The Astrophysical Journal} -\newcommand{\apjl}{The Astrophysical Journal Letters} -\newcommand{\apjs}{The Astrophysical Journal Supplement Series} -\newcommand{\aj}{The Astronomical Journal} -\newcommand{\aap}{Astronomy and Astrophysics} -\newcommand{\araa}{Annual review of Astronomy and Astrophysics} -\newcommand{\aaps}{Astronomy \& Astrophysics Supplement Series} -\newcommand{\pasa}{PASA} - -\let\originalsection=\section -\renewcommand\section{\par\cleardoublepage\originalsection} -\end_preamble -\options referee,usenatbib -\use_default_options false -\maintain_unincluded_children false -\language english -\language_package default -\inputencoding auto -\fontencoding global -\font_roman default -\font_sans cmbr -\font_typewriter beramono -\font_math auto -\font_default_family sfdefault -\use_non_tex_fonts false -\font_sc false -\font_osf false -\font_sf_scale 100 -\font_tt_scale 65 -\graphics default -\default_output_format default -\output_sync 0 -\bibtex_command default -\index_command default -\paperfontsize 11 -\spacing single -\use_hyperref false -\papersize default -\use_geometry true -\use_package amsmath 2 -\use_package amssymb 2 -\use_package cancel 1 -\use_package esint 0 -\use_package mathdots 1 -\use_package mathtools 1 -\use_package mhchem 1 -\use_package stackrel 1 -\use_package stmaryrd 1 -\use_package undertilde 1 -\cite_engine natbib -\cite_engine_type authoryear -\biblio_style plainnat -\use_bibtopic false -\use_indices false -\paperorientation portrait -\suppress_date false -\justification true -\use_refstyle 0 -\index Index -\shortcut idx -\color #008000 -\end_index -\leftmargin 2cm -\topmargin 3cm -\rightmargin 2cm -\bottommargin 3cm -\secnumdepth 3 -\tocdepth 3 -\paragraph_separation indent -\paragraph_indentation default -\quotes_language english -\papercolumns 1 -\papersides 2 -\paperpagestyle fancy -\tracking_changes false -\output_changes false -\html_math_output 0 -\html_css_as_file 0 -\html_be_strict false -\end_header - -\begin_body - -\begin_layout Title -Slackers' guide to -\family typewriter -binary_c/nucsyn -\end_layout - -\begin_layout Standard -\align center -For version 1.2-, currently 1.20pre68 (SVN revision Cambridge/3483) -\end_layout - -\begin_layout Section -Disclaimer and Licence -\end_layout - -\begin_layout Standard -\begin_inset CommandInset label -LatexCommand label -name "sec:Disclaimer-and-Licence" - -\end_inset - -Please read this section before continuing. -\end_layout - -\begin_layout Subsection -Disclaimer -\end_layout - -\begin_layout Standard -\begin_inset CommandInset label -LatexCommand label -name "sub:Disclaimer" - -\end_inset - -Rob Izzard is -\emph on -not responsible -\emph default - for anything you do with this code, for the results etc. - are all up to you! You can check every line of source code if you like. - While Rob has done his best to make sure everything that follows (and in - his papers) is correct there are certainly bugs and omissions. - Please, if you find one, can you let him know. -\end_layout - -\begin_layout Subsection -Licence -\end_layout - -\begin_layout Standard -\begin_inset CommandInset label -LatexCommand label -name "sub:Licence" - -\end_inset - -Please read the LICENCE file provided in the -\emph on -binary_c -\emph default - directory tree. -\end_layout - -\begin_layout Section -Introduction -\end_layout - -\begin_layout Standard -\begin_inset CommandInset label -LatexCommand label -name "sec:Introduction" - -\end_inset - -From -\begin_inset CommandInset citation -LatexCommand citet -key "Izzard_et_al_2003c_Monash" - -\end_inset - -: -\end_layout - -\begin_layout Quotation -For many years the study of stellar yields and galactic chemical evolution - (GCE) has gone on assuming, mainly for simplicity, that stars are isolated - objects (one exception being -\begin_inset CommandInset citation -LatexCommand citealp -key "2002NewA....7...55D" - -\end_inset - -). - Reality bites deeply into this picture with the observation that most stars - are in multiple systems and that many of these systems are interacting. - The state of the art in binary star nucleosynthesis is focused on explosive - events such as type Ia supernovae and classical novae but other binary - star processes contribute to pollution of the interstellar medium. - Mass-transfer by Roche-lobe overflow (RLOF) occurs particularly when the - stellar radius is growing rapidly and so commonly when one star is on the - asymptotic giant branch (AGB). -\end_layout - -\begin_layout Standard -To investigate the effect of a companion on stellar nucleosynthesis the - -\family roman -\emph on -binary_c/nucsyn -\family default -\emph default - code was developed. - The -\emph on -binary_c -\emph default - code uses the -\emph on -BSE -\emph default - package at its core, with nucleosynthesis in parallel (the -\emph on -/nucsyn -\emph default -), to explore large parameter spaces in reasonable periods of time. - Mass lost from the binary system contributes to the stellar yield and since - the -\emph on -BSE -\emph default - code is based on the -\emph on -SSE -\emph default - code nucleosynthesis for populations of single stars is also calculated. - The two are then compared to see if there is any difference. -\end_layout - -\begin_layout Standard -Binaries are important for nucleosynthesis because of two main effects: -\end_layout - -\begin_layout Itemize -The presence of a companion affects evolution by mass loss and gain. - Good examples are RLOF due to interaction between a giant (GB/AGB) star - and a MS star. - Truncation of the GB/AGB phase may prevent dredge-up events and hence reduce - the amount of nuclear processing material undergoes prior to expulsion - to the ISM. - Common envelopes generally result and while the detailed physics is unclear - it is likely that mass is ejected to the ISM from some of these stars. - -\end_layout - -\begin_layout Itemize -Novae and SNeIa only occur in binaries. - What are the progenitors of SNeIa? We do not know - despite what you may - have been told! -\end_layout - -\begin_layout Standard -The physics of binary evolution is not all that well understood and suffers - all the uncertainties of single-star evolution. - Some effects which must be considered are: -\end_layout - -\begin_layout Itemize -Duplicity : single star or binary star. - -\end_layout - -\begin_layout Itemize -Metallicity and, less importantly, initial abundance mix. - The initial abundance mix depends on the galactic evolution history and - even the solar mix is somewhat uncertain. -\end_layout - -\begin_layout Itemize -Initial distributions: What is the IMF? What is the initial distribution - for primary mass, secondary mass, separation/period and eccentricity for - binary stars? -\end_layout - -\begin_layout Itemize -Abundance changes at dredge-ups. - These changes can depend on the input physics, especially in the case of - third dredge-up. - Calibration to observations is necessary in this case and leads to the - introduction of free parameters to increase the amount of dredge-up. - There is also great uncertainty with regard to the s-process isotopes, - in particular the size of the C13 pocket during third dredge-up. - -\end_layout - -\begin_layout Itemize -Wind loss rates. - Mass loss due to stellar winds is a very dodgy affair - most prescriptions - in current use are quite phenomenological and have little regard for actual - physics. - With this in mind it is important to test a range of prescriptions. - -\end_layout - -\begin_layout Itemize -Common envelope parameters - the parameters -\begin_inset Formula $\lambda_{\textrm{CE}}$ -\end_inset - - and -\begin_inset Formula $\alpha_{\textrm{CE}}$ -\end_inset - - parameterise our ignorance of this complex process, mainly because the - mechanism for driving off the stellar envelope is unclear (magnetic fields? - friction? ionization? who knows!). - -\end_layout - -\begin_layout Itemize -Eddington limit : should this be imposed during accretion processes? -\end_layout - -\begin_layout Itemize -HBB temperature : somewhat uncertain is the amount of HBB, this can be varied - in the model -\end_layout - -\begin_layout Itemize -Black hole formation : what is the mass of a black hole forming from a given - mass progenitor? -\end_layout - -\begin_layout Itemize -Supernova kicks : is there a kick at SN formation? What is the magnitude/distrib -ution of this kick? Pulsar peculiar velocities give us an idea but are not - necessarily the answer to the question. - -\end_layout - -\begin_layout Itemize -Binary induced wind loss (Companion Reinforced Attrition Process - CRAP) - - see Chris Tout's PhD. - Does the presence of a binary companion increase wind loss rates? What - about circularization? (Barium stars are eccentric and have short periods - -- current theory, and this code, cannot make these stars!) -\end_layout - -\begin_layout Itemize -Time evolution of the yields. - Even if the integrated yield up to (say) 15Gyr from a population of stars - is similar when comparing binary and single stars, the time evolution probably - is not. - For example, nitrogen peaks far more quickly in single than in binary stars - because massive ( -\begin_inset Formula $M>4\mathrm{\,M_{\odot}}$ -\end_inset - -) TPAGB stars in binaries overflow their Roche lobes prior to HBB so C12 - cannot be converted into N14. - -\end_layout - -\begin_layout Itemize -Numerical resolution - requires careful consideration! -\end_layout - -\begin_layout Standard -" -\family typewriter -binary_c / nucsyn -\family default -" is the trade name for the C-version of the -\emph on -B -\emph default -inary -\emph on -S -\emph default -tar -\emph on -E -\emph default -volution ( -\emph on -BSE -\emph default -) code of -\begin_inset CommandInset citation -LatexCommand citet -key "2002MNRAS_329_897H" - -\end_inset - - with added -\emph on -nucleo -\emph default -synthesis. - The nucleosynthesis algorithm runs (mostly) in parallel to the nucleosynthesis - code and includes the following (see -\begin_inset CommandInset citation -LatexCommand citealp -key "2006A&A...460..565I" - -\end_inset - -): -\end_layout - -\begin_layout Itemize -First and second dredge-up fitted to the detailed nucleosynthesis models - of -\begin_inset CommandInset citation -LatexCommand citet -key "Parameterising_3DUP_Karakas_Lattanzio_Pols" - -\end_inset - -. - -\end_layout - -\begin_layout Itemize -A new synthetic model of TPAGB stars -\begin_inset CommandInset citation -LatexCommand citep -key "Izzard_et_al_2003b_AGBs" - -\end_inset - - in collaboration with Amanda Karakas, Chris Tout and Onno Pols based on - the Karakas et al. - models. - The effects of third dredge-up, the -\begin_inset Formula $s$ -\end_inset - --process, hot-bottom burning (CNO, NeNa and MgAl) and mass loss are included. -\end_layout - -\begin_layout Itemize -Phenomenological fits to massive and Wolf-Rayet star surface abundances - (elemental H, He, CNO, Ne) based on the models of Lynnette Dray -\begin_inset CommandInset citation -LatexCommand citep -key "2003MNRAS.338..973D" - -\end_inset - -. - These were recently complemented by tables from Richard Stancliffe which - include all the -\emph on -isotopes -\emph default - up to iron (Stancliffe, private communication, see also -\begin_inset CommandInset citation -LatexCommand citealp -key "2006astro.ph.12390I" - -\end_inset - -). -\end_layout - -\begin_layout Itemize -Supernovae: types Ia, II and Ib/c with yields fitted to published models - -\begin_inset CommandInset citation -LatexCommand citep -key "1986ApJ...301..601W,1995ApJ...452...62L,1995ApJS..101..181W,1999ApJS..125..439I,2004ApJ...608..405C" - -\end_inset - -. -\end_layout - -\begin_layout Itemize -Nova yields fitted to -\begin_inset CommandInset citation -LatexCommand citet -key "1998ApJ...494..680J" - -\end_inset - -. - -\end_layout - -\begin_layout Itemize -\begin_inset Formula $r$ -\end_inset - --process -\begin_inset Quotes eld -\end_inset - -yields -\begin_inset Quotes erd -\end_inset - - (I say this in the loosest possible sense!) from Arlandini et al 1999. -\end_layout - -\begin_layout Itemize -Roche-Lobe Overflow and (possible) accretion onto the companion, common-envelope - loss contribution to yields. -\end_layout - -\begin_layout Itemize -Mass loss due to winds and mass gain from a companion. -\end_layout - -\begin_layout Itemize -Colliding winds. -\end_layout - -\begin_layout Itemize -Accretion is treated with a two-layer model and thermohaline mixing. -\end_layout - -\begin_layout Itemize -Mergers are treated approximately in the same way as -\emph on -BSE -\emph default - but with the abundances followed. -\end_layout - -\begin_layout Standard -What does the -\family typewriter -binary_c/nucsyn -\family default - code not do? -\end_layout - -\begin_layout Itemize -Diffusion - nobody plans to work on this! -\end_layout - -\begin_layout Itemize -"Extra mixing" - dubious although might be the cause of J-stars. - -\end_layout - -\begin_layout Itemize -Common envelope nucleosynthesis - thought not to be important, but you never - know. - -\end_layout - -\begin_layout Itemize -Accretion/stripping from companion supernovae -\end_layout - -\begin_layout Itemize -(Pre-)MS burning of the interior of the star - this means that if a MS star - is stripped the increase in C13/N14 due to CNO cycling is not taken into - account. - However, if the star makes it to 1st dredge up then this is taken into - account. - Note there is -\emph on -experimental -\emph default - code which can deal with this. -\end_layout - -\begin_layout Itemize -WD surface layers - these are very complicated! -\end_layout - -\begin_layout Itemize -Probably some other things too. -\end_layout - -\begin_layout Section -Simple Use -\end_layout - -\begin_layout Standard -\begin_inset CommandInset label -LatexCommand label -name "sec:Simple-Use" - -\end_inset - -This section is for people who just want to build and use the code but do - not want to hack the code or run grids of binaries. -\end_layout - -\begin_layout Standard -The web home of -\emph on -binary_c/nucsyn -\emph default - is -\begin_inset Flex URL -status collapsed - -\begin_layout Plain Layout - -http://www.ast.cam.ac.uk/~rgi/binary_c.html -\end_layout - -\end_inset - -. - The online binary-star simulator is at -\begin_inset Flex URL -status open - -\begin_layout Plain Layout - -http://www.ast.cam.ac.uk/~rgi/cgi-bin/binary4.cgi -\end_layout - -\end_inset - -. - If these should move, you can use your favourite web-search engine to locate - the code. -\end_layout - -\begin_layout Subsection -Requirements -\end_layout - -\begin_layout Standard -\begin_inset CommandInset label -LatexCommand label -name "sub:Requirements" - -\end_inset - -The following software is required on your system: -\end_layout - -\begin_layout Itemize -ANSI C compiler e.g. - -\emph on -gcc -\emph default - (GNU compiler -\begin_inset Flex URL -status collapsed - -\begin_layout Plain Layout - -http://gcc.gnu.org/ -\end_layout - -\end_inset - -), icc (Intel compiler -\begin_inset Flex URL -status collapsed - -\begin_layout Plain Layout - -http://software.intel.com/en-us/articles/intel-compilers/ -\end_layout - -\end_inset - -), cc (your system compiler, often this -\emph on -is -\emph default - gcc). - Your system should include such a compiler unless you're foolish enough - to use Windows. - The code has been tested on Linux and various Solaris machines. - Note that (for an unknown reason!) it does not run (but does compile) on - old versions of MacOS X. - If you can fix this problem please let me know! Also, there has been trouble - with gcc on Xeon machines. - This is not my fault, please use icc. -\begin_inset Foot -status collapsed - -\begin_layout Plain Layout -This information may be out of date! Please test the build and let me know. -\end_layout - -\end_inset - - -\end_layout - -\begin_layout Itemize - -\emph on -Perl -\emph default - - this is required for the configuration script. - Please see the separate -\emph on -binary_grid-flexigrid -\emph default -manual for information on this. - You can download Perl at -\begin_inset Flex URL -status collapsed - -\begin_layout Plain Layout - -www.perl.com -\end_layout - -\end_inset - -. -\end_layout - -\begin_layout Subsection -Getting binary_c/nucsyn -\end_layout - -\begin_layout Standard -There are two ways to get -\emph on -binary_c/nucsyn -\emph default -. -\end_layout - -\begin_layout Enumerate -You request a tarball/zipfile from Rob. - This is the simplest method, but you should only use this if you do not - plan to do anything but run the code\SpecialChar \@. - -\end_layout - -\begin_layout Enumerate -Ask for access to your own branch on the -\emph on -subversion -\emph default - (SVN) server (see Section -\begin_inset space ~ -\end_inset - - -\begin_inset CommandInset ref -LatexCommand ref -reference "sub:binary_c/subversion-access" - -\end_inset - -). - If you plan to update the physics in -\emph on -binary_c/nucsyn -\emph default - then you should do use SVN because it makes code update and code review - possible. -\end_layout - -\begin_layout Standard -You should consider joining the mailing lists (see Sec. -\begin_inset space ~ -\end_inset - - -\begin_inset CommandInset ref -LatexCommand ref -reference "sub:mailing-lists" - -\end_inset - -). -\end_layout - -\begin_layout Subsection -Building -\end_layout - -\begin_layout Standard -\begin_inset CommandInset label -LatexCommand label -name "sub:Building" - -\end_inset - -If have been given a file -\family typewriter -binary_c.zip, binary_c.tar.gz -\family default - or -\family typewriter -binary_c.tar.bz2 -\family default - which you should copy it to a directory (hereafter -\family typewriter -binary_c -\family default -, usually I put everything in -\family typewriter - -\begin_inset Formula $\sim$ -\end_inset - -/progs/stars/binary_c -\family default - where -\begin_inset Formula $\sim$ -\end_inset - - is your home directory -- if you put it there then all the scripts will - work) and unzip it with one of the following commands (depending on the - file you were given) -\end_layout - -\begin_layout Itemize - -\family typewriter -unzip binary_c.zip -\family default - -\end_layout - -\begin_layout Itemize - -\family typewriter -tar -xvzf binary_c.tar.gz -\end_layout - -\begin_layout Itemize - -\family typewriter -tar -xvjf binary_c.tar.bz2 -\end_layout - -\begin_layout Standard -which will unzip the files in the appropriate places. - -\end_layout - -\begin_layout Standard -Now, from the -\family typewriter -binary_c -\family default - directory, you need to run the configuration script with -\end_layout - -\begin_layout Standard - -\family typewriter -./configure -\end_layout - -\begin_layout Standard -which creates the -\family typewriter -Makefile -\family default -. - Now type -\end_layout - -\begin_layout Standard - -\family typewriter -make -\end_layout - -\begin_layout Standard -to build the code. - Note that you may need to use -\end_layout - -\begin_layout Standard - -\family typewriter -gmake -\end_layout - -\begin_layout Standard -if GNU make is not your default (e.g. - Solaris). - The code will now build, assuming -\family typewriter -configure -\family default - worked ok. - If configure does -\emph on -not -\emph default - work then please try to fix it before running to me with complaints. - It works on Linux and will revert to -\family typewriter -gcc -\family default - as the default compiler if something goes wrong - it -\emph on -might -\emph default - detect -\family typewriter -icc -\family default - if it's on your system. - It is up to you to make your compiler work properly! The executable is - called -\family typewriter -binary_c. -\end_layout - -\begin_layout Standard -Note: -\family typewriter -binary_c -\family default - is built as a single, possibly -\emph on -large -\emph default - (many MB) executable. - The reason for this is purely ease of use when transferring the executable - from one machine to another. - You can, of course, edit the configure script to build shared libraries - instead -- this is the way I used to do it but it was just too cumbersome. -\end_layout - -\begin_layout Subsection -Running -\end_layout - -\begin_layout Standard -\begin_inset CommandInset label -LatexCommand label -name "sub:Running" - -\end_inset - - -\end_layout - -\begin_layout Standard -A script called -\family typewriter -tbse -\family default - is provided to run the binary model, it uses -\family typewriter -bash -\family default -. - The basis of the script is the following -\end_layout - -\begin_layout Quotation - -\family typewriter -#!/bin/bash -\end_layout - -\begin_layout Quotation - -\family typewriter -# be nice! and sort out the path (just in case) -\end_layout - -\begin_layout Quotation - -\family typewriter -NICELEVEL=19 -\end_layout - -\begin_layout Quotation - -\family typewriter -export PATH=$PATH:. -\end_layout - -\begin_layout Quotation - -\family typewriter -BIN_C="./binary_c" -\end_layout - -\begin_layout Standard -What is going on? The -\family typewriter -NICELEVEL -\family default - specifies how much to nice the code when you run it (do -\family typewriter -man nice -\family default -). - The rest of -\family typewriter -tbse -\family default - sets the options as environment variables -- then the code is run with - these options passed in as command-line arguments. - Note that this list of variables is not complete and is subject to change - when new physics is put into the code (see the -\family typewriter -setup/parse_arguments.c -\family default - file for a complete list). - Check your -\family typewriter -tbse -\family default - file for details. -\end_layout - -\begin_layout Quotation -Initial primary mass -\end_layout - -\begin_layout Quotation - -\family typewriter -M1=6 -\end_layout - -\begin_layout Quotation -Initial secondary mass -\end_layout - -\begin_layout Quotation - -\family typewriter -M2=0.001 -\end_layout - -\begin_layout Quotation -Initial orbital period (days) -\end_layout - -\begin_layout Quotation - -\family typewriter -PER=10000000000000 -\end_layout - -\begin_layout Quotation -Initial eccentricity -\end_layout - -\begin_layout Quotation - -\family typewriter -ECC=0.0 -\end_layout - -\begin_layout Quotation -(Initial) Metallicity -\end_layout - -\begin_layout Quotation - -\family typewriter -Z=0.02 -\end_layout - -\begin_layout Quotation -WR wind selection, 0 for -\begin_inset CommandInset citation -LatexCommand citet -key "2002MNRAS_329_897H" - -\end_inset - -, 1 & 2 for MM & NL -\begin_inset CommandInset citation -LatexCommand citep -key "2003MNRAS.338..973D" - -\end_inset - - -\end_layout - -\begin_layout Quotation - -\family typewriter -WRWIND=0 -\end_layout - -\begin_layout Quotation -WR wind multiplication factor -\end_layout - -\begin_layout Quotation - -\family typewriter -WRWINDFAC=1 -\end_layout - -\begin_layout Quotation -Black Hole Prescription, 0 for -\begin_inset CommandInset citation -LatexCommand citet -key "2002MNRAS_329_897H" - -\end_inset - -, 1 for -\begin_inset CommandInset citation -LatexCommand citet -key "2002ApJ...572..407B" - -\end_inset - - -\end_layout - -\begin_layout Quotation - -\family typewriter -BHP=0 -\end_layout - -\begin_layout Quotation -Common envelope envelope removal efficiency -\end_layout - -\begin_layout Quotation - -\family typewriter -CE_ALPHA=3.0 -\end_layout - -\begin_layout Quotation -Maximum evolution time (MYr) -\end_layout - -\begin_layout Quotation - -\family typewriter -EVOLTIME=16000 -\end_layout - -\begin_layout Quotation -\begin_inset Formula $^{13}\textrm{C}$ -\end_inset - - pocket efficiency (size) -\end_layout - -\begin_layout Quotation - -\family typewriter -C13_EFF=1 -\end_layout - -\begin_layout Quotation -\begin_inset Formula $\Delta M_{\textrm{c}}^{\textrm{min}}$ -\end_inset - - and -\begin_inset Formula $\lambda_{\textrm{min}}$ -\end_inset - - - third dredge-up calibration (see -\begin_inset CommandInset citation -LatexCommand citealp -key "Izzard_et_al_2003b_AGBs" - -\end_inset - -) -\end_layout - -\begin_layout Quotation - -\family typewriter -DELTA_MCMIN=0 -\end_layout - -\begin_layout Quotation - -\family typewriter -LAMBDA_MIN=0 -\end_layout - -\begin_layout Quotation -\begin_inset Formula $f_{\textrm{t}}$ -\end_inset - - - timestep multiplication factor - set to <1 to reduce the timestep -\end_layout - -\begin_layout Quotation - -\family typewriter -DTFAC=1 -\end_layout - -\begin_layout Quotation -TPAGB wind selector : 0 is VW93 -\begin_inset CommandInset citation -LatexCommand citep -key "1993ApJ...413..641V" - -\end_inset - - with superwind switch-on at given Mira period (in days, usually -\begin_inset Formula $500\,\textrm{d}$ -\end_inset - - as in -\begin_inset CommandInset citation -LatexCommand citealp -key "Parameterising_3DUP_Karakas_Lattanzio_Pols" - -\end_inset - -), 1 is the -\begin_inset CommandInset citation -LatexCommand citet -key "2002MNRAS_329_897H" - -\end_inset - - prescription, 2 is a Reimers rate with given -\begin_inset Formula $\eta$ -\end_inset - -, 3 is the wind of -\begin_inset CommandInset citation -LatexCommand citet -key "1995A&A...297..727B" - -\end_inset - -. -\end_layout - -\begin_layout Quotation - -\family typewriter -TPAGBWIND=1 -\end_layout - -\begin_layout Quotation - -\family typewriter -MIRA_PERIOD=500 -\end_layout - -\begin_layout Quotation - -\family typewriter -TPAGB_REIMERS=3 -\end_layout - -\begin_layout Quotation -As of V1.2 there are options for STPAGB stars which are the same as those - for TPAGB stars but only apply to the STPAGB stage (stars which ignite - carbon but then settle to the TPAGB). -\end_layout - -\begin_layout Quotation - -\family typewriter -STPAGBWIND=2 -\end_layout - -\begin_layout Quotation - -\family typewriter -STPAGB_REIMERS_ETA=10 -\end_layout - -\begin_layout Quotation - -\family typewriter -STPAGB_SUPERWIND_MIRA=500 -\end_layout - -\begin_layout Quotation - -\family typewriter -STPAGB_LAMBDA=0.07 -\end_layout - -\begin_layout Quotation -Giant branch Reimers wind loss value -\end_layout - -\begin_layout Quotation - -\family typewriter -GB_REIMERS=0.5 -\end_layout - -\begin_layout Quotation -Eddington limit? Allows accretion rates up to EDDFAC -\begin_inset Formula $\times$ -\end_inset - - the Eddington limit ( -\begin_inset Formula $10^{6}$ -\end_inset - - is a typical value, or -\begin_inset Formula $1$ -\end_inset - - for string adherence to the limit) -\end_layout - -\begin_layout Quotation - -\family typewriter -EDDFAC=1e6 -\end_layout - -\begin_layout Quotation -This is the factor in the Bondi-Hoyle accretion rate formula. -\end_layout - -\begin_layout Quotation - -\family typewriter -ACC2=1.5 -\end_layout - -\begin_layout Quotation -The next option varies the initial abundance of isotope 1 (usually helium, - see -\family typewriter -nucsyn_isotopes.h -\family default - for a list) to 0.3 -\end_layout - -\begin_layout Quotation - -\family typewriter -INIT_ABUNDS="--init_abund 1 0.3" -\end_layout - -\begin_layout Quotation -Note that you can change the initial abundances of all the isotopes -\emph on -except hydrogen. - -\emph default - Hydrogen is then everything else (so the total adds up to 1.0). - There is no check to see if the numbers are sensible -- you have been warned. - Also, it is up to you to set the metallicity to the sum of all the metals - -- the fits usually depend on the metallicity, not the individual isotopic - abundances. -\end_layout - -\begin_layout Quotation -Now run the code, output is sent to stdout. -\end_layout - -\begin_layout Quotation - -\family typewriter -nice -n $NICELEVEL $BIN_C --M_1 $M1 --M_2 $M2 --eccentricity $ECC --orbital_peri -od $PER --max_evolution_time $EVOLTIME --metallicity $Z --monte_carlo_kicks - --wr_wind $WRWIND --wr_wind_fac $WRWINDFAC --BH_prescription $BHP --c13_eff - $C13_EFF --delta_mcmin $DELTA_MCMIN --lambda_min $LAMBDA_MIN --dtfac $DTFAC - --tpagbwind $TPAGBWIND --superwind_mira_switchon $MIRA_PERIOD --tpagb_reimers_e -ta $TPAGB_REIMERS --gb_reimers_eta $GB_REIMERS --eddfac $EDDFAC --acc2 $ACC2 - $INIT_ABUNDS -\family default - -\family typewriter ---log_filename /tmp/c_log2.dat -\end_layout - -\begin_layout Quotation -The file -\family typewriter -/tmp/c_log2.dat -\family default - (or whatever you have set the log_filename option to) should also contain - some output. - Of course what gets output to the screen depends on what options you select - (see section -\begin_inset CommandInset ref -LatexCommand ref -reference "sub:Advanced-Configuration" - -\end_inset - -). -\end_layout - -\begin_layout Subsection -Subversion access -\end_layout - -\begin_layout Standard -\begin_inset CommandInset label -LatexCommand label -name "sub:binary_c/subversion-access" - -\end_inset - - -\emph on -binary_c/nucsyn -\emph default - is now hosted Rob's PC (capc85.ast.cam.ac.uk) at the Institute of Astronomy, - part of the University of Cambridge. - Please contact Rob (rgi@ast.cam.ac.uk) for details of how to obtain the code - through SVN. - Note that the SVN version numbers were reset upon Rob's migration to Bonn - but have been continued after his move to Cambridge. - To avoid confusion, Bonn versions are generally referred to as -\emph on -SVN Bonn/xyz -\emph default - (where xyz is a number), after the move to Cambridge they are -\emph on -Cambridge -\emph default -/ -\emph on -xyz -\emph default -. -\end_layout - -\begin_layout Standard -More detailed instructions can be found in the binary_c/nucsyn-devel mailing - list -\end_layout - -\begin_layout Standard -\begin_inset Flex URL -status open - -\begin_layout Plain Layout - -https://groups.google.com/group/binary_c-nucsyn-devel/browse_thread/thread/e6d5b0e -91b1668ff -\end_layout - -\end_inset - - -\end_layout - -\begin_layout Subsection -Mailing lists -\end_layout - -\begin_layout Standard -\begin_inset CommandInset label -LatexCommand label -name "sub:mailing-lists" - -\end_inset - -There are two mailing lists for binary_c/nucsyn, both on Google's -\begin_inset Quotes eld -\end_inset - -groups -\begin_inset Quotes erd -\end_inset - - service -\end_layout - -\begin_layout Itemize -The announcements list -\begin_inset Newline newline -\end_inset - - -\begin_inset Flex URL -status open - -\begin_layout Plain Layout - -https://groups.google.com/group/binary_c-nucsyn-announce -\end_layout - -\end_inset - - -\begin_inset Newline newline -\end_inset - -This contains major announcements such as significant upgrades to binary_c/nucsy -n (or the supporting software) -\end_layout - -\begin_layout Itemize -The development list -\begin_inset Newline newline -\end_inset - - -\begin_inset Flex URL -status open - -\begin_layout Plain Layout - -https://groups.google.com/group/binary_c-nucsyn-devel -\end_layout - -\end_inset - - -\begin_inset Newline newline -\end_inset - -This is more of a discussion list outlining specific changes to physics - and technical development of the code(s). -\end_layout - -\begin_layout Subsection -Directory structure -\end_layout - -\begin_layout Standard -Upon migration of the code to the Bonn -\emph on -subversion -\emph default - server, the directory structure was rearranged. - The -\family typewriter -binary_c -\family default - directory no longer contains the -\family typewriter -.c -\family default -source files or (most of the) perl scripts. - It's subdirectories now include: -\end_layout - -\begin_layout Itemize -The -\family typewriter -src -\family default - directory, which holds all the -\family typewriter -.c -\family default - files -\end_layout - -\begin_layout Itemize - -\family typewriter -src/doc -\family default - contains documentation -\end_layout - -\begin_layout Itemize - -\family typewriter -src/perl -\family default - contains the perl scripts e.g. - -\family typewriter -grid.pl -\family default -as well as latest -\emph on -binary_grid -\emph default - and helper modules -\end_layout - -\begin_layout Section -Batchmode: Running a grid of models -\end_layout - -\begin_layout Standard -\begin_inset CommandInset label -LatexCommand label -name "sub:Running-a-grid" - -\end_inset - -You -\emph on -could -\emph default - run many stars by directly calling -\emph on -binary_c -\emph default - with the appropriate arguments. - This is very inefficient. - Instead, -\family roman -\emph on -binary_c -\family default -\emph default - can be run in -\emph on -batchmode -\emph default - and is then controlled by a Perl script -\emph on -grid.pl -\emph default - which uses a library of functions in the -\emph on -binary_grid -\emph default - Perl module. -\end_layout - -\begin_layout Standard -Please see the dedicated -\emph on -binary_grid-flexigrid.pdf -\emph default - documentation in this directory. -\end_layout - -\begin_layout Section -Hacker Guide -\end_layout - -\begin_layout Standard -\begin_inset CommandInset label -LatexCommand label -name "sec:Hacker-Guide" - -\end_inset - - -\end_layout - -\begin_layout Standard -This section is for the dedicated who cares about the guts of the code. - You are being warned now: some of it is not pretty, some of it is work - in progress, some of it contains dirty fudges which work but could be better - (or perhaps more efficient). - If you want to complain about such things it's best to fix it yourself - and then share the changes with the other people who use the code, although - I am sure they'll be happy to help. -\end_layout - -\begin_layout Subsection -History -\end_layout - -\begin_layout Standard -\begin_inset CommandInset label -LatexCommand label -name "sub:History" - -\end_inset - -First, a bit of history. - The -\emph on -BSE -\emph default - code was given to me by Chris Tout in October 2000 and some updates were - made in May 2001 (from Jarrod Hurley). - Jarrod was responsible for the October 2000 version, written as one monolithic - block of evil -\emph on -Fortran -\emph default -, although past collaborators such as Chris Tout, Sverre Aarseth, Onno Pols - etc. - (who else have I forgotten?) had input their talent to the code. - The -\emph on -Fortran -\emph default - version was converted to -\emph on -C -\emph default - (because I hate -\emph on -Fortran -\emph default - and it was -\emph on -my -\emph default - -\emph on -bloody -\emph default - -\emph on -PhD -\emph default -!) and (some of) the bugs worked out of it. - This gave me a chance to lay things out slightly differently and while - the splitting of the big function ( -\family typewriter -evolv(2).f -\family default -) into lots of little ones is some sort of advantage the code didn't change - much. - This means that most of the bugs in Jarrod's code are in this one (some - have been fixed since) and I don't know how every little bit of Jarrod's - code works (it's just too big to understand everything). -\end_layout - -\begin_layout Standard -One thing that -\emph on -did -\emph default - change was the organisation of the variables. - In the -\emph on -Fortran -\emph default - code there are lots of arrays of size 2 (there are two stars!) and a load - of common blocks. - These have been replaced by structures, one for each -\family typewriter -star -\family default -, the -\family typewriter -common -\family default - and -\family typewriter -model -\family default - structures and a -\family typewriter -stardata -\family default - structure which contains pointers to everything else. - Pointers are far quicker to use than passing the actual data around. - Conceptually it's useful to have all the information about each star in - one space, since most functions deal only with one star and can access - all the information through a single pointer. - Also, having it in C means I am the only one who really knows how it works - so there will always be employment. - Er\SpecialChar \ldots{} - oh, that's bollocks. - Ah well! -\end_layout - -\begin_layout Standard -There are many things which can be improved in the code, some of which I - have described in the introduction. - Also while sometimes the layout looks clumsy, with lots of -\family typewriter -DEBUG -\family default - statements around, these are very useful when something goes wrong. - Just set a -\end_layout - -\begin_layout Standard - -\family typewriter -#define DEBUG 1 -\end_layout - -\begin_layout Standard -at the top of the function in which you think there is a bug and, with some - luck, the debugging information will tell you where it is. - For this reason I insist that if you add anything to the code you make - sure of a few things -\end_layout - -\begin_layout Itemize -Include -\emph on -good comments -\emph default - even if these are -\begin_inset Quotes eld -\end_inset - -this is a fudge -\begin_inset Quotes erd -\end_inset - -! Remember that people who do not know how the code works will want to hack - your hacks in the future. - Descriptions of the physics (cut and paste from a paper if you have to) - are encouraged because the people working on it are physicists (or mathematicia -ns) more than they are computer scientists. -\end_layout - -\begin_layout Itemize -Include -\family typewriter -DEBUG -\family default - statements so that if there is a -\family typewriter -DEBUG -\family default - flag set there will be some (useful!) output to the screen during runtime. - -\end_layout - -\begin_layout Itemize -Make sure the names of your variables -\emph on -describe what they do -\emph default - (in English :-). - I do not care if the variable names are long (long is good!) and the computer - certainly doesn't either. - Just have a look at the Fortran code and try to work out what -\family typewriter -tphys -\family default -, -\family typewriter -tphys0 -\family default - and -\family typewriter -tphys00 -\family default - do, or -\family typewriter -dm1 -\family default -, -\family typewriter -dm2 -\family default - and -\family typewriter -dm22 -\family default -, or -\family typewriter -dt -\family default -, -\family typewriter -dtm -\family default -, -\family typewriter -dtr -\family default -, -\family typewriter -djtt -\family default -, -\family typewriter -tm -\family default -, -\family typewriter -tn -\family default - etc. - -\end_layout - -\begin_layout Itemize -It has taken me ages to write this bloody manual -- so you owe me a pint - of a -\emph on -decent -\emph default - beer! ( -\emph on -NOT -\emph default - Heineken, Stella, Kronenbourg or Fosters!) -\end_layout - -\begin_layout Subsection -How the -\emph on -binary_c/nucsyn -\emph default - code works -\end_layout - -\begin_layout Standard -\begin_inset CommandInset label -LatexCommand label -name "sub:How-the-code" - -\end_inset - -The -\emph on -binary_c -\emph default - code, based on -\emph on -BSE -\emph default -, deals with stellar evolution and binary evolution i.e. - the mass, core mass, luminosity, radius of both stars, mass loss and gain, - orbital changes, supernovae and novae. - The nucsyn code deals with the surface abundance of the stars, follows - this as mass is lost or gained and also the luminosity and radius on the - TPAGB, dredge-ups, HBB, WR stars, supernova and nova yields. - This does not sound like much but it's complicated enough! -\end_layout - -\begin_layout Standard -The -\emph on -binary_c -\emph default - code, apart from on the TPAGB, runs independently of the -\emph on -nucsyn -\emph default - code. - On the TPAGB the luminosity and radius were refitted to Amanda's models - because otherwise there was no way to make them fit, although this is not - really a link between the -\emph on -binary_c -\emph default - and -\emph on -nucsyn -\emph default - code. - The -\emph on -only -\emph default - link (sort of) is the use of the surface hydrogen mass fraction -\begin_inset Formula $X$ -\end_inset - - to calculate the value of -\begin_inset Formula $q$ -\end_inset - - used to calculate the rate of change of core mass of the star on the TPAGB. - Even then the connection is quite weak. - The other possible link is in the WR wind loss rates, some of which are - composition dependent. - In reality they probably should not be, but that's beyond us at the moment. -\end_layout - -\begin_layout Standard -So as the -\emph on -binary_c -\emph default - code does the stellar ( -\begin_inset Quotes eld -\end_inset - -structure -\begin_inset Quotes erd -\end_inset - -) -\emph on - -\emph default -evolution, the nucsyn code identifies when the surface abundances change. - For single stars there are only a few important episodes, the dredge-ups - and TPAGB, WR formation and core-collapse supernovae. - In binaries it's trickier but handled as best as is possible in a simple - model. -\end_layout - -\begin_layout Subsection -Data Structures -\end_layout - -\begin_layout Standard -\begin_inset CommandInset label -LatexCommand label -name "sub:Structures" - -\end_inset - -There are a few structures which get passed around which deal with the stars - and their abundances. - The most important is the -\family typewriter -stardata -\family default - structure. - This is central to the code and contains the -\family typewriter -star -\family default - structures for the two stars, the -\family typewriter -model -\family default - and -\family typewriter -common -\family default - structures and a pointer to the -\family typewriter -preferences -\family default - structure. - Note that there are -\emph on -three -\emph default - -\family typewriter -star -\family default - structures, the first (0) is unused. - This is because Fortran starts counting at one, -\emph on -the utter -\emph default - -\emph on -bastards -\emph default -, and I haven't changed the counting (too much hassle) so the stars are - 1 and 2 (which kind-of makes sense although is annoying). - Also note that while variables I use a lot are called sensible names, there - are some Fortran variables which have silly names -- often I do not know - what they do or have forgotten. - Please feel free to fill in the gaps below\SpecialChar \ldots{} - -\end_layout - -\begin_layout Standard -Note: The structs themselves are -\emph on -never -\emph default - (I hope) passed from one function to another, rather they are passed by - reference (as pointers). - This is very fast and efficient and you should do the same. -\end_layout - -\begin_layout Subsubsection - -\family typewriter -model -\end_layout - -\begin_layout Standard -\begin_inset CommandInset label -LatexCommand label -name "sub:model-struct" - -\end_inset - -Originally variables common to both stars were going to go into -\family typewriter -common -\family default -, and stuff about the model into -\family typewriter -model -\family default -. - Of course the boundary between the two is very blurred so perhaps one day - somebody can merge them into one ( -\family typewriter -common -\family default - or -\family typewriter -codel -\family default - ?). - For now, you'll have to put up with the dodgy distinction. -\end_layout - -\begin_layout Standard - -\family typewriter -model -\family default - contains the -\family typewriter -probability -\family default - of the system existing (the grid code uses this) - this is set to 1 for - a single run. - -\family typewriter -model_time -\family default - is the current time (was -\family typewriter -tphys -\family default - in the Fortran), -\family typewriter -tphys0 -\family default - and -\family typewriter -tphys00 -\family default - are other time variables (unlabeled in the Fortran). - -\family typewriter -max_evolution_time -\family default - is the maximum time the model runs for before it exits (set on command - line). - -\family typewriter -dt -\family default - (which is just a temporary variable and is not really the timestep - damn - you Fortran people), -\family typewriter -dtm -\family default - (which is the timestep), -\family typewriter -dtm0 -\family default - and -\family typewriter -dtr -\family default - are used to calculate the timestep. - -\family typewriter -log_fp -\family default - is a file pointer used for output (usually to the file -\family typewriter -/tmp/c_log2.dat -\family default -), -\family typewriter -snova -\family default - is set to -\family typewriter -TRUE -\family default - if there is a supernova, otherwise -\family typewriter -FALSE -\family default -. - -\family typewriter -esymb -\family default - and -\family typewriter -bsymb -\family default - are to do with symbiotic stars. - -\family typewriter -coel -\family default - is set to -\family typewriter -TRUE -\family default - if the stars collide otherwise -\family typewriter -FALSE -\family default -. - -\family typewriter -inttry -\family default - is to do with the number of iterations during RLOF, although that might - be -\family typewriter -iter -\family default - (ask Jarrod!). - -\family typewriter -sgl -\family default - is -\family typewriter -TRUE -\family default - for a single star system, -\family typewriter -FALSE -\family default - for a binary. - -\family typewriter -bss -\family default - is TRUE for a blue-straggler, -\family typewriter -FALSE -\family default - otherwise. - -\family typewriter -intpol -\family default - is 0 if the code is not interpolating during RLOF, non-zero otherwise. - -\family typewriter -disk -\family default - and -\family typewriter -novae -\family default - signify that the system has a disk or is undergoing nova eruptions respectively. - -\family typewriter -eddfac -\family default - is discussed above (it is a command line option), -\family typewriter -epsnov -\family default - is the amount of matter retained after a nova explosion (perhaps this is - a command line option?), -\family typewriter -gamma -\family default - is to do with the amount of angular momentum transferred during RLOF (-1 - was suggested, but 0 makes the code work in the same way as the old code - -- Onno will know about this, I think he implemented it). - -\family typewriter -supedd -\family default - determines whether the Eddington limit for accretion has been reached, - -\family typewriter -rmin -\family default - is the minimum accretion disk radius. - The following variables are to do with distributed supernova kicking -\family typewriter -in_dist_kick_cycle -\family default -, -\family typewriter -restart_run -\family default -, -\family typewriter -rerun -\family default -, -\family typewriter -exit_after_end, -\family default - -\family typewriter -primary_kicker -\family default - and -\family typewriter -secondary_kicker -\family default -. - The following determine control flow in the -\family typewriter -iterate -\family default - function: -\family typewriter -skip_initialization -\family default -, -\family typewriter -roche_overflow -\family default - and -\family typewriter -skip_all_but_special_cases -\family default -. - These are counters passed between functions -\family typewriter -j1 -\family default -, -\family typewriter -j2 -\family default - (these are used in RLOF, star -\family typewriter -j1 -\family default - is losing mass to star -\family typewriter -j2 -\family default - or perhaps the other way around - check!), -\family typewriter -kmin -\family default -, -\family typewriter -kmax -\family default -, -\family typewriter -kw1 -\family default - and -\family typewriter -kw2 -\family default -. - -\family typewriter -gbwindfac -\family default - is the multiplication factor for the GB wind loss rate (set on the command - line). -\end_layout - -\begin_layout Subsubsection - -\family typewriter -common -\end_layout - -\begin_layout Standard - -\family typewriter -\begin_inset CommandInset label -LatexCommand label -name "sub:common-struct" - -\end_inset - -common -\family default - contains the -\family typewriter -orbital_period -\family default - in days, the (initial!) -\family typewriter -metallicity -\family default -, -\family typewriter -eccentricity -\family default - of the system, a variable -\family typewriter -ecc1 -\family default - (whatever that is), the current -\family typewriter -separation -\family default - (in solar radii, I believe), the -\family typewriter -orbital_angular_momentum -\family default - and -\family typewriter -orbital_angular_frequency -\family default -, -\family typewriter -djorb -\family default - the change in orbital angular momentum, -\family typewriter -delet -\family default - is also related to this. - There are some variables passed around -\family typewriter -tmsnew -\family default - must be something to do with main sequence lifetimes, -\family typewriter -dm1 -\family default - and -\family typewriter -dm2 -\family default - are the amounts of mass transferred during RLOF, -\family typewriter -dm22 -\family default - is like -\family typewriter -dm2 -\family default - but with nova mass loss removed (see what I mean about self-explanatory - variable names?). - -\family typewriter -tm -\family default - and -\family typewriter -tn -\family default - are timescales (main-sequence and nuclear, I believe), -\family typewriter -eqspin -\family default - and -\family typewriter -djtt -\family default - are other things to do with spin-rate at equilibrium (set somewhere) and - orbital angular momentum changes/transfer. - -\family typewriter -zams_separation -\family default - and -\family typewriter -zams_eccentricity -\family default - are the starting values of -\family typewriter -separation -\family default - and -\family typewriter -eccentricity -\family default - (useful somewhere I am sure) while the -\family typewriter -phase_volume -\family default - is useful if you're running a grid (it is e.g. - -\begin_inset Formula $\delta M_{1}\times\delta M_{2}\times\delta a$ -\end_inset - -). - Other grid variables include -\family typewriter -m1min -\family default -, -\family typewriter -m1max -\family default -, -\family typewriter -m1grid_points -\family default - and similar for -\family typewriter -m2 -\family default - and -\family typewriter -sep -\family default -. -\end_layout - -\begin_layout Standard -There are some extra nucsyn variables, -\family typewriter -mnuc -\family default - is an array containing the nuclear masses, -\family typewriter -atomic_number -\family default - is an array containing the atomic number. - -\family typewriter -XZAMS -\family default - is the initial abundance of the stars, this is a -\emph on -constant -\emph default - (unlike -\family typewriter -zams_mass -\family default -) required to calculate -\begin_inset Formula $p_{\textrm{M}}$ -\end_inset - - yields. - -\family typewriter -lambda_min -\family default - and -\family typewriter -delta_mcmin -\family default - are the third dredge-up calibration parameters. -\end_layout - -\begin_layout Standard -There are some arrays, which usually contain timescales or fitting formulae - coefficients, stored in -\family typewriter -common -\family default - as well. - These are -\family typewriter -main_sequence_parameters -\family default -, -\family typewriter -giant_branch_parameters -\family default -, -\family typewriter -GB -\family default -, -\family typewriter -lums -\family default -, -\family typewriter -tscls -\family default -, -\family typewriter -tm -\family default - and -\family typewriter -tn -\family default - (different from the other -\family typewriter -tm -\family default - and -\family typewriter -tn -\family default -? check!). - -\family typewriter -lums -\family default - and -\family typewriter -tscls -\family default - are set by calls to -\family typewriter -calc_lum_and_evol_time -\family default - (formerly the function -\family typewriter -star -\family default - in the Fortran version, but we have -\family typewriter -star -\family default - structures now so it was changed) and are the luminosities and timescales - at important places in stellar evolution (e.g. - base of the GB). -\end_layout - -\begin_layout Subsubsection - -\family typewriter -preferences -\end_layout - -\begin_layout Standard -\begin_inset CommandInset label -LatexCommand label -name "sub:preferences-struct" - -\end_inset - -Variables set at the command line are (usually) saved in the -\family typewriter -preferences -\family default - array, which was added as an afterthought hence it is not stored in the - same space as -\family typewriter -stardata -\family default - but is pointed to in -\family typewriter -stardata -\family default - so you can access it everywhere you can access -\family typewriter -stardata -\family default - (which is almost everywhere). -\end_layout - -\begin_layout Standard - -\family typewriter -popsyn -\family default - is -\family typewriter -TRUE -\family default - if you're running a population synthesis grid (via the -\family typewriter -adaptive_grid -\family default - library), set via -\family typewriter ---popsyn -\family default - on the command line, -\family typewriter -FALSE -\family default - otherwise. - There are some variables used to control the popsyn grid: -\family typewriter -rerun_from_saved -\family default -, -\family typewriter -save_position -\family default -, -\family typewriter -call_iterate -\family default -, -\family typewriter -save_signal_only -\family default -, -\family typewriter -nozoom -\family default -, -\family typewriter -popsyn_z -\family default -, -\family typewriter -smallgrid -\family default -. - More useful are the parameters corresponding to the command line options - -\family typewriter -tpagbwind -\family default -, -\family typewriter -superwind_mira_switchon -\family default -, -\family typewriter -tpagb_reimers_eta -\family default -, -\family typewriter -wr_wind -\family default -, -\family typewriter -wr_wind_fac -\family default -, -\family typewriter -alpha_ce -\family default -, -\family typewriter -lambda_ce -\family default -, -\family typewriter -BH_prescription -\family default -, -\family typewriter -epsnov -\family default -, -\family typewriter -rlof_angmom_gamma -\family default -, -\family typewriter -sn_sigma -\family default -, -\family typewriter -reimers_gb_neta -\family default -, -\family typewriter -bb -\family default - (binary enhanced wind loss factor), -\family typewriter -acc2 -\family default -, -\family typewriter -hbbtfac -\family default - (HBB temperature factor), -\family typewriter -dtfac -\family default -, -\family typewriter -c13_eff -\family default -. - -\family typewriter -NeNaMgAl -\family default - is a command line option used to turn NeNa/MgAl cycling on or off (default - is probably on) although of course if NeNa/MgAl cycling is not compiled - into the code (see above) then it won't work at all! sn_dat_filename is - the name of the file where data on supernovae are sent, useful for -\begin_inset CommandInset citation -LatexCommand citet -key "2004MNRAS.348.1215I" - -\end_inset - -. - There are three experimental polytropic variables -\family typewriter -polyn -\family default -, -\family typewriter -mfac -\family default - and -\family typewriter -rfac -\family default - which are used in -\family typewriter -nucsyn_tpagb -\family default -. -\end_layout - -\begin_layout Standard -In version 1.2 new variables to deal with STPAGB stars were introduced. - These are experimental! -\end_layout - -\begin_layout Subsubsection - -\family typewriter -star -\end_layout - -\begin_layout Standard -\begin_inset CommandInset label -LatexCommand label -name "sub:star-struct" - -\end_inset - -The most important structure of the lot, -\family typewriter -star -\family default - contains the information about each star. - Most variables are obvious, -\family typewriter -mass -\family default - is the mass of the star, -\family typewriter -stellar_type -\family default - is its stellar type (see -\family typewriter -stellar_types.h -\family default -), -\family typewriter -radius -\family default - its radius, -\family typewriter -rol -\family default - its Roche-lobe radius, -\family typewriter -rol0 -\family default - its Roche-lobe radius at some other time, -\family typewriter -initial_mass -\family default - is probably the mass at the beginning of the current evolutionary phase - (rather than the real initial mass although that is stored here too, see - -\family typewriter -pms_mass -\family default -), -\family typewriter -aj -\family default - is the age of the star (Myr), -\family typewriter -aj0 -\family default - is the age at some other time (obviously not -\begin_inset Formula $t=0$ -\end_inset - - because that's er, just -\begin_inset Formula $0$ -\end_inset - -), -\family typewriter -epoch -\family default - is another lifetime variable (and I can't remember what it does), -\family typewriter -core_mass -\family default - and -\family typewriter -core_radius -\family default - are the core mass and core radius and -\family typewriter -luminosity -\family default - is the surface luminosity of the star. - -\family typewriter -omega -\family default -, -\family typewriter -omega1 -\family default - and -\family typewriter -omega2 -\family default - are the star's angular frequency on the current timestep, one back and - the one before that (these are useful if you the angular momentum does - weird things when the star explodes). - -\family typewriter -jspin -\family default - is the star's angular momentum, -\family typewriter -jstar1 -\family default - and -\family typewriter -jstar2 -\family default - are on the previous timestep and the one prior to that. - -\family typewriter -q -\family default - is the mass ratio. - -\family typewriter -tbgb -\family default - is the giant branch timescale, -\family typewriter -tms -\family default - the main sequence timescale. -\end_layout - -\begin_layout Standard - -\family typewriter -dmr -\family default - is mass gain, -\family typewriter -dmt -\family default - is mass lost, -\family typewriter -dms -\family default - is also mass lost (?). - -\family typewriter -dspint -\family default - is -\begin_inset Formula $d\omega/dt$ -\end_inset - -, -\family typewriter -djspint -\family default - is -\begin_inset Formula $dj/dt$ -\end_inset - - ( -\begin_inset Formula $j=$ -\end_inset - -orbital angular momentum). - -\family typewriter -mcxx -\family default - and -\family typewriter -mass00 -\family default - are used as temporary variables, again is it not obvious to you what they - do?! -\family typewriter -rdot -\family default - is probably -\begin_inset Formula $dR/dt$ -\end_inset - -, -\family typewriter -dtmi -\family default - is the timestep -\emph on -for the star -\emph default - (not the binary), -\family typewriter -radx -\family default - is used in the small envelope correction (see -\family typewriter -hrdiag -\family default -), -\family typewriter -tkh -\family default - is the Kelvin-Helmholtz timescale. - -\family typewriter -went_sn_last_time -\family default - implies (if -\family typewriter -TRUE -\family default -) the star exploded on the previous timestep (useful for finding out about - the remnant, requires -\family typewriter -LOG_SUPERNOVAE -\family default - to be set), -\family typewriter -menv -\family default -, -\family typewriter -renv -\family default - and -\family typewriter -k2 -\family default - are the envelope mass, radius mass and moment of inertia (or multiplier - of) see the functions -\family typewriter -menv -\family default - and -\family typewriter -renv -\family default - (in -\family typewriter -zfuncs/ -\family default -). - -\family typewriter -djtx -\family default - is another well named variable. - zams_mass is the ZAMS mass of the star -\emph on -but -\emph default - if the star accretes mass which on the MS then this is -\emph on -redefined -\emph default - to be the greater of the real ZAMS mass and the new (probably higher) mass. - If you want the -\emph on -real -\emph default - initial mass, e.g. - in -\family typewriter -nucsyn_binary_yield -\family default - where -\begin_inset Formula $p_{\textrm{M}}$ -\end_inset - - is calculated, use -\family typewriter -pms_mass -\family default -. - -\family typewriter -supernova -\family default - is set to -\family typewriter -TRUE -\family default - if the star has a SN at any point in its lifetime (used when -\family typewriter -LOG_SUPERNOVAE -\family default - is set). - -\family typewriter -starnum -\family default - is set to 1 for star 1, 2 for star 2 -- this is remarkably useful when - the -\family typewriter -star -\family default - array is passed in but you want to find out which star you are dealing - with (e.g. - for logging purposes). -\end_layout - -\begin_layout Standard -Now for the nucsyn specific variables. - -\family typewriter -first_dredge_up -\family default - is -\family typewriter -FALSE -\family default - if the star has not undergone a first dredge-up event, -\family typewriter -TRUE -\family default - otherwise. - -\family typewriter -second_dredge_up -\family default - is the same for second dredge-up. - -\family typewriter -spiky_luminosity -\family default - follows the luminosity dips and rises during thermal pulses. - -\family typewriter -Xsurf -\family default -, and its siblings, is an array of -\family typewriter -ISOTOPE_ARRAY_SIZE -\family default - doubles which stores the mass fractions of each isotope (see -\family typewriter -nucsyn_isotopes.h -\family default - for a list) in the stellar envelope. - -\family typewriter -Xsurfn -\family default - stores the envelope abundances at the next timestep. - -\family typewriter -Xsurfs -\family default - stores the saved values of -\family typewriter -Xsurf -\family default - -- if the code moves -\emph on -backwards in time -\emph default - when interpolating at the beginning of RLOF, the surface abundances are - frozen (at -\family typewriter -Xsurfs -\family default -) because the nucsyn code does not really cope well with moving backwards! - When the time exceeds the last time -\family typewriter -Xsurfs -\family default - was set nucleosynthesis is allowed to proceed again and -\family typewriter -Xsurfs -\family default - will be set to -\family typewriter -Xsurf -\family default -. - When there is no interpolation -\family typewriter -Xsurfs -\family default - will be set to -\family typewriter -Xsurf -\family default -. - For this reason when you output the surface abundance it is more reliable - to use -\family typewriter -Xsurfs -\family default - than -\family typewriter -Xsurf -\family default -. - -\family typewriter -Xacc -\family default - and -\family typewriter -Xaccs -\family default - are the equivalent of -\family typewriter -Xsurf -\family default - and -\family typewriter -Xsurfs -\family default - for the accretion layer (see later). - Note that the surface abundances of the star are given by -\family typewriter -Xacc(s) -\family default - if there is an accretion layer, -\family typewriter -Xsurf(s) -\family default - if there is not. - There are functions to remove mass from the surface and to decide which - to use in the nucsyn library. - -\end_layout - -\begin_layout Standard - -\family typewriter -Xyield -\family default - stores the mass lost from the star for each isotope, -\family typewriter -mpyield -\family default - the calculated the -\begin_inset Formula $p_{\textrm{m}}$ -\end_inset - - yield. - -\family typewriter -Xinit -\family default - stores the initial abundances although -\emph on -this can vary -\emph default - due to accretion when the star is a MS star. - -\family typewriter -dmacc -\family default - is the size of the accretion layer. - -\end_layout - -\begin_layout Standard -TPAGB specific variables: the time of the first, previous and next pulse - are -\family typewriter -time_first pulse -\family default -, -\family typewriter -time_prev_pulse -\family default - and -\family typewriter -time_next_pulse -\family default - respectively. - -\family typewriter -prev_tagb -\family default - is the -\family typewriter -model_time -\family default - that the tpagb function was last called for this star, interpulse_period - is the time between pulses, -\family typewriter -mc0 -\family default - is the core mass at the first thermal pulse, -\family typewriter -num_thermal_pulses -\family default - is the number of thermal pulses the star has gone through (note this is - reset as soon as the star is not a TPAGB star so a star -\emph on -can -\emph default - go through two TPAGB phases), -\family typewriter -Xhbb -\family default - are the mass fractions in the HBB shell, -\family typewriter -menv0 -\family default - is the envelope mass at the first thermal pulse, -\family typewriter -dmc_prev_pulse -\family default - is the change in core mass since the previous pulse (used together with - -\begin_inset Formula $\lambda$ -\end_inset - - - the dredge-up efficiency - to calculate the amount of mass dredged up, - which is -\begin_inset Formula $\lambda\times$ -\end_inset - - -\family typewriter -dmc_prev_pulse -\family default -). - -\family typewriter -rho -\family default - and -\family typewriter -temp -\family default - are the density and temperature of the HBB shell. - -\family typewriter -mira -\family default - is the Mira period of the star. - -\family typewriter -rteff -\family default - is the radius of the star -\emph on -in the abscence of the small envelope corrections -\emph default -. - -\family typewriter -f_burn -\family default -, -\family typewriter -f_hbb -\family default -, -\family typewriter -temp_rise_fac -\family default -, -\family typewriter -fmdupburn -\family default - and -\family typewriter -ftimeduphbb -\family default - are the free parameters associated with HBB (see -\family typewriter -nucsyn_hbb -\family default - and -\begin_inset CommandInset citation -LatexCommand citealp -key "Izzard_et_al_2003b_AGBs" - -\end_inset - -). -\end_layout - -\begin_layout Standard -Variables used in -\family typewriter -nucsyn_WR -\family default -: -\family typewriter -start_HG_mass -\family default - is an estimate of the mass of the star at the beginning of the HG (used - to estimate first dredge-up mass), -\family typewriter -newhestar -\family default - is set to -\family typewriter -TRUE -\family default - if the star just became a helium star, -\family typewriter -FALSE -\family default - otherwise, -\family typewriter -hezamsmetallicity -\family default - is the metallicity of the star at the beginning of the helium star main - sequence. - -\family typewriter -he_t -\family default - and -\family typewriter -he_f -\family default - are the time the star becomes a helium star and the fraction of the helium - star phase that has been completed. -\end_layout - -\begin_layout Standard - -\family typewriter -stpagb -\family default - is -\family typewriter -TRUE -\family default - if the star is a super thermally pulsing giant, otherwise -\family typewriter -FALSE -\family default -. - These only apply if -\family typewriter -NUCSYN_STPAGB -\family default - is defined. -\end_layout - -\begin_layout Standard -Finally, -\family typewriter -Xsource -\family default - is an array of -\family typewriter -NUCSYN_SOURCE_NUM -\family default - pointers, each points to an array of -\family typewriter -ISOTOPE_ARRAY_SIZE -\family default -. - Each of these arrays contains the amount of mass ejected by a particular - source e.g. - GB stars, TPAGB stars, SNe etc. - This is very useful in conjunction with -\family typewriter -NUCSYN_ID_SOURCES -\family default - (see -\family typewriter -nucsyn.h -\family default - and -\family typewriter -nucsyn_macros.h -\family default -). -\end_layout - -\begin_layout Subsection -Code layout, header files, flow and fuck-ups -\end_layout - -\begin_layout Standard -\begin_inset CommandInset label -LatexCommand label -name "sub:Code-layout" - -\end_inset - -The code is split into a series of directories each representing a broadly - similar set of physics. - Only the nucleosynthesis library is described in any detail here since - the other libraries are (mostly) just a port of the (huge!) Fortran function - to C. - Some header file information is in -\begin_inset CommandInset ref -LatexCommand ref -reference "sub:Advanced-Configuration" - -\end_inset - -. -\end_layout - -\begin_layout Subsubsection - -\family typewriter -binary_star_functions -\end_layout - -\begin_layout Standard -\begin_inset CommandInset label -LatexCommand label -name "sub:binary_star_functions" - -\end_inset - -This library ( -\family typewriter -libbinary_star_functions.so -\family default -) contains functions which deal with the binary system such as Roche Lobe - calculation, angular momentum calculation, supernova kicks ( -\family typewriter -do_kick.c -\family default -, -\family typewriter -monte_carlo_kick.c -\family default -, -\family typewriter -distributed_kick.c -\family default - and files references therein), contact systems ( -\family typewriter -contact_system.c -\family default -), stellar mergers ( -\family typewriter -mix.c -\family default -) and common envelope evolution ( -\family typewriter -common_envelope_evolution.c -\family default -). - Note there is a useful flag called -\family typewriter -MIXDEBUG -\family default - which if you -\family typewriter -#define MIXDEBUG -\family default - you'll get lots of useful mixing information (especially in -\family typewriter -common_envelope_evolution.c -\family default -). -\end_layout - -\begin_layout Standard -The supernova kicks deserve some mention: the old-fashioned way of doing - the kicks, and perhaps the simplest to understand, is that the kick variables - (orbital position, two angles and velocity) are chosen randomly from a - distribution ( -\family typewriter -monte_carlo_kick.c -\family default -). - I introduced the distributed kick function ( -\family typewriter -distributed_kick.c -\family default -) to run a grid across these variables and consider each in turn. - Of course this slows the code down (since if there are 10 points per dimension - that is -\begin_inset Formula $10^{4}$ -\end_inset - - points) and is complicated because the position of the code has to be saved. - For this reason the code is complicated: at each kick the code calls the - -\family typewriter -fork -\family default - function to make a child process identical to itself. - This runs then exits and the parent runs the next point on the distributed - grid. - The source file contains the gory details of the control code. - Note that this code has never been used in anger and as such there might - be bugs. - It also slows down your grid but because it -\family typewriter -fork -\family default -s it only runs from the point when the kick occurs -- so it is as fast as - it can be. - Please feel free to want to use it, it will give me a reason to make sure - it works, but note there is a known bug in the distributed kicking which - needs to be fixed (see the -\family typewriter -#warning -\family default -). -\end_layout - -\begin_layout Standard -In terms of nucleosynthesis really there are only a few functions which - need attention. - Common envelope evolution ( -\family typewriter -common_envelope_evolution.c -\family default -) compares the mass of the stars before and after and uses these masses - to determine the abundance of the common envelope from the stellar abundance - and how much of it is yielded to the ISM (assuming some of the envelope - is lost, which is quite likely). - This is a major source of yielded mass, especially in close low-mass MS-MS - binaries. - The mix function ( -\family typewriter -mix.c -\family default -) mixes both stars, usually completely but sometimes the compact cores merge - and the envelope merges. - The detailed comments in the code explain how this is done (it is similar - to the prescription in -\begin_inset CommandInset citation -LatexCommand citealp -key "2002MNRAS_329_897H" - -\end_inset - -). -\end_layout - -\begin_layout Standard -The -\family typewriter -update_masses.c -\family default - function deals with mass transfer during RLOF. - Note that if, for example, star 1 loses mass -\begin_inset Formula $\delta m$ -\end_inset - - then this may be accreted onto star 2 (if RLOF is conservative). - In that case it is considered as a -\emph on -negative yield -\emph default - (see section -\begin_inset CommandInset ref -LatexCommand ref -reference "sub:Yield-calculations" - -\end_inset - - for yield calculation details) - details are in the function. - Novae are yielded here by a call to -\family typewriter -nucsyn_set_nova_abunds -\family default - followed by a call to -\family typewriter -nucsyn_calc_yields -\family default -. - -\family typewriter -acquire_stellar_parameters_at_apparent_evolution_age.c -\family default - yields some types of supernovae (core-collapse, AIC and IIa). -\end_layout - -\begin_layout Subsubsection - -\family typewriter -hrdiag -\end_layout - -\begin_layout Standard -\begin_inset CommandInset label -LatexCommand label -name "sub:hrdiag" - -\end_inset - - -\begin_inset Quotes eld -\end_inset - - -\emph on -H-R diagram for population I stars. - Computes the new mass, luminosity, radius & stellar type -\emph default -. -\begin_inset Quotes erd -\end_inset - - The comment is out of date: it is valid for Pop. - II stars as well. -\end_layout - -\begin_layout Standard -This is the mythical function at the heart of SSE/BSE, ask Jarrod and Onno - about it, they are the experts. - Given a stellar mass, initial mass and age, -\family typewriter -hrdiag -\family default - computes the luminosity and radius. - It was recently split from a huge monolithic monster into a set of functions - in the -\family typewriter -hrdiag/ -\family default - directory. - -\end_layout - -\begin_layout Standard -Little nucleosynthesis is in this function although -\family typewriter -hrdiag_nucsyn -\family default - does contain the call to the -\family typewriter -nucsyn_tpagb -\family default - function, as well as first and second dredge-up. - It also contains the estimate for the mass at the start of the HG. - Note that first dredge-up now occurs at a core mass based on a fit to Evert - Glebbeek's models. -\end_layout - -\begin_layout Standard -There is -\family typewriter -#define NO_UNEXPECTED_MASS_CHANGES -\family default - which forces the mass of the star to be constant in -\family typewriter -hrdiag -\family default -. - While I am no longer clear on -\emph on -exactly -\emph default - why I did this, I think it was because the mass of the star was being set - to zero in -\family typewriter -hrdiag -\family default - when a supernova exploded which broke a call to -\family typewriter -nucsyn_calc_yields -\family default - later on (mass was not conserved because the yields are not calculated - here!). - It is best to leave this here since things seem to work now with it in - -- though note it's slightly different to the Fortran version. -\end_layout - -\begin_layout Subsubsection - -\family typewriter -iteration -\end_layout - -\begin_layout Standard -\begin_inset CommandInset label -LatexCommand label -name "sub:iteration" - -\end_inset - -The iteration library ( -\family typewriter -libiteration.so -\family default -) contains the initialisation and flow blocks. - Of interest are -\family typewriter -initialize_parameters.c -\family default - which sets initial values and allocates memory for arrays, -\family typewriter -deltat.c -\family default - which sets the timestep (although -\emph on -not in RLOF! -\emph default -), -\family typewriter -iterate.c -\family default - which is the main program loop (and contains calls to many functions e.g. - -\family typewriter -nucsyn_WR -\family default -, -\family typewriter -nucsyn_radioactive_decay -\family default - etc.), -\family typewriter -special_cases.c -\family default - which deals with RLOF -- this has mostly been moved into the -\family typewriter -RLOF/ -\family default - directory. - The rest of the functions are quite dull. -\end_layout - -\begin_layout Subsubsection - -\family typewriter -RLOF -\end_layout - -\begin_layout Standard -\begin_inset CommandInset label -LatexCommand label -name "sub:RLOF" - -\end_inset - -This has functions which deal with dynamical timescale Roche lobe overflow. - This was the original -\family typewriter -special_cases -\family default - function, which is now slimmed down. - Edit this if you want to see how the SNIa accretion works (e.g. - the Hachisu disk-wind mechanism). -\end_layout - -\begin_layout Standard -As of version 1.20pre55 the new adaptive RLOF algorithm is contained in the - -\family typewriter -RLOF_mass_transfer_rate function -\family default - -- please see the -\family typewriter -binary_c-RLOF.lyx/pdf -\family default - file for details. -\end_layout - -\begin_layout Subsubsection - -\family typewriter -logging -\end_layout - -\begin_layout Standard -\begin_inset CommandInset label -LatexCommand label -name "sub:logging" - -\end_inset - -Contains some functions used to output either to the screen or a file. - Not very interesting but very useful! -\end_layout - -\begin_layout Subsubsection - -\family typewriter -setup -\end_layout - -\begin_layout Standard -\begin_inset CommandInset label -LatexCommand label -name "sub:setup" - -\end_inset - -This sets the code up because -\family typewriter -set_up_variables -\family default - is called by the -\family typewriter -main -\family default - function. - It reads in the command line arguments and sets them to variables. - There is also the -\family typewriter -instar -\family default - function which initializes the -\begin_inset Quotes eld -\end_inset - -collision matrix -\begin_inset Quotes erd -\end_inset - - -\family typewriter -ktype -\family default - (see -\begin_inset CommandInset citation -LatexCommand citealp -key "2002MNRAS_329_897H" - -\end_inset - -). - -\end_layout - -\begin_layout Standard -In version 1.2x it also contains the -\family typewriter -parse_arguments -\family default - function, which takes command line arguments and puts them into (in particular) - the -\family typewriter -preferences -\family default - structure. - This function is very useful if you want to put in your own arguments. -\end_layout - -\begin_layout Subsubsection - -\family typewriter -single_star_functions -\end_layout - -\begin_layout Standard -\begin_inset CommandInset label -LatexCommand label -name "sub:single_star_functions" - -\end_inset - -A set of functions that act on a single star. - -\end_layout - -\begin_layout Standard - -\family typewriter -calc_lum_and_evol_time.c -\family default - (was the poorly-named -\family typewriter -star.f -\family default - in the Fortran) which calculates the luminosity and lifetimes at various - stages in the star's life and is -\emph on -very important! -\emph default - -\family typewriter -calc_lum_and_evol_time -\family default -has a cache feature which should be enabled. - This is because it takes just the mass and initial mass of the star (and, - implicitly, the (constant) metallicity) as arguments. - Also, it is often called with identical arguments mulitple times due to - bad design of the code. - As such, it is faster to store the results in memory and recycle them if - possible. - At present it stores the previous two results ( -\family typewriter -CLAET_CACHE_SIZE -\family default - is 2). - The cache is enabled when -\family typewriter -CLAET_CACHE -\family default - is defined (in -\family typewriter -code_options.h -\family default -). - This cache buys about 15% of runtime compared to the case when it is not - used (i.e. - it is very useful!). - If only -\family typewriter -hrdiag -\family default - had a similar feature\SpecialChar \ldots{} - -\end_layout - -\begin_layout Standard - -\family typewriter -calc_stellar_wind_mass_loss.c -\family default - is the mass loss function - you'll need to hack this to put in your own - mass-loss prescription. -\end_layout - -\begin_layout Subsubsection - -\family typewriter -zfuncs -\end_layout - -\begin_layout Standard -\begin_inset CommandInset label -LatexCommand label -name "sub:zfuncs" - -\end_inset - -The so called -\begin_inset Quotes eld -\end_inset - -metallicity functions -\begin_inset Quotes erd -\end_inset - - i.e. - fits to -\begin_inset Formula $L$ -\end_inset - -, -\begin_inset Formula $R$ -\end_inset - -, -\begin_inset Formula $M_{\textrm{c}}$ -\end_inset - - etc. - as a function of -\begin_inset Formula $M$ -\end_inset - - and -\begin_inset Formula $Z$ -\end_inset - - (and perhaps other things). - These are lots of tiny functions which contain fitting formulae. - I have added -\family typewriter -bh_mass.c -\family default - as an alternative BH mass prescription based on some of Jarrod's code. - -\end_layout - -\begin_layout Standard -Lately I have added some new functions, such as -\family typewriter -mc_1DUP -\family default - (the core mass at which first dredge up occurs), -\family typewriter -fphase -\family default - (the fractional age in a given stellar evolution phase), -\family typewriter -rwd -\family default - and -\family typewriter -lwd -\family default - (radius and luminosity of a white dwarf) etc. - This seems a reasonable location for storing small, useful functions. -\end_layout - -\begin_layout Standard -Please note that I have optimized these functions to the hilt, which means - they are often not too readable. - This is because these functions are called every time -\family typewriter -calc_lum_and_evol_time -\family default - is called, which is at least twice every timestep (and usually more often). -\end_layout - -\begin_layout Subsubsection - -\family typewriter -maths -\end_layout - -\begin_layout Standard -In this directory I store mathematical functions. - Some are from Numerical Recipes in C. - Of particular interest is the -\family typewriter -kaps_rentrop -\family default - function, which uses the Kaps-Rentrop fourth-order implicit scheme to solve - nuclear networks. - Also, the -\family typewriter -interpolate -\family default - function is a custom-made (i.e. - by me!) linear interpolation routine. - It is very fast, highly optimized and hence unreadable. -\end_layout - -\begin_layout Subsection - -\family typewriter -nucsyn -\end_layout - -\begin_layout Standard -\begin_inset CommandInset label -LatexCommand label -name "sub:nucsyn" - -\end_inset - -The nucleosynthesis functions are in a directory of their own. - It contains the functions which deal with the nucleosynthesis part of the - code which runs in parallel to SSE/BSE. - That is -\emph on -not -\emph default - to say that all the nucleosynthesis is done here, but most of it is. -\end_layout - -\begin_layout Standard -To enable nucleosynthesis in the code you must -\end_layout - -\begin_layout Standard - -\family typewriter -#define NUCSYN -\end_layout - -\begin_layout Standard -somewhere, usually in -\family typewriter -binary_parameters.h -\family default - (which gets included in -\family typewriter -binary_macros.h -\family default - so -\family typewriter -nucsyn.h -\family default - -- you should include -\family typewriter -nucsyn.h -\family default - in every nucsyn library file). - It is vitally important that if you add anything to the nucleosynthesis - code you enclose it in something like -\end_layout - -\begin_layout Standard - -\family typewriter -#ifdef NUCSYN -\end_layout - -\begin_layout Standard - -\family typewriter -... -\end_layout - -\begin_layout Standard - -\family typewriter -#endif /* NUCSYN */ -\end_layout - -\begin_layout Standard -so that if nucleosynthesis is not required it can be turned off. -\end_layout - -\begin_layout Standard -There are then further options in -\family typewriter -nucsyn_parameters.h -\family default - (see section -\begin_inset CommandInset ref -LatexCommand ref -reference "sub:Advanced-Configuration" - -\end_inset - -). -\end_layout - -\begin_layout Standard -NOTE! -\emph on -Every function in the nucsyn library has -\emph default - -\family typewriter -nucsyn -\family default - -\emph on -prepended to the function name - please maintain this convention! -\end_layout - -\begin_layout Subsubsection -Header files and isotope arrays -\end_layout - -\begin_layout Standard -\begin_inset CommandInset label -LatexCommand label -name "sub:Header-files-and-isotope-arrays" - -\end_inset - -All abundances are stored as mass fractions when the array is called -\family typewriter -X\SpecialChar \ldots{} - -\family default -, number densities are referred to as -\family typewriter -N\SpecialChar \ldots{} - -\family default -. - The index for each array ranges from -\begin_inset Formula $0$ -\end_inset - - to -\family typewriter -ISOTOPE_ARRAY_SIZE -\family default - which is defined in -\family typewriter -nucsyn_isotopes.h -\family default - however you should -\emph on -NEVER -\emph default - manually access the array by e.g. - -\family typewriter -X[0] -\family default - or -\family typewriter -X[1] -\family default -, you should use the predefined macros referring to each isotope in -\family typewriter -nucsyn_isotopes.h -\family default -. - For example, XC12 is defined like this -\end_layout - -\begin_layout Standard - -\family typewriter -#define XC12 2 -\end_layout - -\begin_layout Standard -so the second isotope in the array is -\begin_inset Formula $^{12}\textrm{C}$ -\end_inset - -. - All the others are defined similarly. - To access the -\begin_inset Formula $^{12}\textrm{C}$ -\end_inset - - abundance you should then use -\family typewriter -X[XC12] -\family default - or -\family typewriter -N[XC12] -\family default -. - Perhaps also useful for you is -\family typewriter -ISOTOPE_MEMSIZE -\family default - which is just the size (in bytes) of the abundance array. -\end_layout - -\begin_layout Standard -Why is this an advantage? It is very useful to be able to pull isotopes - out which are not of interest (this speeds up the code) without breaking - all the others, the historical development of the code ( -\begin_inset Formula $^{1}\textrm{H}$ -\end_inset - -, -\begin_inset Formula $^{4}\textrm{He}$ -\end_inset - - and CNO came first) is not a problem and the addition of new nuclei is - easy (but remember section -\begin_inset CommandInset ref -LatexCommand ref -reference "sub:Setup-functions" - -\end_inset - -). - It also makes the code -\emph on -bloody easy to read -\emph default - since it is painfully obvious which isotope you are referring to! This - is important late at night after too much coffee (or other drink!). -\end_layout - -\begin_layout Subsubsection -Setup functions -\end_layout - -\begin_layout Standard -\begin_inset CommandInset label -LatexCommand label -name "sub:Setup-functions" - -\end_inset - - -\family typewriter -nucsyn_set_nuc_masses -\family default - sets the nuclear masses (in grams!) and atomic numbers. - If you add an isotope to -\family typewriter -nucsyn_isotopes.h -\family default - (see section -\begin_inset CommandInset ref -LatexCommand ref -reference "sub:Header-files-and-isotope-arrays" - -\end_inset - -) you -\emph on -MUST -\emph default - change this function to set the nuclear mass or atomic number. - If you do not then the number will be undefined and strange things will - happen even though your nice new code looks fine. - Trust me! -\end_layout - -\begin_layout Standard - -\family typewriter -nucsyn_initial_abundances -\family default - is obviously important because it defines your initial abundance mix based - on the metallicity. -\end_layout - -\begin_layout Subsubsection -First and Second Dredge-up -\end_layout - -\begin_layout Standard -\begin_inset CommandInset label -LatexCommand label -name "sub:First-and-Second-DUP" - -\end_inset - -First and second dredge-up are handled by the functions -\family typewriter -nucsyn_set_1st_dup_abunds -\family default - and -\family typewriter -nucsyn_set_2nd_dup_abunds -\family default - which perturb the surface abundances. - There may be problems in binaries because the evolution is different to - single stars, but I try to take this into account by scaling the CNO abundances - to whatever the stellar CNO abundance is. - Thanks to Evert Glebbeek and Richard Stancliffe for helping out with this, - the results will be published in one of our CEMP papers soon. -\end_layout - -\begin_layout Subsubsection -TPAGB functions (3rd dredge-up and HBB) -\end_layout - -\begin_layout Standard -\begin_inset CommandInset label -LatexCommand label -name "sub:TPAGB-functions" - -\end_inset - -The first section of the library to be written was the synthetic TPAGB evolution - (see -\begin_inset CommandInset citation -LatexCommand citealp -key "Izzard_et_al_2003b_AGBs" - -\end_inset - -). - This is controlled by the function -\family typewriter -nucsyn_tpagb -\family default - (which is called in -\family typewriter -hrdiag -\family default - if the stellar type is TPAGB). - The function itself has a lot of stuff in it, some of which is not currently - used, but basically it determines whether the next thermal pulse has been - reached by the star and if so it does third dredge-up(and perhaps there's - some hot-bottom burning). -\end_layout - -\begin_layout Standard -On the first pulse (when the function is first called for the star, actually - if -\family typewriter -num_thermal_pulses -\family default - < 0, which is the case for any stellar type other than TPAGB) the function - -\family typewriter -nucsyn_init_first_pulse -\family default - is called which sets a few things like the interpulse period and -\begin_inset Formula $M_{\textrm{c,min}}$ -\end_inset - - for dredge-up. -\end_layout - -\begin_layout Standard -For subsequent timesteps the -\family typewriter -nucsyn_tpagb -\family default - function calls -\family typewriter -nucsyn_tpagb_H_shell_burn -\family default - to burn the hydrogen shell during the interpulse period and save the amount - of core mass growth -\begin_inset Formula $\Delta M_{\textrm{c}}$ -\end_inset - -. - -\end_layout - -\begin_layout Standard -There is then a check to see if the star is hot enough for HBB -- this is - done by fitting the temperature (see -\family typewriter -nucsyn_set_hbb_conditions -\family default -, -\family typewriter -nucsyn_hbbtmax -\family default - and -\family typewriter -nucsyn_tpagb_rhomax -\family default -) to mass and metallicity. - If so the -\family typewriter -nucsyn_hbb -\family default - function is called. - The free parameters associated with HBB -\begin_inset CommandInset citation -LatexCommand citep -key "Izzard_et_al_2003b_AGBs" - -\end_inset - - are set in -\family typewriter -nucsyn_set_tpagb_free_parameters -\family default - (these are the burn times, mixing fractions etc.). - Burning is done by the extremely funky functions -\family typewriter -nucsyn_anal_CNO_burn -\family default -, -\family typewriter -nucsyn_anal_MgAl_burn -\family default - and -\family typewriter -nucsyn_anal_NeNa_burn -\family default -. - Currently attempts to burn Be and Li have failed -- please develop an algorithm -, I have a few ideas that don't work\SpecialChar \ldots{} - -\end_layout - -\begin_layout Standard -If the next pulse is reached then -\family typewriter -nucsyn_third_dredge_up -\family default - is called to deal with third dredge-up. - This dredges up a mass -\begin_inset Formula $\lambda\times\Delta M_{\textrm{c}}$ -\end_inset - - and mixes it with the envelope. - The abundances of the dredged-up material are set in -\family typewriter -nucsyn_set_third_dredgeup_abunds -\family default - (and -\family typewriter -nucsyn_s_process -\family default - for s-process elements). - Note that the s-process is (in V1.20-pre63) currently disabled pending new - data from Carlo Abate. -\end_layout - -\begin_layout Standard -As of V1.2 there is an option to evolve STPAGB stars by defining -\family typewriter -NUCSYN_STPAGB -\family default - in -\family typewriter -nucsyn.h -\family default -. - These have been updated recently to follow Poelarends' models, but I do - not believe the HBB in them, -\emph on -so use them at your own risk -\emph default -. -\end_layout - -\begin_layout Subsubsection -Hot-Bottom Burning -\end_layout - -\begin_layout Standard -\begin_inset CommandInset label -LatexCommand label -name "sub:Hot-Bottom-Burning" - -\end_inset - -While this sounds painful, really it's not! HBB is the process where the - convective zone in a TPAGB star reaches down into the hydrogen burning - shell. - This occurs in -\begin_inset Formula $4-8\mathrm{\,M_{\odot}}$ -\end_inset - - stars (for -\begin_inset Formula $Z=0.02$ -\end_inset - -, lower masses for lower metallicity). - I have two burning routines which can deal with this: -\end_layout - -\begin_layout Enumerate -The original analytic routine. - This uses analytic solutions to the CN, ON, NeNa and MgAl cycles, together - with some approximate fudges to join them into the CNO and NeNaMgAl cycles, - to solve for the abundances. - This is fast but sometimes, when used outside the range of the approximations, - -\emph on -very -\emph default - unstable. -\end_layout - -\begin_layout Enumerate -The new numerical solver. - This uses a 4th-order implict (Kaps-Rentrop) scheme to solve for the abundances - as a function of time. - It does -\emph on -not -\emph default - depend on approximations, and currently burns the -\begin_inset Formula $pp$ -\end_inset - --chain, CNO cycles (hot or cold) and the full NeNa/MgAl chains/cycles. - In theory it can be extended to any nuclear network (although it is designed - for small networks -- it will get very slow with larger networks). - It turns out that, after much code optimization, the numerical solver is - about as fast as the analytic solver! I think this is because to solve - numerically requires additions, subtractions, multiplications and divisions, - while analytic solutions require lots of exponentials. - However, whether the numerical solver quickly converges on a result depends - on the initial timestep. - Be careful with that, I have a number of schemes which can improve this. -\end_layout - -\begin_layout Subsubsection -nucsyn_WR -\end_layout - -\begin_layout Standard -\begin_inset CommandInset label -LatexCommand label -name "sub:nucsyn_WR" - -\end_inset - -This is a set of phenomenological fits to Lynnette Dray's models for massive - stars and helium star remnants. - It is self-contained (see the details above and in the function) and contains - useful stuff regarding logging of O/B and WR stars. - I recently updated it to use tabular lookups instead of fitting functions. - -\end_layout - -\begin_layout Standard -The latest version includes tables from Richard Stancliffe which follow - all isotopes, not just elemental CNO and H, He. -\end_layout - -\begin_layout Subsubsection -The -\begin_inset Formula $r$ -\end_inset - --process -\end_layout - -\begin_layout Standard -\begin_inset CommandInset label -LatexCommand label -name "sub:The-r-process" - -\end_inset - -I have included some yields from -\begin_inset CommandInset citation -LatexCommand citet -key "1999ApJ...525..886A" - -\end_inset - - and -\begin_inset CommandInset citation -LatexCommand citet -key "2004ApJ...617.1091S" - -\end_inset - - which you can activate with the appropriate define in -\family typewriter -nucsyn_parameters.h -\family default -. - This code has -\emph on -not been well tested -\emph default - so beware! -\end_layout - -\begin_layout Subsubsection -Winds and Mixing -\end_layout - -\begin_layout Standard -\begin_inset CommandInset label -LatexCommand label -name "sub:Winds-and-Mixing" - -\end_inset - -Colliding winds and the like are a complicated business! -\family typewriter -nucsyn_update_abundances -\family default - is called when to deal with this. - The function is well commented so for details please refer to it but briefly - it takes the wind loss from each star and the amount of that accreted by - the companion ( -\family typewriter -dmr -\family default - and -\family typewriter -dmt -\family default -, set elsewhere), determines whether the accreted matter should reach the - surface (by the factor -\begin_inset Formula $f$ -\end_inset - - set in -\family typewriter -nucsyn_choose_wind_mixing_factor -\family default -) or not and if so mixes it in or makes a new accretion layer on the surface. - It also yields the wind loss by a call to -\family typewriter -nucsyn_calc_yields -\family default - and the mass accreted by a similar call but with a negative number. - Note: mass is removed from the surface of the star by the function -\family typewriter -nucsyn_remove_dm_from_surface -\family default - so that it is preferentially removed from the accretion layer rather than - the stellar envelope. - Convective stars have no accretion layer, if one is present a call to -\family typewriter -nucsyn_mix_accretion_layer_and_envelope -\family default - soon removes it. -\end_layout - -\begin_layout Subsubsection -Abundance profiles ( -\family typewriter -NUCSYN_PROFILES -\family default -) -\end_layout - -\begin_layout Standard -\begin_inset CommandInset label -LatexCommand label -name "sub:Abundance-profiles-(NUCSYN_PROFILES)" - -\end_inset - -This macro and associated code was removed in version 1.20pre71. - Consider using -\emph on -BONNFIRES -\emph default -instead. -\end_layout - -\begin_layout Subsubsection -Explosions (supernovae and novae) -\end_layout - -\begin_layout Standard -\begin_inset CommandInset label -LatexCommand label -name "sub:Explosions" - -\end_inset - -Supernova yields are looked up in tables and yielded in -\family typewriter -nucsyn_sn_yield -\family default -. - Novae are dealt with similarly in -\family typewriter -nucsyn_set_nova_abunds -\family default - although the yield call is in -\family typewriter -update_masses -\family default - in -\family typewriter -libbinary_star_functions -\family default - (which deals with RLOF). -\end_layout - -\begin_layout Subsubsection -Yield calculations -\end_layout - -\begin_layout Standard -\begin_inset CommandInset label -LatexCommand label -name "sub:Yield-calculations" - -\end_inset - -The calls to -\family typewriter -nucsyn_calc_yields -\family default - modify the arrays -\family typewriter -Xyield -\family default - in the -\family typewriter -star -\family default - structures. - These contain the mass of material of each isotope lost by the star, so - if -\family typewriter -nucsyn_calc_yields -\family default - is called for (say) wind loss by an amount -\begin_inset Formula $\delta m$ -\end_inset - - with abundances -\begin_inset Formula $X_{i}$ -\end_inset - - then the amount of mass lost as isotope -\begin_inset Formula $i$ -\end_inset - - is -\begin_inset Formula $\delta m\times X_{i}$ -\end_inset - - which is added to the appropriate -\family typewriter -Xyield -\family default - array item -\begin_inset Formula $i$ -\end_inset - -. - This is a simple definition for single stars but gets complicated in binaries - because wind/RLOF accretion takes place. - In that case the same -\family typewriter -nucsyn_calc_yields -\family default - function is called but for a negative mass -\begin_inset Formula $-\delta m$ -\end_inset - -. - In this way -\emph on -mass is conserved -\emph default - because the other star yields the -\begin_inset Formula $\delta m$ -\end_inset - - (or perhaps more mass if some is lost from the system). - The total mass lost from the system is then just the sum of the -\family typewriter -Xyield -\family default - for both stars. - -\end_layout - -\begin_layout Standard -The array -\family typewriter -mpyield -\family default - stores the values of -\begin_inset Formula $p_{\textrm{m},i}$ -\end_inset - -, the enhancement of isotope -\begin_inset Formula $i$ -\end_inset - - relative to the ZAMS abundance and divided by the initial mass (note use - -\family typewriter -pms_mass -\family default - not -\family typewriter -ZAMS_mass -\family default - since the latter is redefined by accretion processes). -\end_layout - -\begin_layout Standard -Binary system yields are easy to calculate because they are just the sum - of both stars' yields, this is done in -\family typewriter -nucsyn_binary_yield -\family default -. - The appropriate -\begin_inset Formula $p_{\textrm{m}}$ -\end_inset - - yields are more difficult to define but there is an attempt. - -\end_layout - -\begin_layout Subsubsection -Logging and minor functions -\end_layout - -\begin_layout Standard -\begin_inset CommandInset label -LatexCommand label -name "sub:Logging-and-minor-functions" - -\end_inset - -There are numerous logging functions for debugging and general pretty-picture-ma -nufacture, e.g. - -\family typewriter -nucsyn_log -\family default -, -\family typewriter -nucsyn_long_log -\family default -, -\family typewriter -nucsyn_short_log -\family default -, -\family typewriter -nucsyn_j_log -\family default -. - Most of these are activated or deactivated in -\family typewriter -nucsyn.h -\family default -. - Other minor functions: -\family typewriter -nucsyn_totalX -\family default - calculates the total mass fraction (or actually the total sum of array - elements), -\family typewriter -nucsyn_square_bracket -\family default - calculates an abundance in -\begin_inset Quotes eld -\end_inset - -square bracket notation -\begin_inset Quotes erd -\end_inset - - by mass fraction (should it be by number?); -\family typewriter -nucsyn_mix_shells -\family default - mixes two isotope arrays together (very useful!) there are the other mixing - functions -\family typewriter -nucsyn_dilute_shell -\family default - and -\family typewriter -nucsyn_dilulte_shell_to -\family default - which are similarly useful; -\family typewriter -nucsyn_radioactive_decay -\family default - decays a few isotopes -- it is by no means exhaustive, there may be other - isotopes you wish to place in here but it's easy to extend; -\family typewriter -nucsyn_mole_fraction -\family default - converts an array of mass fractions to mole fractions, perhaps useful for - the square bracket logging? -\end_layout - -\begin_layout Subsubsection -Other stellar remnants -\end_layout - -\begin_layout Standard -\begin_inset CommandInset label -LatexCommand label -name "sub:Other-stellar-remnants" - -\end_inset - -Some stellar types are not dealt with by nucleosynthesis. - There include WDs ( -\family typewriter -nucsyn_set_WD_abunds -\family default -), which are assumed to: HeWD 100% -\begin_inset Formula $^{4}\textrm{He}$ -\end_inset - -, COWD 80% -\begin_inset Formula $^{12}\textrm{C}$ -\end_inset - - and 20% -\begin_inset Formula $^{16}\textrm{O}$ -\end_inset - - while ONeWDs are 80% -\begin_inset Formula $^{16}\textrm{O}$ -\end_inset - - and 20% -\begin_inset Formula $^{20}\textrm{Ne}$ -\end_inset - -. - This could be improved (to take into account, say, the heavier metals) - but note that any accretion onto the surface from a non-degenerate companion - will mask the above abundances (since an accretion layer will form on the - surface unless there are novae) and the business of accretion onto WDs - is -\emph on -very complicated indeed -\emph default -. -\end_layout - -\begin_layout Standard -NSs and BHs ( -\family typewriter -nucsyn_set_remnant_abunds -\family default -) are assumed to be all neutrons ( -\family typewriter -Xsurf[Xn]=1.0 -\family default -). - -\end_layout - -\begin_layout Subsection -Control scripts -\end_layout - -\begin_layout Standard -\begin_inset CommandInset label -LatexCommand label -name "sub:Control-scripts" - -\end_inset - -I have a number of control scripts written in Perl which test the code and - output graphs and data for e.g. - AGB stars and WR stars (to compare to full evolution models), stellar yields - etc. - There might be some documentation here eventually\SpecialChar \ldots{} - it all depends on whether - you prefer writing your own scripts (that way you'll learn how it all works) - or just having a black-box that works (you can always look at the source - code). -\end_layout - -\begin_layout Standard -A very useful script is -\begin_inset Quotes eld -\end_inset - -zipup -\begin_inset Quotes erd -\end_inset - - which makes a file -\family typewriter -binary_c.zip -\family default - containing this manual and all the source code. - See also -\family typewriter -grid.pl -\family default -. -\end_layout - -\begin_layout Section -Advanced Configuration -\end_layout - -\begin_layout Standard -\begin_inset CommandInset label -LatexCommand label -name "sub:Advanced-Configuration" - -\end_inset - - -\end_layout - -\begin_layout Standard -There are three configuration files which affect how the code is built: - -\family typewriter -code_options.h -\family default -, -\family typewriter -binary_parameters.h -\family default - and -\family typewriter -nucsyn/nucsyn_parameters.h -\family default -. -\end_layout - -\begin_layout Standard -Also, some options are enabled via the Makefile (set up by the -\emph on -configure -\emph default -script). - -\end_layout - -\begin_layout Subsection -configure -\end_layout - -\begin_layout Standard -The -\emph on -configure -\emph default -script should be run before you do anything else. - It makes the -\emph on -Makefile -\emph default - and also makes a source file called -\emph on -nucsyn/nucsyn_unrolled_functions.h -\emph default -. - This function contains loop-unrolled versions of a few bottleneck functions - which execute more quickly than if they were in loops (yes, even telling - the compiler to unroll the loops is not as fast). -\end_layout - -\begin_layout Subsection -Makefile -D\SpecialChar \ldots{} - -\end_layout - -\begin_layout Standard -Some options are set up by -\emph on -configure -\emph default -and passed into the -\emph on -Makefile -\emph default -as -\family typewriter --D\SpecialChar \ldots{} - -\family default - arguments to the compiler: -\end_layout - -\begin_layout Itemize - -\family typewriter -LINUX -\family default - is defined if you're running Linux. - This is useful for some timers and segfault catchers which only work with - the Linux libraries. -\end_layout - -\begin_layout Itemize - -\family typewriter -LARGEFILE_SOURCE -\family default - and -\family typewriter -FILE_OFFSET_BITS -\family default - were once useful for large output files on 64-bit machines (>2GB). - This may no longer be a problem but they do not hurt. -\end_layout - -\begin_layout Itemize - -\family typewriter -CPUFREQ -\family default - is the frequency of your CPU (in Mhz) -- this is very useful for timing - information. - (Taken from -\family typewriter -/proc/cpuinfo -\family default - if available, -\family typewriter -sysctl -a -\family default - on MacOS/Darwin) -\end_layout - -\begin_layout Subsection - -\family typewriter -code_options.h -\end_layout - -\begin_layout Standard -\begin_inset CommandInset label -LatexCommand label -name "sub:code_options.h" - -\end_inset - -This contains -\emph on -non-physics -\emph default - options. - You probably do not want to change this file unless you have compilation - problems or you want to optimize the code (even more!). - The options are the following (in the order given in the file) -\end_layout - -\begin_layout Itemize - -\family typewriter -SEGFAULTS -\family default - This should be set if want segfaults on a code failure. - This is useful if you are debugging with gdb. -\end_layout - -\begin_layout Itemize - -\family typewriter -ACML -\family default - should be set if you wish to use the AMD math (sic) library. - This should not be set here, but with in the -\emph on -Makefile -\emph default - with the -\emph on -configure -\emph default - script. -\end_layout - -\begin_layout Itemize - -\family typewriter -DUMA -\family default - should be set if you wish to use the DUMA memory checking library. - This should not be set here, but with in the -\emph on -Makefile -\emph default - with the -\emph on -configure -\emph default - script. -\end_layout - -\begin_layout Itemize - -\family typewriter -DEBUG -\family default - is either zero ( -\family typewriter -0 -\family default -) or one ( -\family typewriter -1 -\family default -). - All debugging statements should use the -\family typewriter -Dprint -\family default - function instead of the standard C-library function -\family typewriter -printf -\family default -. - If -\family typewriter -DEBUG -\family default - is zero, then the compiler should never build the debug statements into - the code (modern compilers will behave in this way). - However, if in doubt enable the -\family typewriter -DISABLE_DPRINT -\family default - option. -\end_layout - -\begin_layout Itemize - -\family typewriter -COMPARE_FORTRAN -\family default - activates a number of extra print statements for comparison with a version - of Jarrod's FORTRAN code I have lying around. - It's probably of little interest to you. -\end_layout - -\begin_layout Itemize - -\family typewriter -LOGGING -\family default - Enables logging, you want this otherwise what is the point in running the - code? -\end_layout - -\begin_layout Itemize - -\family typewriter -FASTEST -\family default - Makes things a little faster, or used to. - I am not sure it does now\SpecialChar \ldots{} - -\end_layout - -\begin_layout Itemize - -\family typewriter -BATCHMODE -\family default - Enables the interactive batch mode. - You should compile this in because the grid.pl script (which makes populations - of stars) uses it. - -\end_layout - -\begin_layout Itemize - -\family typewriter -TIMEOUT_SECONDS -\family default - Every time the code is run, a timer is set. - If this is not reset within -\family typewriter -TIMEOUT_SECONDS -\family default - seconds, -\emph on -binary_c -\emph default - is deliberately crashed. - Clearly, if your star has not evolved in 60 seconds then something is wrong. -\end_layout - -\begin_layout Itemize - -\family typewriter -USE_MEMSET -\family default - This uses memset instead of loops to set memory. - I think all modern C libraries should have this so it may be standard in - future. - Use it. -\end_layout - -\begin_layout Itemize - -\family typewriter -ALLOC_CHECKS -\family default - This should be defined, it enables checks on memory allocation (which slows - the code down a little bit). - Note that if DEBUG is -\begin_inset Formula $1$ -\end_inset - - this will be set automatically. -\end_layout - -\begin_layout Itemize - -\family typewriter -STARDATA_STATUS -\family default - used to allow output from the stardata_status function, but it is not clear - if this does anything anymore. -\end_layout - -\begin_layout Itemize - -\family typewriter -INTERPOLATE_* -\family default - These are used for the fast linear interpolation routine, you should not - change them. - -\end_layout - -\begin_layout Itemize - -\family typewriter -TABLE_* -\family default - These are the interpolation tables. - Each has to be defined because the results are cached with an integer number - as an identifier. - If you add another table remember to increment -\family typewriter -NUMBER_OF_INTERPOLATION_TABLES -\family default -. -\end_layout - -\begin_layout Itemize - -\family typewriter -RESTRICT -\family default -, -\family typewriter -FASTCALL -\family default -, -\family typewriter -CONST_FUNC -\family default - and -\family typewriter -pure_function -\family default - are used to tell the compiler if a function can use restricted memory access, - should use fastcall (something to do with registers?) or is a constant - function. - See the -\emph on -gcc -\emph default - manual for details, or just leave them. -\end_layout - -\begin_layout Itemize - -\family typewriter -FLUSH_LOG -\family default - If true then keeps the log buffer flushed, otherwise when the code crashes - (which it can!) the log is out of date. - Recommended! -\end_layout - -\begin_layout Itemize - -\family typewriter -USE_MADVISE -\family default - allows you to specify to the compiler (or the kernel running your code) - how memory is accessed. - This should speed up the code. -\end_layout - -\begin_layout Itemize - -\family typewriter -CLAET_CACHE -\family default -enables the calc_lum_and_evol_time cache (see the function for more details). - This should be used as it buys 10-15% of runtime. -\end_layout - -\begin_layout Itemize - -\family typewriter -MILLISECOND_RANDOMNESS -\family default - Improves the resolution of the random number seed. - You probably want this. -\end_layout - -\begin_layout Itemize - -\family typewriter -IDUM_COMMAND_LINE_SPECIFICATION -\family default - Allows you to specify the random number ( -\family typewriter -IDUM -\family default -) seed on the command line ( -\family typewriter ---idum xyz -\family default -) -\end_layout - -\begin_layout Itemize - -\family typewriter -SAVE_IDUM -\family default - and I -\family typewriter -DUM_LOG -\family default - log the random number which is used, just so you can check it. - ( -\family typewriter -IDUM_LOG_STREAM -\family default -sets the output stream, usually -\family typewriter -stderr -\family default -). -\end_layout - -\begin_layout Itemize - -\family typewriter -UNROLL_NUCSYN_LOOPS -\family default - allows use of the automatically generated loop unrolling as done in the - configure script (see above). - This seems to work, and is generally faster, but you should check. -\end_layout - -\begin_layout Itemize - -\family typewriter -NANCHECKS -\family default - enables checks in many parts of the code for -\family typewriter -NaN -\family default - (Not A Number). - While -\emph on -this is slow -\emph default - it is very useful for catching bugs. -\end_layout - -\begin_layout Itemize - -\family typewriter -STATIC_ARRAYS -\family default - prevents memory space which is in stardata or its child structures (star_t, - common_t, model_t, preferences_t etc) from being allocated dynamically, - i.e. - with malloc or calloc. - Instead, the space is allocated statically. - This has the advantage that the whole stardata structure can be copied - and replaced with another (for some experimental code this is -\emph on -required -\emph default -). - In later versions the dynamic allocation option may be removed (i.e. - -\family typewriter -STATIC_ARRAYS -\family default - will be standard). - I know this goes against programming ideals, in which all memory should - be dynamically allocated, but it makes life much easier. -\end_layout - -\begin_layout Itemize - -\family typewriter -CC_TIMER -\family default - does not work but perhaps you can fix it. -\end_layout - -\begin_layout Itemize - -\family typewriter -RDTSC_TIMER -\family default - uses the RDTSC timer on modern Intel (and compatible?) chips to time code - runs. - Use this instead of -\family typewriter -CC_TIMER -\family default - if you can. -\end_layout - -\begin_layout Itemize - -\family typewriter -REPEAT_RUN -\family default -allows the use of the -\family typewriter ---repeat -\emph on -<n> -\family default -\emph default - command line argument to run the code -\emph on -n -\emph default - times. - Note that timing statistics are adapted as required and a runtime -\emph on -per run -\emph default - is given (which is what you want). -\end_layout - -\begin_layout Itemize - -\family typewriter -RANDOM_SYSTEMS -\family default -is used in conjunction with -\family typewriter ---repeat -\family default -to run randomly chosen systems to check for bugs. - This is deprecated and will be removed in future. - Instead you should use the -\family typewriter -random_systems.pl -\family default - script to generate random binaries. - -\end_layout - -\begin_layout Itemize - -\family typewriter -MULTISTAR -\family default - is an experimental attempt to run many stars in parallel. - It does not work and is highly experimental. -\end_layout - -\begin_layout Subsection - -\family typewriter -binary_parameters.h -\end_layout - -\begin_layout Standard -\begin_inset CommandInset label -LatexCommand label -name "sub:binary_parameters.h" - -\end_inset - -The options in this file are non-nucleosynthesis, (single or) binary stellar - evolution options. - This file also automatically includes many header files, -\family typewriter -code_options.h -\family default - and -\family typewriter -nucsyn_parameters.h -\family default - so is very useful as a -\begin_inset Quotes eld -\end_inset - -catch-all -\begin_inset Quotes erd -\end_inset - - at the top of each source code file. - -\end_layout - -\begin_layout Itemize - -\family typewriter -AXEL -\family default - if this is defined then Axel Bonacic's changes to the code are applied - (but -\emph on -NOT necessarily -\emph default - -\family typewriter -AXEL_RGB_FIX -\family default -). - -\series bold -\emph on -WARNING! -\series default -\emph default - This is often broken and subject to development. - Axel's code is not usually that well tested\SpecialChar \ldots{} - -\end_layout - -\begin_layout Itemize - -\family typewriter -SMOOTH_AGB -\family default - enables code to smooth the HR-diagram through the transition between the - original overshooting models and Amanda's TPAGB models. - May not be reliable -- you may want to use -\family typewriter -ROBSMOOTH -\family default - instead. -\end_layout - -\begin_layout Itemize - -\family typewriter -ROBSMOOTH -\family default - does the same as -\family typewriter -SMOOTH_AGB -\family default - but is simpler and more reliable. -\end_layout - -\begin_layout Itemize - -\family typewriter -NUMBER_OF_STARS -\family default - This should always be defined as 2, it is a binary star code\SpecialChar \ldots{} - -\end_layout - -\begin_layout Itemize - -\family typewriter -PRIMARY -\family default -, -\family typewriter -SECONDARY -\family default - These are 1 and 2. -\end_layout - -\begin_layout Itemize - -\family typewriter -CFAMANDA -\family default - enables TPAGB logging so that you can compare your output to Amanda's TPAGB - models. -\end_layout - -\begin_layout Itemize - -\family typewriter -CF_LYNNETTE -\family default -enables massive-star logging so that you can compare your output to Lynnette's - models. -\end_layout - -\begin_layout Itemize - -\family typewriter -WIND_MASS_LOSS -\family default - This used to be a constant ( -\family typewriter -TRUE -\family default -) but now points to an option in the preferences struct which allows you - to turn (wind) mass-loss on and off on the command line. -\end_layout - -\begin_layout Itemize - -\family typewriter -ROTATIONALLY_ENHANCED_MASS_LOSS -\family default - If defined enables stellar-wind mass loss when stars rotate close to their - breakup velocity (see -\family typewriter -calc_stellar_wind_mass_loss.c -\family default -). -\end_layout - -\begin_layout Itemize - -\family typewriter -RETURN_ANGMOM_TO_ORBIT -\family default - returns the angular momentum from rotationally-induced winds back to the - orbit. - If this is not defined, it is just lost from the system (this is the default). -\end_layout - -\begin_layout Itemize - -\family typewriter -TIDAL_CIRCULARIZATION -\family default - This should be defined as -\family typewriter -TRUE -\family default -, if -\family typewriter -FALSE -\family default - then tides are off (does this work? perhaps it's best to set -\family typewriter -TIDAL_STRENGTH_FACTOR -\family default - to 0) -\end_layout - -\begin_layout Itemize - -\family typewriter -TIDAL_STRENGTH_FACTOR -\family default - This points to a preferences struct option so the tidal strength can be - altered on the comamnd line. -\end_layout - -\begin_layout Itemize - -\family typewriter -TIDAL_STRENGTH_FACTOR_DEFAULT -\family default - This should be -\family typewriter -1.0 -\family default -. -\end_layout - -\begin_layout Itemize - -\family typewriter -MERGER_ANGULAR_MOMENTUM_FACTOR_DEFAULT -\family default - This defines the angular momentum left in a stellar merger as a fraction - of its breakup angular momentum (assuming the angular momentum is available - from the orbit and the pre-merger stellar spins). -\end_layout - -\begin_layout Itemize - -\family typewriter -BETA -\family default - This is a mass loss factor which affects the wind velocity. - Default is -\begin_inset Formula $1/8$ -\end_inset - -. -\end_layout - -\begin_layout Itemize - -\family typewriter -XI -\family default - This is the wind accretion factor which is usually -\begin_inset Formula $1$ -\end_inset - -. -\end_layout - -\begin_layout Itemize - -\family typewriter -MIN_SEP_FOR_CLOSE_ANG_MOM_LOSS -\family default - This is the minimum separation for which close angular momentum loss algorithms - (e.g. - gravitational waves) are applied. - Default is -\begin_inset Formula $10$ -\end_inset - - ( -\begin_inset Formula $\mathrm{\,R_{\odot}}$ -\end_inset - -). -\end_layout - -\begin_layout Itemize - -\family typewriter -EPSNOV_DEFAULT -\family default - The default amount of matter accreted in a nova explosion (default -\begin_inset Formula $1/1000$ -\end_inset - -). -\end_layout - -\begin_layout Itemize - -\family typewriter -EPSNOV -\family default - points to a preferences option (see -\family typewriter -EPSNOV_DEFAULT -\family default -). -\end_layout - -\begin_layout Itemize - -\family typewriter -ACCRETION_RATE_ -\family default -\SpecialChar \ldots{} - These govern the rates at which matter can be stably accreted: important - for SN Ia production. - They point to preferences options so you can vary these limits on the command - line, but also have defaults set here as the -\family typewriter -\SpecialChar \ldots{} -_DEFAULT -\family default - macros. -\end_layout - -\begin_layout Itemize - -\family typewriter -GAMMA_DEFAULT -\family default - This governs the angular momentum loss rate for mass lost during RLOF. - (Default 0 or -1) -\end_layout - -\begin_layout Itemize - -\family typewriter -CEFLAG -\family default - A common envelope parameters, if more than zero then spin-energy corrections - are applied in the common envelope routine. - (Not tested!) -\end_layout - -\begin_layout Itemize - -\family typewriter -SN_SIGMA_DEFAULT -\family default - The SN kick velocity dispersion (Maxwellian distribution). - Default -\begin_inset Formula $190\,\mathrm{km}/\mathrm{s}$ -\end_inset - -. -\end_layout - -\begin_layout Itemize - -\family typewriter -WD_SIGMA_DEFAULT -\family default - The WD kick velocity default -- NB this is -\emph on -not -\emph default - a velocity dispersion, it is a constant value. - Default -\begin_inset Formula $0\,\mathrm{km}/\mathrm{s}$ -\end_inset - -. -\end_layout - -\begin_layout Itemize - -\family typewriter -DISTRIBUTED_SN_KICKS -\family default - This is an old option (no longer supported) which, when there is a SN, - runs the code a number (say -\begin_inset Formula $1000$ -\end_inset - -) times with different kicks. - It has not been tested for years (instead, the -\family typewriter ---repeat -\family default - option should be used -- although it is not as efficient it is at least - more reliable) -\end_layout - -\begin_layout Itemize - -\family typewriter -PTS1 -\family default -, -\family typewriter -PTS2 -\family default - and -\family typewriter -PTS3 -\family default - are timestepping options for the various evolutionary phases. - Do not touch! Defaults 0.05, 0.02 and 0.01. -\end_layout - -\begin_layout Itemize - -\family typewriter -NETA_DEFAULT -\family default - sets the default -\begin_inset Formula $\eta$ -\end_inset - - for the Reimers formula ( -\begin_inset Formula $0.5$ -\end_inset - -). - -\end_layout - -\begin_layout Itemize - -\family typewriter -NETA -\family default - points to a preferences struct option for the Reimers -\begin_inset Formula $\eta$ -\end_inset - - parameter. -\end_layout - -\begin_layout Itemize - -\family typewriter -BB_DEFAULT -\family default - The CRAP parameters (enhanced wind loss due to binaries) default -\begin_inset Formula $0$ -\end_inset - -. -\end_layout - -\begin_layout Itemize - -\family typewriter -BB -\family default - points to a preferences struct option for the CRAP parameter. -\end_layout - -\begin_layout Itemize - -\family typewriter -LUM0 -\family default -, -\family typewriter -KAP -\family default -, -\family typewriter -AHE -\family default -, -\family typewriter -ACO -\family default -, -\family typewriter -TAUMIN -\family default -, -\family typewriter -MLP -\family default -, -\family typewriter -IZETA -\family default - and -\family typewriter -ACC1 -\family default - are simply constants. -\end_layout - -\begin_layout Itemize - -\family typewriter -ACC2 -\family default - The Bondi-Hoyle wind accretion parameter (default -\begin_inset Formula $3/2$ -\end_inset - -) points to -\family typewriter -preferences -\family default -. -\end_layout - -\begin_layout Itemize - -\family typewriter -ACC2_DEFAULT -\family default - The default value of ACC2 -\end_layout - -\begin_layout Itemize - -\family typewriter -DTFAC -\family default - and -\family typewriter -DTFAC_DEFAULT -\family default - This multiplies the timestep during the TPAGB phase (if NUCSYN is defined, - usually -\begin_inset Formula $1$ -\end_inset - -). -\end_layout - -\begin_layout Itemize - -\family typewriter -HBBTFAC -\family default -and -\family typewriter - HBBTFAC_DEFAULT -\family default - This multiplies the temperature during HBB on the TPAGB ( -\begin_inset Formula $1$ -\end_inset - -). -\end_layout - -\begin_layout Itemize - -\family typewriter -EDDFAC_DEFAULT -\family default - The Eddington limit for accretion is multiplied by this, which implies - that the default ( -\begin_inset Formula $10^{6}$ -\end_inset - -) means there is effectively no Eddington limit. -\end_layout - -\begin_layout Itemize - -\family typewriter -MAXIMUM_STELLAR_MASS -\family default - This is the maximum stellar mass the code can handle ( -\begin_inset Formula $100\mathrm{\,M_{\odot}}$ -\end_inset - -). - If -\family typewriter -TRIM_SUPERMASSIVE_STARS -\family default - is defined then stars of more than -\family typewriter -MAXIMUM_STELLAR_MASS -\family default - are trimmed down (the excess material -\emph on -is -\emph default - counted as stellar yield, so think of this as a -\emph on -very -\emph default - strong mass loss). -\end_layout - -\begin_layout Itemize - -\family typewriter -MINIMUM_STELLAR_MASS -\family default - is used to prevent the fitting formulae from giving spurious results if - the mass fed into them is too small. -\end_layout - -\begin_layout Itemize - -\family typewriter -TIMESTEP_MODULATION -\family default - if defined allows the timestep to be modulated by a number given in -\family typewriter -preferences->timestep_modulator -\end_layout - -\begin_layout Itemize - -\family typewriter -DEFAULT_LAMBDA_CE -\family default - This is the default value of the common envelope parameter -\begin_inset Formula $\lambda$ -\end_inset - -. - If it is -\begin_inset Formula $-1$ -\end_inset - - then -\begin_inset Formula $\lambda$ -\end_inset - - is calculated from fits to real stellar models according to -\begin_inset CommandInset citation -LatexCommand citet -key "2000A&A...360.1043D" - -\end_inset - -. - If it is -\begin_inset Formula $>0$ -\end_inset - - then it is used directly. -\end_layout - -\begin_layout Itemize - -\family typewriter -DEFAULT_LAMBDA_IONISATION -\family default - If -\begin_inset Formula $>0$ -\end_inset - - then energy from ionization is used to help eject the envelope. -\end_layout - -\begin_layout Itemize - -\family typewriter -DEFAULT_COMENV_PRESCRIPTION -\family default - can be -\family typewriter -COMENV_HURLEY -\family default - or -\family typewriter -COMENV_NELEMANS -\family default -, which means you use either the -\begin_inset CommandInset citation -LatexCommand citet -after "$\\alpha$" -key "2002MNRAS_329_897H" - -\end_inset - - or the -\begin_inset CommandInset citation -LatexCommand citet -after "$\\gamma$" -key "2001A&A...365..491N" - -\end_inset - - prescription. -\end_layout - -\begin_layout Itemize - -\family typewriter -DEFAULT_NELEMANS_GAMMA -\family default - is the default value of -\begin_inset Formula $\gamma$ -\end_inset - - in the case that you use the -\begin_inset CommandInset citation -LatexCommand citet -after "$\\gamma$" -key "2001A&A...365..491N" - -\end_inset - - prescription (i.e. - -\family typewriter -COMENV_NELEMANS -\family default -) -\end_layout - -\begin_layout Itemize -There are some other parameters associated with the Nelemans mechanism ( -\family typewriter -NELEMANS_* -\family default -), but these are not standard so if you want to use them please consult - the code directly. -\end_layout - -\begin_layout Itemize - -\family typewriter -DEFAULT_ALPHA1 -\family default - This is the -\begin_inset Formula $\alpha$ -\end_inset - - parameter used in the -\begin_inset CommandInset citation -LatexCommand citet -key "2002MNRAS_329_897H" - -\end_inset - - prescription of common envelope evolution ( -\begin_inset Formula $1$ -\end_inset - - or -\begin_inset Formula $3$ -\end_inset - -). -\end_layout - -\begin_layout Itemize - -\family typewriter -CE_DURATION_DEFAULT -\family default - defines the time which is spent in common envelope evolution. - This is not used at present. -\end_layout - -\begin_layout Itemize - -\family typewriter -NO_MERGER_NUCLEOSYNTHESIS -\family default - prevents the -\begin_inset CommandInset citation -LatexCommand citet -key "2002MNRAS_329_897H" - -\end_inset - - algorithm which ignites degenerate cores when they merge. - This does not mean a SN will not occur when appropriate, but it does mean - that helium white dwarf mergers do not explode. -\end_layout - -\begin_layout Itemize - -\family typewriter -HeWD_HeCORE_MERGER_IGNITION -\family default - if defined allows stars which have degenerate He cores and then merge to - ignore. - This is probably nonsense, so you should -\emph on -not -\emph default - enable this option. -\end_layout - -\begin_layout Itemize - -\family typewriter -HeWD_HeWD_IGNITION_MASS -\family default - is -\begin_inset Formula $0.3\,\mathrm{M}_{\odot}$ -\end_inset - - and is the mass at which an accreting helium white dwarf reignites helium - and turns into a helium star. - This number will, in reality, depend on the accretion rate, composition - etc. - and is something that could be worked on. -\end_layout - -\begin_layout Itemize - -\family typewriter -ALLOW_HeWD_SUPERNOVAE -\family default - if defined allows HeIa supernovae for HeWDs above -\begin_inset Formula $0.7\,\mathrm{M}_{\odot}$ -\end_inset - -. - It is -\emph on -not -\emph default - defined by default (see above for reasoning). -\end_layout - -\begin_layout Itemize - -\family typewriter -COMENV_NS_ACCRETION -\family default - is used to accrete material onto neutron stars inside common envelopes. - You can either accrete a fraction of the envelope (through -\family typewriter -COMENV_NS_ACCRETION_FRACTION_DEFAULT -\family default -) or a fixed mass ( -\family typewriter -COMENV_NS_ACCRETION_MASS_DEFAULT -\family default -). - Both are -\begin_inset Formula $0$ -\end_inset - - by default (i.e. - nothing happens) and -\family typewriter -COMENV_NS_ACCRETION -\family default - is not defined by default. -\end_layout - -\begin_layout Itemize - -\family typewriter -COMENV_MS_ACCRETION -\family default - is used to accrete material onto main sequence (and other?) stars during - a common envelope phase, the amount accreted is -\family typewriter -COMENV_MS_ACCRETION_MASS_DEFAULT -\family default - ( -\begin_inset Formula $0.01$ -\end_inset - - by default, but -\family typewriter -COMENV_MS_ACCRETION -\family default - is not usually defined so this does not happen). - NOTE at present this seems a little buggy\SpecialChar \ldots{} - -\end_layout - -\begin_layout Itemize - -\family typewriter -CHANDRASEKHAR_MASS -\family default - is the Chandrasekhar mass, -\begin_inset Formula $M_{\mathrm{Ch}}=1.44\mathrm{\,M_{\odot}}$ -\end_inset - -. -\end_layout - -\begin_layout Itemize - -\family typewriter -MAX_NEUTRON_STAR_MASS -\family default - If a compact remnant has a mass greater than this, it is turned into a - black hole (default -\begin_inset Formula $1.8\mathrm{\,M_{\odot}}$ -\end_inset - -). -\end_layout - -\begin_layout Itemize - -\family typewriter -MINIMUM_MASS_FOR_CARBON_IGNITION -\family default - If a helium core (during CHeB or the EAGB before second dredge up) has - more than this mass then it goes on to ignite carbon ( -\begin_inset Formula $1.6\mathrm{\,M_{\odot}}$ -\end_inset - -). -\end_layout - -\begin_layout Itemize - -\family typewriter -MAX_TPAGB_CORE_MASS -\family default - The maximum core mass of a TPAGB star (which will have an ONeMg -- or, - in rare circumstances -- a CO core) before it collapses to a NS. - This is -\begin_inset Formula $1.44\mathrm{\,M_{\odot}}=M_{\mathrm{Ch}}$ -\end_inset - - or perhaps -\begin_inset Formula $1.38\mathrm{\,M_{\odot}}$ -\end_inset - - (taking into account the composition). -\end_layout - -\begin_layout Itemize - -\family typewriter -MAX_CONVECTIVE_MASS -\family default - and -\family typewriter -MIN_CONVECTIVE_MASS -\family default -: if a star is in this mass range and is a main sequence star it is defined - as -\begin_inset Quotes eld -\end_inset - -convective -\begin_inset Quotes erd -\end_inset - -. -\end_layout - -\begin_layout Itemize - -\family typewriter -MASS_ACCRETION_FOR_ELD_DEFAULT -\family default - This is the amount of mass accreted to make an Edge Lit Detonation (which - might be SNIa) default is -\begin_inset Formula $0.15\mathrm{\,M_{\odot}}$ -\end_inset - - -\end_layout - -\begin_layout Itemize - -\family typewriter -GIANT_AGE_FATAL_ERRORS -\family default - Occasionally this function spits out an error: if this is defined then - the error stops the code (default: no, go with it) -\end_layout - -\begin_layout Itemize - -\family typewriter -ACQUIRE_FUDGE_NEGATIVE_AGES -\family default - Sometimes the age can be negative. - This allows it to be set to zero if it is small, in which case we assume - it's because Rob has broken something or there is a small numerical error. - (Defined by default but note that -\emph on -FUDGE -\emph default - is a correct description!) -\end_layout - -\begin_layout Itemize - -\family typewriter -ACQUIRE_TEST_FOR_NEGATIVE_AGES -\family default - If enabled causes the code to stop when the age is very negative. - (Default off) -\end_layout - -\begin_layout Itemize - -\family typewriter -MINIMUM_TIMESTEP_DEFAULT -\family default -This sets the minimum timestep (in Myr, although this can be overwritten - by command line options) -\end_layout - -\begin_layout Itemize - -\family typewriter -MINIMUM_TIMESTEP_DEFAULT -\family default - The minimum timestep ( -\begin_inset Formula $1000\,\mathrm{Myr}$ -\end_inset - -). -\end_layout - -\begin_layout Itemize - -\family typewriter -HACHISU_DISK_WIND -\family default - If defined then the disk wind of -\begin_inset CommandInset citation -LatexCommand citet -key "1996ApJ...470L..97H" - -\end_inset - - is used, with a rate limit given by -\family typewriter -ACCRETION_RATE_LIMIT_HACHISU -\family default -. - The wind is mulitplied by -\family typewriter -HACHISU_DISK_WIND_FACTOR_DEFAULT -\family default - (default -\begin_inset Formula $10^{20}$ -\end_inset - -) which when set very high (like the default) has no effect. - This code has not been well tested. -\end_layout - -\begin_layout Itemize - -\family typewriter -BINARY_STARS_ONLY -\family default - When defined the evolution code does not evolve through phases involving - just one star. -\end_layout - -\begin_layout Itemize - -\family typewriter -NUCSYN -\family default - When defined then the nucleosynthesis code is built (and nucsyn/nucsyn_paramete -rs.h is included, see -\begin_inset CommandInset ref -LatexCommand ref -reference "sub:nucsyn/nucsyn_parameters.h" - -\end_inset - -). - When not defined you are just building my C version of BSE. -\end_layout - -\begin_layout Itemize - -\family typewriter -ANG_MOM_CHECKS -\family default - is used to log angular momenta just prior to a SN. -\end_layout - -\begin_layout Itemize - -\family typewriter -DELIBERATE_BUG1 -\family default - enables a bug which you don't want enabled. -\end_layout - -\begin_layout Itemize - -\family typewriter -BINARY_COLOURS -\family default - builds some code which includes UBV colour calculations based on Kurucz - atmospheres (thanks to Jarrod). -\end_layout - -\begin_layout Itemize - -\family typewriter -NO_IMMEDIATE_MERGERS -\family default - if defined does not allow early MS-MS mergers to evolve (do these systems - ever exist?). -\end_layout - -\begin_layout Itemize - -\family typewriter -CGI_EXTENSIONS -\family default - builds code suitable for the website -\begin_inset Flex URL -status collapsed - -\begin_layout Plain Layout - -http://www.phys.uu.nl/~izzard/cgi-bin/binary2.cgi -\end_layout - -\end_inset - -. -\end_layout - -\begin_layout Itemize - -\family typewriter -SDB_CHECKS -\family default - logs information on subdwarf-B stars. -\end_layout - -\begin_layout Itemize - -\family typewriter -BI_LYN -\family default - logs information on BI Lyn stars (what are they???). -\end_layout - -\begin_layout Itemize - -\family typewriter -XRAY_BINARIES -\family default - logs information on X-ray binaries, specifically their luminosities. -\end_layout - -\begin_layout Itemize - -\family typewriter -STELLAR_TYPE_LOG -\family default - logs stellar type information. -\end_layout - -\begin_layout Itemize - -\family typewriter -LOG_JJE -\family default - is the log for John Eldridge, -\family typewriter -LTEST -\family default - is related to this, -\family typewriter -JJE_FUDGES -\family default - fudges parts of the code to behave more like John's. -\end_layout - -\begin_layout Itemize - -\family typewriter -NUCSYN_LOG_JL -\family default - is for some abundance logging (for John Lattanzio) \SpecialChar \ldots{} -I can't remember what. -\end_layout - -\begin_layout Itemize - -\family typewriter -SELMA -\family default - enables some logging for Selma which she ended up not using. - Typical! -\end_layout - -\begin_layout Itemize - -\family typewriter -SELMA_MASS_EJECTA -\family default -, -\family typewriter -SELMA_MASS_EJECTA_N -\family default -, -\family typewriter -SELMA_DM_MASS_RESOLUTION -\family default - enable some logging for Selma. -\end_layout - -\begin_layout Itemize - -\family typewriter -LOG_CE_PARAMETERS -\family default - Logs stuff fromt he common-envelope phase to the c_log file. -\end_layout - -\begin_layout Itemize - -\family typewriter -FORM_STARS_AT_BREAKUP_ROTATION -\family default - If this is defined then the initial rotation rate of the stars is as high - as it can be before they break up. -\end_layout - -\begin_layout Itemize - -\family typewriter -FILE_LOG -\family default - logs output to a file, usually /tmp/c_log.dat (but this can be defined on - the command line). - You want this to be defined (it is by default). -\end_layout - -\begin_layout Itemize - -\family typewriter -AXEL_RGB_FIX -\family default - fixes a bug in the giant branch radius function, you want this to be defined. -\end_layout - -\begin_layout Itemize - -\family typewriter -NS_BH_AIC_LOG -\family default - logs when neutron stars turn into black holes, for Enrico. -\end_layout - -\begin_layout Itemize - -\family typewriter -NELEMANS_MASS_PLOT -\family default - was an attempt to reproduce some of Gijs' work (which was quite successful). -\end_layout - -\begin_layout Itemize - -\family typewriter -DETMERS_LOG -\family default - outputs information for Rob Detmers' upcoming paper (which will be finished - one day). -\end_layout - -\begin_layout Itemize - -\family typewriter -LOG_TO_STDOUT -\family default - and -\family typewriter -LOG_TO_STDERR -\family default - allow the standard log to be sent to stdout or stderr without the need - to do this manually each time. -\end_layout - -\begin_layout Itemize - -\family typewriter -NO_UNEXPECTED_MASS_CHANGES -\family default - removes the mass changes which occur in hrdiag, which are otherwise quite - bad as that's not what hrdiag is supposed to do! -\end_layout - -\begin_layout Itemize - -\family typewriter -RSTARS -\family default - if defined activates the following flags, which were used to make the R - stars paper -\begin_inset CommandInset citation -LatexCommand citet -key "2007A&A...470..661I" - -\end_inset - -, namely the following: -\end_layout - -\begin_deeper -\begin_layout Itemize - -\family typewriter -NO_MERGER_NUCLEOSYNTHESIS -\family default - Stops ignition of helium cores when they merge ( -\begin_inset CommandInset citation -LatexCommand citealp -key "2002MNRAS_329_897H" - -\end_inset - - did this but I do not believe it is correct) -\end_layout - -\begin_layout Itemize - -\family typewriter -HeWD_HeCORE_MERGER_IGNITION -\family default - Forces HeWD+GB to form a new GB star, and HeWD+CHeB to form a new CHeB - star (a little thought tells you that the latter cannot happen) -\end_layout - -\begin_layout Itemize - -\family typewriter -LOG_COMENV_RSTARS -\family default - Logs R star mergers resulting from common envelope evolution -\end_layout - -\begin_layout Itemize - -\family typewriter -LOG_RSTARS -\family default - Logs R stars during the CHeB stage -\end_layout - -\begin_layout Itemize - -\family typewriter -NUCSYN_LOW_MASS_STRIPPING -\family default - Follow surface abundance changes in low mass stars due to mass stripping - during the MS (i.e. - nitrogen enhancement, carbon depletion) This -\emph on -only works for star 1 -\emph default -. -\end_layout - -\begin_layout Itemize - -\family typewriter -SMALL_GB_CORES -\family default - This forces the cores in GB stars to be the same as the equivalent mass - WD rather than the -\begin_inset Formula $5\times$ -\end_inset - - -\begin_inset Quotes eld -\end_inset - -hot subdwarf -\begin_inset Quotes erd -\end_inset - - which was made up by Chris Tout. -\end_layout - -\begin_layout Itemize - -\family typewriter -CONSERVE_ANGMOM_IN_COMENV -\family default - Conserves angular momentum in the common envelope merged core. -\end_layout - -\end_deeper -\begin_layout Itemize - -\family typewriter -HRDIAG -\family default - When defined HR-diagram information is output (can be useful). -\end_layout - -\begin_layout Itemize - -\family typewriter -INITIAL_FINAL_MASS_RELATION -\family default - outputs information about initial/final masses. -\end_layout - -\begin_layout Itemize - -\family typewriter -DTR_FUDGES -\family default - enables some timestep function (see deltat.c) fudges to stop the code grinding - to a halt when it shouldn't. -\end_layout - -\begin_layout Itemize - -\family typewriter -COMPARE_FORTRAN -\family default - enables some logging so I can compare my FORTRAN version of BSE to the - C version. -\end_layout - -\begin_layout Itemize -The three defines -\family typewriter -GIANT_CRITICAL_Q_ORIGINAL -\family default -, -\family typewriter -GIANT_CRITICAL_Q_HJELLMING_WEBBINK -\family default - and -\family typewriter -GIANT_CRITICAL_Q_NO_COMENV -\family default - refer to the prescription used for the critical -\begin_inset Formula $q=M_{1}/M_{2}$ -\end_inset - - which determines the stability of mass transfer from a giant. - The original is as -\begin_inset CommandInset citation -LatexCommand citet -key "2002MNRAS_329_897H" - -\end_inset - -. -\end_layout - -\begin_layout Itemize -White dwarf cooling rates are defined by -\family typewriter -MESTEL_COOLING -\family default - or -\family typewriter -MODIFIED_MESTEL_COOLING -\family default -, the former was originally used in -\begin_inset CommandInset citation -LatexCommand citet -key "2002MNRAS_329_897H" - -\end_inset - -. -\end_layout - -\begin_layout Itemize - -\family typewriter -EXTRA_IA_LOGGING -\family default - enables SNIa logging. -\end_layout - -\begin_layout Itemize - -\family typewriter -COMENV_CO_MERGER_GIVES_IIa -\family default - forces CO-CO mergers inside common envelopes to log as SNeIa. - Are they? -\end_layout - -\begin_layout Itemize -When HeWDs accrete hydrogen, what happens? Novae? If so, then we wait until - -\family typewriter -He_REIGNITION_LAYER_THICKNESS -\family default - accretes (guessed at -\begin_inset Formula $0.01\mathrm{\,M_{\odot}}$ -\end_inset - - although the exact number may not matter too much) and form a helium star. - To disable this enable -\family typewriter -NO_HeWD_NOVAE -\family default -. -\end_layout - -\begin_layout Itemize - -\family typewriter -STARDATA_STATUS -\family default - outputs some status information regarding the stardata struct. - Quite what I am not sure\SpecialChar \ldots{} - and it doesn't seem to do anything at the moment. -\end_layout - -\begin_layout Itemize - -\family typewriter -TPAGB_SPEEDUP -\family default - activates an algorithm for speeding up TPAGB evolution after it becomes - -\begin_inset Quotes eld -\end_inset - -asymptotic -\begin_inset Quotes erd -\end_inset - -, i.e. - after -\family typewriter -TPAGB_SPEEDUP_AFTER -\family default - pulses. - This is useful, but of course reduces time resolution so be careful when - using it (default is on). - -\end_layout - -\begin_layout Itemize - -\family typewriter -VW93_MIRA_SHIFT -\family default - and -\family typewriter -VW93_MULTIPLIER -\family default - allow fudge factors in the VW93 mass-loss formula. -\end_layout - -\begin_layout Itemize - -\family typewriter -STEP_BACK_RLOF -\family default - is a better attempt at dealing with the transition into RLOF, but was never - finished (should not be on!) -\end_layout - -\begin_layout Itemize - -\family typewriter -PATHOLOGICAL_RLOF_CHECK -\family default - checks if the star expands when it should shrink in the RLOF interpolation - steps. -\end_layout - -\begin_layout Itemize - -\family typewriter -SLOW_DOWN_PREROCHE_EAGB -\family default - and -\family typewriter -SLOW_DOWN_PREROCHE_TPAGB -\family default - force the timestep to be reduced when the star is an EAGB or TPAGB star - respectively and approaches RLOF (i.e -\begin_inset Formula $R/R_{\mathrm{L}}\rightarrow1$ -\end_inset - -. -\end_layout - -\begin_layout Itemize - -\family typewriter -MANUAL_VROT -\family default - allows you to specify the spin of the stars on the command line. -\end_layout - -\begin_layout Itemize - -\family typewriter -VROT_LOGGING -\family default - enables the log output for Norbert Langer. - This is every -\family typewriter -VROT_LOGGING_DT -\family default - Myr. -\end_layout - -\begin_layout Itemize - -\family typewriter -STOP_ACCRETION_OF_MATERIAL_BEYOND_BREAKUP -\family default - enables the lines of code which Jarrod put in the code to prevent accretion - of material beyond the breakup velocity. -\end_layout - -\begin_layout Itemize - -\family typewriter -ZAMS_MENV_METALLICITY_CORRECTION -\family default - enables new fits to the convective envelope mass based on a model grid - from Evert Glebbeek. - This is valid for -\begin_inset Formula $Z=10^{-4}$ -\end_inset - - to -\begin_inset Formula $Z=0.02$ -\end_inset - - which is an improvement on the old version which only worked for -\begin_inset Formula $Z=0.02$ -\end_inset - -. -\end_layout - -\begin_layout Itemize - -\family typewriter -RLOF_RADIATION_CORRECTION -\family default - is an experiment to allow radiation effects to affect the size of the Roche - lobe (default off, the code requires an update with the latest fitting - formula). -\end_layout - -\begin_layout Itemize - -\family typewriter -RLOF_MDOT_MODULATION -\family default - if defines allows modulation of the (non-dynamical) RLOF mass-transfer - rate -\end_layout - -\begin_layout Itemize - -\family typewriter -RLOF_LIMIT_ALL_STARS_TO_THERMAL_RATE -\family default - forces all (non-dynamical) RLOF mass transfer rates to be limited by the - KH timescale (in the old code it was just giants) -\end_layout - -\begin_layout Itemize - -\family typewriter -CALCULATE_EXTRA_ROTATION_VARIABLES -\family default - Enables the calculation of extra variables related to rotation -- often - required by logging routines and adaptive Roche-lobe overflow, etc. -\end_layout - -\begin_layout Itemize - -\family typewriter -ADAPTIVE_RLOF -\family default - enables the new RLOF code which attempts to judge the mass transfer rate - based on an iterative procedure which forces the star to remain inside - its Roche lobe. -\end_layout - -\begin_layout Itemize - -\family typewriter -ADAPTIVE_RLOF_CONVECTIVE_CHECK -\family default - enables code which shortcuts the adaptive iterative procedure for stars - with giant envelopes. - These would just attempt to lose all their envelopes anyway (in which case - the thermal limit caps the transfer rate). -\end_layout - -\begin_layout Itemize - -\family typewriter -ADAPTIVE_RLOF_LOG -\family default - enables some logging of RLOF information. -\end_layout - -\begin_layout Itemize - -\family typewriter -LIMIT_RLOF_ACCRETION_TO_THERMAL_RATE -\family default - If defined, limits accretion on the secondary to the thermal rate of the - secondary. -\end_layout - -\begin_layout Itemize - -\family typewriter -RLOF_OVERFLOW_THRESHOLD(2) -\family default -, -\family typewriter -ADAPTIVE_RLOF_THRESHOLD -\family default - and -\family typewriter -RLOF_STABILITY_FACTOR -\family default - are numerical factors which affect the RLOF routines. - -\end_layout - -\begin_layout Itemize - -\family typewriter -ADAPTIVE_RLOF_IMIN -\family default - and -\family typewriter -ADAPTIVE_RLOF_IMAX -\family default - are the minimum and maximum number of iterations the adaptive RLOF code - may perform. -\end_layout - -\begin_layout Itemize - -\family typewriter -ADAPTIVE_RLOF_MINIMUM_RADIUS_ERROR -\family default - If the radius error ( -\begin_inset Formula $(R-R_{\mathrm{L}})/R_{\mathrm{L}})$ -\end_inset - - is less than this, stop the iterations to avoid a -\begin_inset Formula $0/0$ -\end_inset - -. -\end_layout - -\begin_layout Itemize - -\family typewriter -ADAPTIVE_RLOF_DM_MAX -\family default - An expression which gives the maximyum change in the mass in one iteration. -\end_layout - -\begin_layout Itemize - -\family typewriter -ADAPTIVE_RLOF_MAX_ENV_FRAC -\family default - An expression which limits the mass transfer rate such that it is the maximum - fraction of the envelope mass that can be transferred in a timestep. -\end_layout - -\begin_layout Itemize - -\family typewriter -ADAPTIVE_RLOF_ALPHA -\family default - A fudge factor, -\begin_inset Formula $<1$ -\end_inset - -, which is used in the calculation of -\begin_inset Formula $\partial R/\partial M$ -\end_inset - -. -\end_layout - -\begin_layout Itemize - -\family typewriter -MAX_NUM_RLOFS -\family default - is the maximum number of RLOF events a system may experience. - If zero (the default) then it is not used and the system can have as many - RLOFs as it likes. -\end_layout - -\begin_layout Itemize - -\family typewriter -RLOF_NO_TRANSFER_LIMITS -\family default - prevents the thermal limits (etc) on mass-transfer rates. - This is not realistic but is useful for forcing the system to be conservative. -\end_layout - -\begin_layout Itemize - -\family typewriter -RLOF_MINIMUM_SPEEDUP_FACTOR -\family default - is used as a minimum for the -\begin_inset Formula $k_{w}$ -\end_inset - - (number of orbits per timestep) factor. - Whenever I have used it I have found a pathological case which breaks, - so you should not defined it. -\end_layout - -\begin_layout Itemize - -\family typewriter -RLOF_REDUCE_TIMESTEP -\family default - (and -\family typewriter -RLOF_REDUCE_TIMESTEP_AGGRESSION -\family default -, -\family typewriter -RLOF_REDUCE_TIMESTEP_MINIMUM_FACTOR -\family default -, -\family typewriter -RLOF_REDUCE_TIMESTEP_THRESHOLD -\family default -) is used to reduce the timestep during RLOF (controlled by the other parameters -). - It can result in a very small timestep, but is useful for testing. -\end_layout - -\begin_layout Itemize - -\family typewriter -RLOF_MINIMUM_TIMESTEP -\family default - The minimum timestep during RLOF (in Myr) -- may be removed in the near - future. -\end_layout - -\begin_layout Itemize - -\family typewriter -RLOF_NO_STELLAR_TYPE_CHANGE_IF_DTM_NEGATIVE -\family default - If enabled do not let the stellar type go backwards during RLOF (could - cause problems? or perhaps solve them\SpecialChar \ldots{} -) -\end_layout - -\begin_layout Itemize - -\family typewriter -CONSERVE_ANGULAR_MOMENTUM_DURING_MERGERS -\family default - Is supposed to conserve angular momentum during a stellar merger -- however - Selma suggests it may not work quite as planned. -\end_layout - -\begin_layout Itemize - -\family typewriter -CONSERVATIVE_SYSTEM -\family default - if defined then checks are compiled in which check if the system is conservativ -e, and if not an error is logged and the code exits. - Useful with -\family typewriter -RLOF_NO_TRANSFER_LIMITS -\family default - but otherwise do not use it. -\end_layout - -\begin_layout Itemize - -\family typewriter -SINGLE_STAR_LIFETIMES -\family default - If defined outputs the lifetime of a single star with the given mass -- - used for the time-adaptive mass grid. -\end_layout - -\begin_layout Itemize - -\family typewriter -CIRCUMBINARY_DISK -\family default - Experimental circumbinary-disk routines -- ask Tyl Dermine about it. -\end_layout - -\begin_layout Itemize - -\family typewriter -ECCENTRIC_CRAP -\family default - Experimental code -- may be removed because I cannot remember what it does! -\end_layout - -\begin_layout Itemize - -\family typewriter -COMENV_LOG -\family default - logs post-common envelope information -\end_layout - -\begin_layout Itemize - -\family typewriter -SELMA_MASS_EJECTA -\family default -, -\family typewriter -SELMA_DM_MASS_EJECTA_N -\family default - and -\family typewriter -SELMA_DM_MASS_RESOLUTION -\family default - are for Selma -\end_layout - -\begin_layout Itemize - -\family typewriter -FABIAN_IMF_LOG -\family default - is Fabian Schneider's single/binary star initial mass function log -\end_layout - -\begin_layout Itemize - -\family typewriter -STARSEARCH -\family default - is a general logging device for outputting stellar information when stellar - variables change by prescribed amounts. - See the comments in -\family typewriter -binary_parameters.h -\family default - for more information. -\end_layout - -\begin_layout Itemize - -\family typewriter -POST_CE_OBJECTS_HAVE_ENVELOPES -\family default - (and associated options) allow stars exiting the common-envelope phase - to keep their envelopes (e.g. - an AGB star which has its envelope stripped remains an AGB star). - The envelope mass is fixed according to the stellar type by -\family typewriter -POST_CE_ENVELOPE_DM_GB -\family default -, -\family typewriter -POST_CE_ENVELOPE_DM_EAGB -\family default - and -\family typewriter -POST_CE_ENVELOPE_DM_TPAGB -\family default -. -\end_layout - -\begin_layout Itemize - -\family typewriter -POST_CE_ADAPTIVE_MENV -\family default - is an improvement on the previous option. - When the common-envelope phase terminates, the star is left with the envelope - mass appropriate to being just inside its Roche lobe. - -\end_layout - -\begin_layout Itemize - -\family typewriter -PN_FAST_WIND -\family default - When the stellar envelope mass is less than a given amount ( -\family typewriter -PN_FAST_WIND_DM_GB -\family default - for first GB stars, -\family typewriter -PN_FAST_WIND_DM_AGB -\family default - for AGB stars) the standard stellar wind is switched off and a fast wind - at a fixed rate ( -\family typewriter -PN_FAST_WIND_MDOT_GB -\family default - and -\family typewriter -PN_FAST_WIND_MDOT_AGB -\family default -) is used instead. -\end_layout - -\begin_layout Itemize - -\family typewriter -RESOLVE_PN_FAST_WIND -\family default - decreases the stellar timestep (in deltat.c) in order to better resolve - (in time) the PN wind. - A star is defined as a planetary nebula if its luminosity exceeds -\family typewriter -PN_MIN_L -\family default - and its temperature exceeds -\family typewriter -PN_MIN_TEFF -\family default -. - This is only activated if the stellar envelope has a mass less than -\family typewriter -RESOLVE_PN_FAST_WIND_MAX_MENV -\family default -. -\end_layout - -\begin_layout Itemize - -\family typewriter -PN_PROJECT -\family default - is a catchall for Rob's PN+nucleosynthesis project. -\end_layout - -\begin_layout Itemize - -\family typewriter -WRLOF_MASS_TRANSFER -\family default - is Carlo Abate's wind-RLOF prescription (see Abate et al 2013, MNRAS accepted). -\end_layout - -\begin_layout Subsection - -\family typewriter -nucsyn/nucsyn_parameters.h -\end_layout - -\begin_layout Standard -\begin_inset CommandInset label -LatexCommand label -name "sub:nucsyn/nucsyn_parameters.h" - -\end_inset - -While many important options are set on the command line the options governing - which nucleosynthesis algorithms to use and what to output are set in the - file -\family typewriter -nucsyn/nucsyn_parameters.h -\family default -. - More detailed descriptions of the variables used in the code are given - in section -\begin_inset CommandInset ref -LatexCommand ref -reference "sec:Hacker-Guide" - -\end_inset - -. -\end_layout - -\begin_layout Itemize -Enable -\family typewriter -NUCSYN_FIRST_DREDGE_UP -\family default - to make first dredge-up happen on the GB. - -\end_layout - -\begin_deeper -\begin_layout Itemize -You want this, and probably you want to enable -\family typewriter -NUCSYN_FIRST_DREDGE_UP_AMANDAS_TABLE -\family default - and -\family typewriter -NUCSYN_FIRST_DREDGE_UP_ACCRETION_CORRECTION -\family default -. - These enable tabular lookups of the abundance changes (better than fitting - formulae) and a simple prescription to deal with abundance changes due - to accretion. -\end_layout - -\begin_layout Itemize - -\family typewriter -NUCSYN_FIRST_DREDGE_UP_ACCRETION_CORRECTION_FROM_TAMS -\family default - is similar but bases changes on the -\emph on -terminal-age main sequence -\emph default - abundances -- this is better in the case of accretion of e.g. - carbon (i.e. - for CEMPs). - -\end_layout - -\begin_layout Itemize - -\family typewriter -NUCSYN_FIRST_DREDGE_UP_PHASE_IN -\family default - enables a phased change of the abundance to better match detailed models - (the default model assumes that 1st DUP happens instantaneously). - -\end_layout - -\begin_layout Itemize - -\family typewriter -NUCSYN_FIRST_DREDGE_UP_RICHARDS_TABLE -\family default - should be enabled in addition to -\family typewriter -NUCSYN_FIRST_DREDGE_UP_AMANDAS_TABLE -\family roman - to use Richard Stancliffe's models in place of Amanda's when in the appropriate - mass/metallicity range (down to -\begin_inset Formula $Z=10^{-5}$ -\end_inset - - while Amanda's are valid only down to -\begin_inset Formula $10^{-4}$ -\end_inset - -). -\end_layout - -\end_deeper -\begin_layout Itemize -Enable -\family typewriter -NUCSYN_SECOND_DREDGE_UP -\family default - to make second dredge-up happen at the beginning of the TPAGB. - You want this. -\end_layout - -\begin_layout Itemize -Enable -\family typewriter -NUCSYN_THIRD_DREDGE_UP -\family default - to make third dredge-up happen during the TPAGB. - -\end_layout - -\begin_deeper -\begin_layout Itemize -You probably also want -\family typewriter -NUCSYN_THIRD_DREDGE_UP_AMANDA -\family default - to get the intershell abundances from a table based on Amanda's models. -\end_layout - -\begin_layout Itemize -You can choose whether to get these numbers from either the old data -\family typewriter -USE_TABULAR_INTERSHELL_ABUNDANCES_KARAKAS_2002 -\family default - (no s-process; use only for testing!) or the new table -\family typewriter -USE_TABULAR_INTERSHELL_ABUNDANCES_KARAKAS_2012 -\family default - (with s-process, deprecates the Busso/Gallino tables which have been removed). -\end_layout - -\begin_layout Itemize - -\family typewriter -MINIMUM_ENVELOPE_MASS_FOR_THIRD_DREDGEUP -\family default - is the minimum mass for third dredge up, set on the command line with -\family typewriter ---minimum_envelope_mass_for_third_dredgeup -\family default - or -\family typewriter -MINIMUM_ENVELOPE_MASS_FOR_THIRD_DREDGEUP_DEFAULT -\family default - by default ( -\begin_inset Formula $0.5\mathrm{\,M_{\odot}}$ -\end_inset - - based on Straniero's models). -\end_layout - -\begin_layout Itemize -You have the option of defining -\family typewriter -NUCSYN_THIRD_DREDGE_UP_RICHARD -\family default - instead, which uses Richard's intershell material (but is less complete - than Amanda's tables). -\end_layout - -\begin_layout Itemize - -\family typewriter -NUCSYN_THIRD_DREDGE_UP_TABULAR_NCAL -\family default - should be used for tabular fits to the NCAL parameter instead of the old - (dodgy?) formula fit. -\end_layout - -\begin_layout Itemize - -\family typewriter -NUCSYN_THIRD_DREDGE_UP_HYDROGEN_SHELL -\family default - activates the algorithm which takes into account dredge up of the hydrogen-burn -ing shell at low metallicity. - At high metallicity it is negligible. - You should activate this. -\end_layout - -\begin_layout Itemize - -\family typewriter -NUCSYN_THIRD_DREDGE_UP_MULTIPLIERS -\family default - allows command-line modification of the amount of material dredge up. - It does not hurt to define this if you do not use it. -\end_layout - -\begin_layout Itemize - -\family typewriter -USE_TABULAR_INTERSHELL_ABUNDANCES -\family default - forces the use of tables instead of fits to the intershell abundances: - this is probably what you want (there are checks for going off the end - of the tables). -\end_layout - -\end_deeper -\begin_layout Itemize -Enable -\family typewriter -PADOVA_MC1TP -\family default - to use the Padova group's -\begin_inset Formula $M_{\textrm{c}}^{\textrm{1TP}}$ -\end_inset - - rather than the -\begin_inset CommandInset citation -LatexCommand citet -key "Parameterising_3DUP_Karakas_Lattanzio_Pols" - -\end_inset - - fits (only for -\begin_inset Formula $M<3\,\textrm{M}_{\odot}$ -\end_inset - -, above -\begin_inset Formula $3\,\textrm{M}_{\odot}$ -\end_inset - - the difference is small anyway). -\end_layout - -\begin_layout Itemize -Enable -\family typewriter -NUCSYN_TPAGB -\family default - if you want to use nucleosynthesis on the TPAGB (e.g. - third dredge-up and HBB). -\end_layout - -\begin_layout Itemize -You can control the luminosity behaviour on the TPAGB with -\family typewriter -NUCSYN_TPAGB_LUMTYPE -\family default -. - If zero then an average luminosity is used, if 1 then post-flash dips are - included for the first -\family typewriter -NUCSYN_PULSE_LUM_DROP_N_PULSES -\family default - dips ( -\family typewriter -DTFAC -\family default - must be set to something small e.g. - 0.1 to resolve the dips). - The drop is by a factor -\family typewriter -THERMAL_PULSE_LUM_DROP_FACTOR -\family default - and the luminosity rises again on a timescale 1/ -\family typewriter -THERMAL_PULSE_LUM_DROP_TIMESCALE -\family default - of the interpulse period. - The -\family typewriter -spiky_luminosity -\family default - variable in each star structure follows the luminosity changes. - It is impossible to put the changes in the luminosity itself because the - timestep becomes very small when the luminosity (and so radius) changes - suddenly._ -\end_layout - -\begin_layout Itemize - -\family typewriter -NUCSYN_SMOOTH_AGB_RADIUS_TRANSITION -\family default - smooths the transition between Hurley and Karakas -\begin_inset Formula $L$ -\end_inset - - and -\begin_inset Formula $R$ -\end_inset - -: it's a bit of a fudge (uses -\family typewriter -NUCSYN_SMOOTH_AGB_RADIUS_TRANSITION_SMOOTHING_TIME -\family default -). -\end_layout - -\begin_layout Itemize - -\family typewriter -NUCSYN_TPAGB_MIN_LUMINOSITY -\family default - is a minimum luminosity for TPAGB stars, a bit of a fudge, usually -\begin_inset Formula $100\,\mathrm{L}_{\odot}$ -\end_inset - -. -\end_layout - -\begin_layout Itemize - -\family typewriter -MAX_TPAGB_TIME -\family default - the maximum time (in years) for which the TPAGB phase is allowed to run, - just in case something goes wrong, default is -\begin_inset Formula $10^{8}\,\mathrm{years}$ -\end_inset - -. -\end_layout - -\begin_layout Itemize - -\family typewriter -NUCSYN_ROBS_REFITTED_TPAGB_INTERPULSES -\family default - enables updated fits for the interpulse period. -\end_layout - -\begin_layout Itemize - -\family typewriter -MINIMUM_INTERPULSE_PERIOD -\family default - is the minimum interpulse period, default -\begin_inset Formula $10^{-4}\,\mathrm{years}$ -\end_inset - - -\end_layout - -\begin_layout Itemize -Enable -\family typewriter -NUCSYN_TPAGB_HBB -\family default - if you want to HBB on the TPAGB. - Choose either the analytic burning method, -\family typewriter -NUCSYN_ANAL_BURN -\family default -, or the numerical solver -\family typewriter -NUCSYN_NUMERICAL_BURN -\family default -. - The latter has proved to be reliable, and more flexible, so I would go - with that. -\end_layout - -\begin_deeper -\begin_layout Itemize -If you choose -\family typewriter -NUCSYN_ANAL_BURN -\family default - you can specify which nuclear reactions to include: -\family typewriter -NUCSYN_TPAGB_HBB_CN_CYCLE -\family default - and -\family typewriter -NUCSYN_TPAGB_HBB_ON_CYCLE -\family default - are the CN and ON parts of the CNO cycling in HBB, -\family typewriter -NUCSYN_TPAGB_HBB_NeNa_CYCLE -\family default - activates the approximate NeNa cycling, -\family typewriter -NUCSYN_TPAGB_HBB_MgAl_CYCLE -\family default - activates the approximate MgAl cycling. - Enable -\family typewriter -NUCSYN_CNO_ASSUME_STABLE -\family default - to assume solutions of the CNO quadratic are always real (i.e. - a stable solution, neglect the oscillating parts), -\family typewriter -NUCSYN_NENA_LEAK -\family default - will allow leakage from NeNa to MgAl (do this), -\family typewriter -NUCSYN_Na22_EQUILIBRIUM -\family default - will force Na22 into equilibrium (otherwise it is not calculated because - it is unstable and you probably do not care), -\family typewriter -NUCSYN_Al26m -\family default - follows the metastable state of -\begin_inset Formula $^{26}\mathrm{Al}$ -\end_inset - - (again, do you care? it makes little difference except at low -\begin_inset Formula $Z$ -\end_inset - -) and -\family typewriter -NUCSYN_MGAL_LEAKBACK -\family default - allows the -\begin_inset Formula $^{27}\mathrm{Al}(p,\alpha)^{24}\mathrm{Mg}$ -\end_inset - - reaction, which should be negligible. -\end_layout - -\begin_layout Itemize -If you choose -\family typewriter -NUCSYN_NUMERICAL_BURN -\family default - then most of the above options are automatically taken into account by - the burning schemes. - However, you can choose your schemes with -\family typewriter -NUCSYN_NETWORK_PP -\family default - ( -\begin_inset Formula $pp$ -\end_inset - --chain), -\family typewriter -NUCSYN_NETWORK_COLDCNO -\family default - (cold CNO cycle, which is sufficient for temperatures less than -\begin_inset Formula $\log_{10}T/\mathrm{K}\lesssim8.2$ -\end_inset - -), -\family typewriter -NUCSYN_NETWORK_HOTCNO -\family default - (hot CNO cycle, explicitly includes -\begin_inset Formula $\beta$ -\end_inset - - decays and is probably not necessary for most purposes) and -\family typewriter -NUCSYN_NETWORK_NeNaMgAl -\family default - (NeNa and MgAl cycles/chains). - -\family typewriter -NUCSYN_NORMALIZE_NUCLEONS -\family default - preserves the number of nucleons in the burning routine, which should prevent - numerical errors. -\end_layout - -\end_deeper -\begin_layout Itemize -Further, -\family typewriter -NUCSYN_HBB_RENORMALIZE_MASS_FRACTIONS -\family default - will renormalize the total mass fraction to one in order to remove some - errors. - -\end_layout - -\begin_layout Itemize - -\family typewriter -NUCSYN_S_PROCESS -\family default - activates the elemental -\begin_inset Formula $s$ -\end_inset - --process, you might well want this. - -\family typewriter -NUCSYN_EXTENDED_S_PROCESS -\family default - does the same for isotopes, but is not properly implemented yet. - If you want to implement this then you should probably remove the elemental - part, and I have not had a reason to do this yet (elements are observed\SpecialChar \ldots{} - - isotopes are not). - The -\begin_inset Quotes eld -\end_inset - - -\begin_inset Formula $^{13}\mathrm{C}$ -\end_inset - --efficiency -\begin_inset Quotes erd -\end_inset - - is set to its default by -\family typewriter -DEFAULT_C13_EFFICIENCY -\family default - (usually -\begin_inset Formula $1$ -\end_inset - -) but see also -\begin_inset CommandInset citation -LatexCommand citet -key "2007A&A...469.1013B" - -\end_inset - -. - If you define -\family typewriter -C13_POCKET_CORRECTION -\family default - then the amount of -\begin_inset Formula $s$ -\end_inset - --process material is correctly for a change in intershell mass, the standard - being -\family typewriter -STD_M_C13_POCKET -\family default -. -\end_layout - -\begin_layout Itemize -Enable -\family typewriter -NUCSYN_STPAGB -\family default - for STPAGB stars. - There are many associated options which you should not play with. -\end_layout - -\begin_layout Itemize -The -\family typewriter -NUCSYN_HS_LS_LOG -\family default - is an option for s-process logging and outputs the value of -\begin_inset Formula $[hs]$ -\end_inset - -, -\begin_inset Formula $[ls]$ -\end_inset - - and -\begin_inset Formula $[hs/ls]$ -\end_inset - - (see e.g. - -\begin_inset CommandInset citation -LatexCommand citealp -key "1998ApJ...497..388G" - -\end_inset - -). -\end_layout - -\begin_layout Itemize - -\family typewriter -NUCSYN_RADIOACTIVE_DECAY -\family default - allows decay of isotopes. -\end_layout - -\begin_layout Itemize - -\family typewriter -NUCSYN_FORCE_DUP_IN_COMENV -\family default - forces dredge up when a common envelope forms. - This seems likely, as a companion star spiralling in will mix up the envelope. -\end_layout - -\begin_layout Itemize - -\family typewriter -NUCSYN_WR -\family default - switches on the massive star (and WR/Helium star) code. - -\family typewriter -NUCSYN_WR_METALLICITY_CORRECTIONS -\family default - switches on the -\begin_inset Formula $Z\neq0.02$ -\end_inset - - extension to this code. - -\family typewriter -NUCSYN_WR_LOG -\family default - outputs some information during the O/B or WR phase. - -\family typewriter -NUCSYN_WR_TABLES -\family default - uses tabular values instead of fits (please use this) and -\family typewriter -NUCSYN_WR_RS_TABLE -\family default - enables Richard Stancliffe's tables (this code is in -\emph on -testing -\emph default -). -\end_layout - -\begin_layout Itemize - -\family typewriter -NUCSYN_NOVAE -\family default - and -\family typewriter -NUCSYN_SUPERNOVAE -\family default - switch on the novae and supernovae respectively. - You should enable -\family typewriter -NUCSYN_NOVAE_FROM_TABLES -\family default - to use tables instead of fits. - -\end_layout - -\begin_layout Itemize -For core-collapse supernovae choose either -\family typewriter -NUCSYN_CCSNE_WOOSLEY_WEAVER_1995 -\family default - or -\family typewriter -NUCSYN_CCSNE_CHIEFFI_LIMONGI_2004 -\family default -. - -\end_layout - -\begin_deeper -\begin_layout Itemize -In the case of -\family typewriter -NUCSYN_CCSNE_WOOSLEY_WEAVER_1995 -\family default - you can choose to use their -\family typewriter -NUCSYN_SUPERNOVAE_CC_WW95_A -\family default - or -\family typewriter -B -\family default - or -\family typewriter -C -\family default - models. -\end_layout - -\begin_layout Itemize -In the case of -\family typewriter -NUCSYN_CCSNE_CHIEFFI_LIMONGI_2004 -\family default - you can either use their yields directly (best to do this as then the yields - really are a function of mass cut) or use the Portinari-corrected versions - which are less accurate ( -\family typewriter -NUCSYN_CCSNE_CHIEFFI_LIMONGI_2004_PORTINARI -\family default -). - Define -\family typewriter -NUCSYN_CCSNE_CHIEFFI_LIMONGI_2004_EXTRAPOLATE -\family default - to extrapolate beyond the end of their table at the high metallicity ( -\begin_inset Formula $Z>0.02$ -\end_inset - -) end. -\end_layout - -\begin_layout Itemize - -\family typewriter -NUCSYN_SN_REDUCE_SODIUM -\family default - reduces the sodium yield: avoid this. -\end_layout - -\begin_layout Itemize - -\family typewriter -NUCSYN_LIMIT_SN_TYPES -\family default - allows you to exclude SN yields from various types on the command line -\end_layout - -\begin_layout Itemize - -\family typewriter -NUCSYN_R_PROCESS -\family default - allows -\begin_inset Formula $r$ -\end_inset - --process yields: choose from -\family typewriter -NUCSYN_R_PROCESS_ARLANDINI1999 -\family default - or -\family typewriter -NUCSYN_R_PROCESS_SIMMERER2004 -\family default -. - You also need to choose -\family typewriter -NUCSYN_R_PROCESS_FROM_SNE_MASS -\family default - which is the mass of -\begin_inset Formula $r$ -\end_inset - --process material ejected in the SN, typically I choose -\begin_inset Formula $10^{-6}\mathrm{\,M_{\odot}}$ -\end_inset - - but this is quite arbitrary. -\end_layout - -\end_deeper -\begin_layout Itemize - -\family typewriter -NUCLEAR_REACTION_RATE_MULTIPLIERS -\family default - allows you to change nuclear reaction rates on the command line (see -\begin_inset CommandInset citation -LatexCommand citealp -key "2007A&A...466..641I" - -\end_inset - - for the reasoning). -\end_layout - -\begin_layout Itemize - -\family typewriter -NUCSYN_SIGMAV_PRE_INTERPOLATE -\family default - allows interpolation of the nuclear cross section -\begin_inset Formula $\left\langle \sigma v\right\rangle $ -\end_inset - - from a pre-calculated table, rather than a recalculation of the values - from analytic formulae as a function of temperature. - This is about -\begin_inset Formula $10\%$ -\end_inset - - quicker. - You can change the resolution in -\begin_inset Formula $T_{9}=T/10^{9}\mathrm{K}$ -\end_inset - - with -\family typewriter -NUCSYN_SIGMAV_INTERPOLATION_RESOLUTION -\family default - and you should enable -\family typewriter -NUCSYN_SIGMAV_INTERPOLATE_LOGT9 -\family default - and -\family typewriter -NUCSYN_SIGMAV_INTERPOLATE_LOGSIGMAV -\family default - so the interpolations are done in log space. - -\family typewriter -SIGMAV_TINY -\family default - ( -\begin_inset Formula $10^{-100}$ -\end_inset - -) is a minimum value for the cross section. - Enable -\family typewriter -NUCSYN_HOT_SIGMAV -\family default - if you want to use high-temperature ( -\begin_inset Formula $>10^{9}\mathrm{K}$ -\end_inset - -) reaction rates (otherwise don't calculate them, because it's slower). - Enable -\family typewriter -NUCSYN_THERMALIZED_CORRECTIONS -\family default - for high temperature reactions (not normally required). -\end_layout - -\begin_layout Itemize -Enable -\family typewriter -NUCSYN_ALLOW_NO_PRODUCTION -\family default - to prevent the surface abundances from changing if -\family typewriter ---no_production -\family default - is used on the command line. -\end_layout - -\begin_layout Itemize - -\family typewriter -NUCSYN_LOW_MASS_STRIPPING -\family default - is used to change surface abundances as a function of mass stripped for - star 1 and only for low mass. - It is based on a lookup table of -\emph on -TWIN -\emph default --code results. - It is a temporary fudge for a particular problem and you probably do not - want it. -\end_layout - -\begin_layout Itemize -There are various logging options. - -\family typewriter -NUCSYN_LOGGING -\family default - should be defined if you want any output at all. -\end_layout - -\begin_layout Itemize - -\family typewriter -NUCSYN_YIELDS -\family default - should be used if you want to calculate the yield from each star. - Note that yields are calculated for each single star and the whole binary - system separately. - -\end_layout - -\begin_layout Itemize - -\family typewriter -NUCSYN_LOG_BINARY_MPYIELDS -\family default - outputs the yield -\begin_inset Formula $p_{\textrm{M}}$ -\end_inset - - for the binary system (if -\family typewriter -NUCSYN_YIELDS -\family default - and -\family typewriter -NUCSYN_LOG_YIELDS -\family default - are defined). -\end_layout - -\begin_layout Itemize - -\family typewriter -NUCSYN_LOG_YIELDS -\family default - outputs the yields -\emph on -at every timestep -\emph default - (warning! this is a lot of output since it applies to -\emph on -all -\emph default - the isotopes, perhaps run through -\family typewriter -gawk -\family default - to reduce the output) if -\family typewriter -NUCSYN_YIELDS -\family default - is defined. - If -\family typewriter -NUCSYN_YIELDS -\family default - is defined and -\family typewriter -NUCSYN_LOG_YIELDS -\family default - is -\emph on -not defined -\emph default - then the yields will be output at the end of the evolution time -- this - is the usual case. -\end_layout - -\begin_layout Itemize - -\family typewriter -NUCSYN_LOG_BINARY_X_YIELDS -\family default - outputs the mass ejected from the binary. -\end_layout - -\begin_layout Itemize - -\family typewriter -NUCSYN_LOG_SINGLE_X_YIELDS -\family default - outputs the mass ejected from each star. -\end_layout - -\begin_layout Itemize - -\family typewriter -NUCSYN_LOG_MPYIELDS -\family default - outputs the -\begin_inset Formula $p_{\textrm{M}}$ -\end_inset - - yield for each star. -\end_layout - -\begin_layout Itemize - -\family typewriter -NUCSYN_LOG_DX_YIELDS -\family default - outputs the mass ejected from each star for each timestep. -\end_layout - -\begin_layout Itemize - -\family typewriter -NUCSYN_SHORT_LOG -\family default - outputs some stuff about the stars (usually in the TPAGB phase) -\end_layout - -\begin_layout Itemize - -\family typewriter -NUCSYN_LOG -\family default - outputs more stuff. -\end_layout - -\begin_layout Itemize - -\family typewriter -NUCSYN_LONG_LOG -\family default - outputs even more stuff. -\end_layout - -\begin_layout Itemize - -\family typewriter -NUCSYN_J_LOG -\family default - outputs some stuff for J-type stars. -\end_layout - -\begin_layout Itemize - -\family typewriter -NUCSYN_S_PROCESS_LOG -\family default - outputs some stuff to do with the s-process. -\end_layout - -\begin_layout Itemize - -\family typewriter -NUCSYN_STRUCTURE_LOG -\family default - outputs stuff to do with the stellar structure. -\end_layout - -\begin_layout Itemize - -\family typewriter -NUCSYN_XTOT_CHECKS -\family default - is supposed to check that -\begin_inset Formula $\Sigma_{i}X_{\textrm{i}}=1$ -\end_inset - - (i.e. - the mass fractions add to -\begin_inset Formula $1$ -\end_inset - -) all the time. - This has not been used in a long time\SpecialChar \ldots{} - so do not be surprised if it fails! -\end_layout - -\begin_layout Itemize - -\family typewriter -NUCSYN_CEMP_LOGGING -\family default - and associated options are for the CEMP papers. - Do not use these, they are experimental. -\end_layout - -\begin_layout Itemize - -\family typewriter -NUCSYN_PLANETARY_NEBULAE -\family default - provides some information about PNe formation. -\end_layout - -\begin_layout Itemize - -\family typewriter -NUCSYN_TPAGB_RUNTIME -\family default - provides information about the time the code spends in the -\family typewriter -nucsyn_tpagb -\family default - function. -\end_layout - -\begin_layout Itemize - -\family typewriter -NUCSYN_ID_SOURCES -\family default - is used to identify where the yields come from and is extremely useful. -\end_layout - -\begin_layout Itemize - -\family typewriter -CONSMASS -\family default - is activated to check whether mass is conserved when a call is made to - the -\family typewriter -nucsyn_binary_yield -\family default - function. - If you find you are losing mass somewhere then this is probably a bug (or - a numerical error, in which case you should try to fix it!) so activate - -\family typewriter -CONSMASS -\family default - and the code will dump out when there is missing mass. - See the -\family typewriter -nucsyn_binary_yield -\family default - function for details. - -\family typewriter -CONSMASSDM -\family default - is an extension to this but I cannot remember what it does. -\end_layout - -\begin_layout Itemize - -\family typewriter -MIXDEBUG -\family default - outputs some debugging information in the mixing routines, but there's - a lot of data... - -\family typewriter -MIXLOG -\family default - is supposed to be a shorter version but I haven't used this for ages so - it might not work. - -\family typewriter -MIXDEBUG -\family default - is usually set in the routine you are considering rather than here because - if it is activated in -\family typewriter -nucsyn.h -\family default - then it will be passed to -\emph on -all -\emph default - routines. -\end_layout - -\begin_layout Itemize - -\family typewriter -AMU_GRAMS -\family default - and -\family typewriter -ANU_MEV -\family default - are constants and should not be changed! They give the atomic mass unit - in grams and MeV. -\end_layout - -\begin_layout Itemize - -\family typewriter -NUC_MASSES_DEBUG -\family default - enables debugging in the nuclear mass setting code. -\end_layout - -\begin_layout Itemize - -\family typewriter -NUCSYN_TPAGB_EDDINGTON_CHECKS -\family default - does something to tell you whether your AGB star exceeds the Eddington - limit. -\end_layout - -\begin_layout Itemize - -\family typewriter -NUCSYN_GCE -\family default - enables other options which are used in my GCE code. - Do not touch this unless you know what you are doing. -\end_layout - -\begin_layout Itemize - -\family typewriter -NUCSYN_ROTATION_EFFECTS -\family default - simulates extra -\begin_inset Formula $^{14}\mathrm{N}$ -\end_inset - - production at low- -\begin_inset Formula $Z$ -\end_inset - -. - Do not touch. -\end_layout - -\begin_layout Itemize - -\family typewriter -NUCSYN_HUGE_PULSE_CRISTALLO -\family default - Enables a huge third dredge up based on Sergio Cristallo's models. - Experimental. -\end_layout - -\begin_layout Itemize - -\family typewriter -NUCSYN_CONVECTIVE_MIXIN -\family default - Instead of mixing material into the whole envelope (as the original thermohalin -e mixing routine does) this uses the estimate of the convective envelope - given in mrenv and mixes into that instead. - Requires that you turn off thermohaline mixing (see -\family typewriter -MAYBE_NO_THERMOHALINE_MIXING -\family default - and the -\family typewriter ---no_thermohaline_mixing -\family default - command-line option). -\end_layout - -\begin_layout Itemize - -\family typewriter -NUCSYN_STAR_BY_STAR_MATCHING -\family default - Enables some code to match stars to given observations. -\end_layout - -\begin_layout Itemize - -\family typewriter -NUCSYN_SAFE_XSURF -\family default - is defined if there is no possibility of a feedback loop which used to - occur in the -\family typewriter -nucsyn_WR -\family default - functions. - Newer versions avoid this by using -\family typewriter -NUCSYN_WR_TABLES -\family default - and so it should defined if -\family typewriter -NUCSYN_WR_TABLES -\family default - is defined. -\end_layout - -\begin_layout Itemize -NUCSYN_MU_FUZZ blurs the condition for accretion layers to sink to prevent - unecessary calculations. -\end_layout - -\begin_layout Itemize - -\family typewriter -MATTSSON_MASS_LOSS -\family default - experimental mass-loss rates from Lars Mattsson (based on carbon abundances). -\end_layout - -\begin_layout Itemize - -\family typewriter -LITHIUM_TABLES -\family default - experiments to introduce lithium as a function of mass and pulse number - in HBBing stars. -\end_layout - -\begin_layout Standard -Now you have edited this file to your specifications you need to rebuild - the code. - The simplest way is -\end_layout - -\begin_layout Standard - -\family typewriter -make clean -\end_layout - -\begin_layout Standard - -\family typewriter -make -\end_layout - -\begin_layout Standard -although if you have changed only one or two parameters (e.g. - -\family typewriter -NUCSYN_WR -\family default - and -\family typewriter -NUCSYN_NOVAE -\family default -) you can use configure like this -\end_layout - -\begin_layout Standard - -\family typewriter -./configure re NUCSYN_WR re NUCSYN_NOVAE -\end_layout - -\begin_layout Standard - -\family typewriter -make -\end_layout - -\begin_layout Standard -because the configure script will automatically remove the object files - it needs to rebuild (the ones which contain -\family typewriter -NUCSYN_WR -\family default - or -\family typewriter -NUCSYN_NOVAE -\family default -). - This is far quicker than rebuilding the entire code. - If you find you have problems with segfaults then a complete clean rebuild - may be the only way. -\end_layout - -\begin_layout Standard - -\family typewriter -configure -\family default - is supposed to detect your CPU but I have limited machines on which to - test this feature. - Please add your machine to the list in -\family typewriter -configure -\family default -. -\end_layout - -\begin_layout Standard -There are further options in the file -\family typewriter -binary_parameters.h -\family default - (details below) although it's unlikely you'll want to change any of them. -\end_layout - -\begin_layout Section -Changelog -\end_layout - -\begin_layout Standard -The changes to this manual and/or -\emph on -binary_c/nucsyn -\emph default -. - (note this is always an incomplete list!) -\end_layout - -\begin_layout Description -Version -\begin_inset space ~ -\end_inset - -1.2prexx Lots of updates! CEMPs project (Utrecht), experimental stuff to - better model rotation, tables replace many fits (e.g. - -\family typewriter -nucsyn_WR -\family default -), interaction with -\family typewriter -binary_grid -\family default - Perl module for population synthesis, external users (Selma, Joke, Carlo). -\end_layout - -\begin_layout Description -Version -\begin_inset space ~ -\end_inset - -1.2 Include STPAGB stars, batchmode and -\family typewriter -grid.pl -\family default - references, -\family typewriter -spiky_luminosity -\family default -, removal of the adaptive grid. - Also mention -\family typewriter -gce.pl -\family default -. - -\end_layout - -\begin_layout Description -Version -\begin_inset space ~ -\end_inset - -1.1 Minor changes to include support for variation of initial abundances - via command-line switches for Hilke's GCE project. -\end_layout - -\begin_layout Description -Version -\begin_inset space ~ -\end_inset - -1.0 The original version. -\end_layout - -\begin_layout Standard -\paragraph_spacing other 0.0 - -\size scriptsize -\begin_inset CommandInset bibtex -LatexCommand bibtex -bibfiles "references" -options "apalike" - -\end_inset - - -\end_layout - -\end_body -\end_document diff --git a/doc/deprecated/nucsyn_manual.pdf b/doc/deprecated/nucsyn_manual.pdf deleted file mode 100644 index df2e82cd47e4088a892883e745e52cfaa2667b28..0000000000000000000000000000000000000000 Binary files a/doc/deprecated/nucsyn_manual.pdf and /dev/null differ diff --git a/doc/deprecated/references.bib b/doc/deprecated/references.bib deleted file mode 120000 index 28b114fd475f56cf7688ca6fb8b56aed03091690..0000000000000000000000000000000000000000 --- a/doc/deprecated/references.bib +++ /dev/null @@ -1 +0,0 @@ -../references.bib \ No newline at end of file diff --git a/doc/shared_library b/doc/shared_library deleted file mode 100644 index feb80c6c21ac05ab826d404ecfd23391514cd27c..0000000000000000000000000000000000000000 --- a/doc/shared_library +++ /dev/null @@ -1,18 +0,0 @@ -The libbinary_c.so shared library is used to use binary_c through the API -e.g. through the binary_grid::C backend. - -To build the shared library: - -./configure -make clean -make -make libbinary_c.so - -To build the binary_grid::C backend: - -1) export BINARY_C_SRC=<location your binary_c src directory> -2) install the binary_grid module as usual - -Note that binary_grid will only install the Perl backend -if BINARY_C_SRC is not defined or it cannot find binary_c.h on its own. -(It also checks in $HOME/progs/stars/binary_c/src) \ No newline at end of file diff --git a/meson.build b/meson.build index 6b42ead1f71c1fd0f177872df96a53b2072c38f3..0f29d29653e6b835ed227b3bd317f8f2de67e824 100644 --- a/meson.build +++ b/meson.build @@ -1511,27 +1511,6 @@ if os == 'linux' and \ endif -############################################################ -# -# symlink shared_library to binary_c/src directory -# run: ninja libbinary_c_symlink -# -# NB only works if we can symlink, i.e. unix systems -# -if unix - libbinary_c_symlink = custom_target( - 'libbinary_c_symlink', - build_by_default: false, - output: [ 'libbinary_c_symlink' ], - command: [ - 'sh', - '-c', - '../meson/symlink_libbinary_c.sh' - ], - ) -endif - - ############################################################ # # make binary_c objects diff --git a/meson/pgo.sh b/meson/pgo.sh index d4534f468b59c48a3e628054c6283e7cae19fd3e..7c5a81d7ea5b523bc09330ed0d8b2a66eb123e45 100755 --- a/meson/pgo.sh +++ b/meson/pgo.sh @@ -1,21 +1,30 @@ #!/bin/bash -cd ${MESON_SOURCE_ROOT} # script to do PGO with Meson +# make sure BINARY_C is set, or run from the binary_c +# root directory +: "${BINARY_C:=`pwd`}" # set defaults BUILDDIR="builddir" N="$1" -: "${N:='1000'}" +: "${N:=1000}" NCORES=$(grep -c -i Processor /proc/cpuinfo) : "${NCORES:='1'}" TMP="/tmp/" NCORES1=$((NCORES - 1)) REPEAT_PER_CORE=$((N/NCORES)) SLEEP=0 -MESON="meson" +MESON="meson --buildtype=release" NINJA="ninja" +DUMMY=0 # if 1 just do a dummy run +STATUS_SLEEP=2 + +if [ -d $BUILDDIR ] ; then + echo "Please remove $BUILDDIR before we start" + exit +fi # where to redirect stderr, stdout on meson and ninja calls MESON_STDERR=/dev/stderr @@ -29,7 +38,21 @@ WARMUP_SECS=0 COMMAND1="random_systems 1 repeat $REPEAT_PER_CORE warmup_cpu $WARMUP_SECS" # status message -echo "Using Meson to build binary_c with Profile Guided Optimization (PGO) on $N systems across $NCORES cores" +echo "Using Meson to build binary_c with Profile Guided Optimization (PGO) on $N systems across $NCORES cores" +echo +echo +echo "Ncores : $NCORES" +echo "N tests : $N" +echo "repeat/core : $REPEAT_PER_CORE" +echo "Meson command: $MESON" +echo "Ninja command: $NINJA" +echo " builddir: $BUILDDIR" +echo "Warmup sleep : $SLEEP" +echo "Tmp dir : $TMP" +echo "tbse cmd : $TBSE $COMMAND1" +echo "warmup secs : $WARMUP_SECS" +echo "status sleep : $STATUS_SLEEP" +echo # function to kill child processes KillChildren() { @@ -53,14 +76,19 @@ trap '[ -n "$(jobs -pr)" ] && KillChildren $$' INT QUIT TERM EXIT ############################################################ # first build: use builddir if already avaialble echo "Configure meson for PGO build 1" -if [ -d $BUILDDIR ] ; then - $MESON configure $BUILDDIR -Db_pgo=generate > $MESON_STDOUT 2> $MESON_STDERR -else - $MESON $BUILDDIR -Db_pgo=generate > $MESON_STDOUT 2> $MESON_STDERR +if ! [ $DUMMY -eq 1 ]; then + if [ -d $BUILDDIR ] ; then + $MESON --reconfigure $BUILDDIR -Db_pgo=generate \ + > $MESON_STDOUT 2> $MESON_STDERR + else + $MESON $BUILDDIR -Db_pgo=generate \ + > $MESON_STDOUT 2> $MESON_STDERR + fi fi echo "Build (1) with ninja" -$NINJA -C $BUILDDIR > $NINJA_STDOUT 2> $NINJA_STDERR - +if ! [ $DUMMY -eq 1 ]; then + $NINJA -C $BUILDDIR > $NINJA_STDOUT 2> $NINJA_STDERR +fi ############################################################ ############################################################ # run and filter to files @@ -68,19 +96,52 @@ START=$(date +%s%N) echo "Running binary_c" for i in $(seq 0 $NCORES1); do echo "Launch tbse on core $i" - taskset -c "$i" "$TBSE" "$COMMAND1" | grep At | awk '{print substr($0, index($0,$5))}' > "$TMP/binary_c_pgo.$i" & + if ! [ $DUMMY -eq 1 ]; then + taskset -c "$i" "$TBSE" "$COMMAND1" | grep At | awk '{print substr($0, index($0,$5))}' > "$TMP/binary_c_pgo.$i" & + fi sleep "$SLEEP" done + +function statusbar() { + KEEP_LOOPING=true + printf "Thread %5s/%8s %12s\n" "Ndone" "Ntotal" "complete %" + while $KEEP_LOOPING; + do + KEEP_LOOPING=false + for i in $(seq 0 $NCORES1); do + DONE=`wc -l "$TMP/binary_c_pgo.$i" | gawk "{print \\\$1}"` + PCDONE=`echo "$DONE $N" | gawk "{print 100.0*\\\$1/\\\$2}"` + printf "%3d %8d/%8d %12.3f %%\n" $i $DONE $REPEAT_PER_CORE $PCDONE + if ! [ $DONE -eq $REPEAT_PER_CORE ]; then + KEEP_LOOPING=true + fi + done + + if [ $KEEP_LOOPING = true ]; then + sleep $STATUS_SLEEP + echo -n -e '\033['$NCORES'A' + fi + done; +} + +statusbar wait + END=$(date +%s%N) PGO1_DURATION=$(echo "(0.000000001*($END - $START))"|bc) ############################################################ # rebuild echo "Configure meson for PGO build 2" -$MESON configure $BUILDDIR -Db_pgo=use > $MESON_STDOUT 2> $MESON_STDERR -echo "Build (2) with ninja" -$NINJA -C $BUILDDIR > $NINJA_STDOUT 2> $NINJA_STDERR +if ! [ $DUMMY -eq 1 ]; then + $MESON --reconfigure $BUILDDIR -Db_pgo=use \ + > $MESON_STDOUT 2> $MESON_STDERR +fi +echo "Build (2) with ninja" +if ! [ $DUMMY -eq 1 ]; then + $NINJA -C $BUILDDIR \ + > $NINJA_STDOUT 2> $NINJA_STDERR +fi # remove trap trap - INT QUIT TERM EXIT @@ -95,10 +156,15 @@ START=$(date +%s%N) echo "Running binary_c" for i in $(seq 0 $NCORES1); do - env FIRST_TBSE="warmup_cpu $WARMUP_SECS" taskset -c "$i" "$TBSE" "$TMP/binary_c_pgo.$i" >/dev/null 2>&1 & + if ! [ $DUMMY -eq 1 ]; then + env FIRST_TBSE="warmup_cpu $WARMUP_SECS" taskset -c "$i" "$TBSE" "$TMP/binary_c_pgo.$i" >/dev/null 2>&1 & + fi sleep $SLEEP done + +statusbar wait + END=$(date +%s%N) PGO2_DURATION=$(echo "(0.000000001*($END - $START))"|bc) diff --git a/meson/symlink_libbinary_c.sh b/meson/symlink_libbinary_c.sh deleted file mode 100755 index e7a7954997bee754921dd1abfca988560448d7e0..0000000000000000000000000000000000000000 --- a/meson/symlink_libbinary_c.sh +++ /dev/null @@ -1,6 +0,0 @@ -#!/bin/bash - -# script to symlink a completed binary_c executable -# to the binary_c root directory. - -ln -sfr ${MESON_BUILD_ROOT}/libbinary_c.so ${MESON_SOURCE_ROOT}/src/ diff --git a/src/perl/modules_targz/binary_grid-v2.1.7.tar.gz b/src/perl/modules_targz/binary_grid-v2.1.7.tar.gz deleted file mode 100644 index 99f559af75498e271185bbe383bed49733a0bd85..0000000000000000000000000000000000000000 Binary files a/src/perl/modules_targz/binary_grid-v2.1.7.tar.gz and /dev/null differ