-
Izzard, Robert Dr (Maths & Physics) authoredIzzard, Robert Dr (Maths & Physics) authored
Code owners
Assign users and groups as approvers for specific file changes. Learn more.
binary_c2.lyx 334.92 KiB
#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 article
\begin_preamble
\usepackage[usenames,dvipsnames]{xcolor}
\input{binary_c2_preamble}
\end_preamble
\use_default_options true
\maintain_unincluded_children false
\begin_local_layout
Format 66
InsetLayout Flex:Command
LyxType Custom
Multipar 0
LabelString "Command"
LatexType Command
LatexName commandwrapper
Decoration Classic
HTMLStyle
span.flex_command {
font-family: monospace;
}
EndHTMLStyle
ResetsFont true
End
InsetLayout Flex:Perlscript
LyxType Custom
Multipar 0
LabelString "Perlscript"
LatexType Command
LatexName Perlscriptwrapper
Decoration Classic
HTMLStyle
span.flex_perlscript {
font-style: italic;
}
EndHTMLStyle
ResetsFont true
End
InsetLayout Flex:bashscript
Multipar 0
LyxType Custom
LabelString "bashscript"
LatexType Command
LatexName bashscriptwrapper
Decoration Classic
HTMLStyle
span.flex_bashscript {
font-style: italic;
}
EndHTMLStyle
ResetsFont true
End
InsetLayout Flex:File
Multipar 0
LyxType Custom
LabelString "File"
LatexType Command
LatexName filewrapper
Decoration Classic
HTMLStyle
span.flex_file { font-style: italic;
}
EndHTMLStyle
ResetsFont true
End
InsetLayout Flex:SourceFile
Multipar 0
LyxType Custom
LabelString "SourceFile"
LatexType Command
LatexName sourcefilewrapper
Decoration Classic
HTMLStyle
span.flex_sourcefile {
font-style: italic;
}
EndHTMLStyle
ResetsFont true
End
InsetLayout Flex:HeaderFile
Multipar 0
LyxType Custom
LabelString "HeaderFile"
LatexType Command
LatexName headerfilewrapper
Decoration Classic
HTMLStyle
span.flex_headerfile {
font-style: italic;
}
EndHTMLStyle
ResetsFont true
End
InsetLayout Flex:OS
Multipar 0
LyxType Custom
LabelString "OS"
LatexType Command
LatexName OSwrapper
Decoration Classic
HTMLStyle
span.flex_os {
font-style: italic;
}
EndHTMLStyle
ResetsFont true
End
InsetLayout Flex:CStruct
Multipar 0
LyxType Custom
LabelString "CStruct"
LatexType Command
LatexName Cstructwrapper
Decoration Classic
HTMLStyle
span.flex_cstruct {
font-family: monospace;
}
EndHTMLStyle
ResetsFont true
End
InsetLayout Flex:CFunction
Multipar 0
LyxType Custom LabelString "CFunction"
LatexType Command
LatexName Cfunctionwrapper
Decoration Classic
HTMLStyle
span.flex_cfunction {
font-family: monospace;
}
EndHTMLStyle
ResetsFont true
End
InsetLayout Flex:CVar
Multipar 0
LyxType Custom
LabelString "CVar"
LatexType Command
LatexName Cvarwrapper
Decoration Classic
HTMLStyle
span.flex_cvar {
font-family: monospace;
}
EndHTMLStyle
ResetsFont true
End
InsetLayout Flex:CMacro
Multipar 0
LyxType Custom
LabelString "CMacro"
LatexType Command
LatexName Cmacrowrapper
Decoration Classic
HTMLTag "span"
HTMLStyle
span.flex_cmacro {
font-family: monospace;
}
EndHTMLStyle
ResetsFont true
End
InsetLayout Flex:FortranFunction
Multipar 0
LyxType Custom
LabelString "FortranFunction"
LatexType Command
LatexName Fortranfunctionwrapper
Decoration Classic
HTMLStyle
span.flex_fortranfunction {
font-family: monospace;
}
EndHTMLStyle
ResetsFont true
End
InsetLayout Flex:ProgrammingLanguage
Multipar 0
LyxType Custom
LabelString "ProgrammingLanguage"
LatexType Command
LatexName ProgrammingLanguagewrapper
Decoration Classic
HTMLStyle span.flex_programminglanguage {
font-style: italic;
}
EndHTMLStyle
ResetsFont true
End
InsetLayout Flex:ScriptingLanguage
Multipar 0
LyxType Custom
LabelString "ScriptingLanguage"
LatexType Command
LatexName ScriptingLanguagewrapper
Decoration Classic
HTMLStyle
span.flex_scriptinglanguage {
font-style: italic;
}
EndHTMLStyle
ResetsFont true
End
InsetLayout Flex:Software
Multipar 0
LyxType Custom
LabelString "Software"
LatexType Command
LatexName Softwarewrapper
Decoration Classic
HTMLStyle
font-style: italic;
EndHTMLStyle
HTMLStyle
span.flex_software {
font-style: italic;
}
EndHTMLStyle
ResetsFont true
End
InsetLayout Flex:CFlags
Multipar 0
LyxType Custom
LabelString "CFlags"
LatexType Command
LatexName Cflagswrapper
Decoration Classic
HTMLStyle
span.flex_cflags {
font-family: monospace;
}
EndHTMLStyle
ResetsFont true
End
InsetLayout Flex:Args
Multipar 0
LyxType Custom
LabelString "Args"
LatexType Command
LatexName Argswrapper
Decoration Classic
HTMLStyle
span.flex_args {
font-family: monospace;
}
EndHTMLStyle
ResetsFont trueEnd
InsetLayout Flex:Envvar
Multipar 0
LyxType Custom
LabelString "Envvar"
LatexType Command
LatexName Envvarwrapper
Decoration Classic
HTMLStyle
span.flex_envvar {
font-family: monospace;
}
EndHTMLStyle
ResetsFont true
End
InsetLayout Flex:Perlmodule
Multipar 0
LyxType Custom
LabelString "Perlmodule"
LatexType Command
LatexName Perlmodulewrapper
Decoration Classic
HTMLStyle
span.flex_perlmodule {
font-family: monospace;
}
EndHTMLStyle
ResetsFont true
End
InsetLayout Flex:Perlcode
Multipar 0
LyxType Custom
LabelString "Perlcode"
LatexType Command
LatexName Perlcodewrapper
Decoration Classic
HTMLStyle
span.flex_perlcode {
font-family: monospace;
}
EndHTMLStyle
ResetsFont true
End
PackageOptions xcolor "usenames,dvipsnames"
AddToPreamble
%robadd
\usepackage[usenames,dvipsnames]{xcolor}
EndPreamble
\end_local_layout
\begin_forced_local_layout
Format 66
Style "Command"
Category "MainText"
Margin Dynamic
LatexType Command
InTitle 0
InPreamble 0
TocLevel -1000
ResumeCounter 0
StepMasterCounter 0
NeedProtect 0
KeepEmpty 0 NextNoIndent 0
CommandDepth 0
LatexName "commandwrapper"
ItemCommand item
LabelType Static
EndLabelType No_Label
ParagraphGroup "0"
ParSkip 0
ItemSep 0
TopSep 0
BottomSep 0
LabelBottomSep 0
LabelSep x
ParSep 0
NewLine 1
Align Block
AlignPossible Layout
LabelString "Command:"
FreeSpacing 0
PassThru 0
ParbreakIsNewline 0
RefPrefix OFF
HTMLLabelFirst 0
HTMLForceCSS 0
HTMLTitle 0
Spellcheck 1
ForceLocal 1
End
\end_forced_local_layout
\language british
\language_package default
\inputencoding auto
\fontencoding global
\font_roman "utopia" "default"
\font_sans "default" "default"
\font_typewriter "default" "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 100 100
\use_microtype false
\use_dash_ligatures false
\graphics default
\default_output_format default
\output_sync 0
\bibtex_command default
\index_command default
\paperfontsize 12
\spacing single
\use_hyperref false
\papersize a4paper
\use_geometry true
\use_package amsmath 1
\use_package amssymb 1
\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 1
\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
\listings_params "basicstyle={\ttfamily},backgroundcolor={\color{codeoffwhite}},breaklines=true,postbreak={\mbox{\textcolor{red}{$\hookrightarrow$}\space}},framexleftmargin=5pt,xleftmargin=5pt"
\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 Standard
\begin_inset FormulaMacro
\newcommand{\binaryc}{{\text{{\it binary\_c}}}}
{\text{\emph{binary\_c}}}
\end_inset
\begin_inset FormulaMacro
\newcommand{\Binaryc}{\text{{\it Binary\_c}}}
{\emph{Binary\_c}}
\end_inset
\begin_inset FormulaMacro
\newcommand{\BSE}{\emph{BSE}}
{\emph{BSE}}
\end_inset
\begin_inset FormulaMacro
\newcommand{\SSE}{\emph{SSE}}
{\emph{SSE}}
\end_inset
\begin_inset FormulaMacro
\newcommand{\STARS}{\text{{\it STARS}}}
{\emph{STARS}}
\end_inset
\begin_inset FormulaMacro
\newcommand{\NBODY}{\emph{NBODY}}
{\emph{NBODY}}
\end_inset
\begin_inset FormulaMacro
\newcommand{\NBODYSIX}{\emph{NBODY6}}
{\emph{NBODY6}}
\end_inset
\begin_inset FormulaMacro
\newcommand{\libbinaryc}{{\text{{\it libbinary\_c}}}}
{\text{\emph{libbinary\_c}}}
\end_inset
\begin_inset FormulaMacro
\newcommand{\binarygrid}{{\text{{\it binary\_grid}}}}
{\text{\emph{binary\_grid}}}
\end_inset
\begin_inset FormulaMacro
\newcommand{\binarycpython}{{\text{{\it binary\_c-python}}}}
{\text{\emph{binary\_c-python}}}
\end_inset
\begin_inset FormulaMacro
\newcommand{\mainbranch}{{\text{master}}}
{master}
\end_inset
\begin_inset FormulaMacro
\newcommand{\MINT}{\text{MINT}}
{\text{\emph{MINT}}}
\end_inset
\end_layout
\begin_layout Standard
\align center
\begin_inset Float figure
placement H
wide false
sideways false
status open
\begin_layout Plain Layout
\align center
\begin_inset Graphics
filename images/logo.pdf
width 55page%
\end_inset
\end_layout
\end_inset
\end_layout
\begin_layout Standard
\begin_inset Box Frameless
position "t"
hor_pos "c"
has_inner_box 1
inner_pos "t"
use_parbox 0use_makebox 0
width "100col%"
special "none"
height "1in"
height_special "totalheight"
thickness "0.4pt"
separation "3pt"
shadowsize "4pt"
framecolor "black"
backgroundcolor "lightgray"
status open
\begin_layout Plain Layout
\align center
\series bold
An introduction to the
\begin_inset Formula $\binaryc$
\end_inset
framework: software to make populations of single and binary stars on your
computer(s).
\begin_inset Newline newline
\end_inset
\begin_inset Newline newline
\end_inset
Version 2.2.0
\begin_inset Newline newline
\end_inset
\begin_inset Newline newline
\end_inset
Warning:
\emph on
\begin_inset Formula $\binaryc$
\end_inset
\emph default
is always under development, so details are likely to change.
\end_layout
\end_inset
\end_layout
\begin_layout Standard
\begin_inset Newpage pagebreak
\end_inset
\end_layout
\begin_layout Standard
\begin_inset CommandInset toc
LatexCommand tableofcontents
\end_inset
\end_layout
\begin_layout SectionDisclaimer 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 "subsec:Disclaimer"
\end_inset
Robert Izzard (henceforth RGI) is
\emph on
not responsible
\emph default
for anything you do with this code, for the results, quality of code or
results, etc.
\begin_inset space ~
\end_inset
it is up to you to make sure you get things right! You can check every line
of source code if you like.
While RGI has done his best to make sure everything that follows (and in
his papers) is correct
\series bold
there are certainly bugs and omissions
\series default
.
Please, if you find one, can you let him know, preferably through the gitlab
bug reporting interface
\begin_inset Flex URL
status open
\begin_layout Plain Layout
https://gitlab.eps.surrey.ac.uk/ri0005/binary_c/issues
\end_layout
\end_inset
or by email.
\series bold
\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
\end_layout
\end_inset
\end_layout
\begin_layout Subsection
Licence
\end_layout
\begin_layout Standard
\begin_inset CommandInset label
LatexCommand label
name "subsec:Licence"
\end_inset
Please read the
\begin_inset Flex File
status open
\begin_layout Plain Layout
LICENCE
\end_layout
\end_inset
file provided in the
\emph on
\begin_inset Formula $\binaryc$
\end_inset
\emph default
directory tree.
\end_layout
\begin_layout Subsection
Websites
\end_layout
\begin_layout Standard
\begin_inset CommandInset label
LatexCommand label
name "subsec:Website"
\end_inset
\end_layout
\begin_layout Itemize
The main
\begin_inset Formula $\binaryc$
\end_inset
website is at
\begin_inset CommandInset href
LatexCommand href
target "http://personal.ph.surrey.ac.uk/~ri0005/binary_c.html"
literal "false"
\end_inset
\end_layout
\begin_layout Itemize
\begin_inset Formula $\binaryc$
\end_inset
's
\begin_inset Flex Software
status open
\begin_layout Plain Layout
git
\end_layout
\end_inset
repository is at
\begin_inset CommandInset href
LatexCommand href
target "https://gitlab.eps.surrey.ac.uk/ri0005/binary_c"
literal "false"
\end_inset
\end_layout
\begin_layout Itemize
\begin_inset Formula $\binaryc$
\end_inset
is on Twitter at
\begin_inset Flex URL
status open
\begin_layout Plain Layout
https://twitter.com/binary_c_code
\end_layout
\end_inset
\end_layout
\begin_layout Itemize
\begin_inset Formula $\binaryc$
\end_inset
is on Facebook at
\begin_inset Flex URL
status open
\begin_layout Plain Layout
https://www.facebook.com/groups/149489915089142
\end_layout
\end_inset
\end_layout
\begin_layout Itemize
\begin_inset Formula $\binaryc$
\end_inset
is on YouTube at
\begin_inset Flex URL
status open
\begin_layout Plain Layout
https://www.youtube.com/channel/UCsWzzMdthAs5LMmDnXEqzrg
\end_layout
\end_inset
\end_layout
\begin_layout Subsection
Mailing lists and Slack
\end_layout
\begin_layout Standard
\begin_inset CommandInset label
LatexCommand label
name "subsec:mailing-lists"
\end_inset
There are two mailing lists for
\begin_inset Formula $\binaryc$
\end_inset
, both on Google's
\begin_inset Quotes eld
\end_inset
groups
\begin_inset Quotes erd
\end_inset
service
\end_layout
\begin_layout Itemize
We have a Slack workspace for
\begin_inset Formula $\binaryc$
\end_inset
, the
\begin_inset Quotes eld
\end_inset
BinarySlack
\begin_inset Quotes erd
\end_inset
, at
\begin_inset Flex URL
status open
\begin_layout Plain Layout
binaryslack.slack.com
\end_layout
\end_inset
.
\end_layout
\begin_layout Itemize
The announcements list\begin_inset Newline newline
\end_inset
\begin_inset CommandInset href
LatexCommand href
name " https://groups.google.com/group/binary_c-nucsyn-announce"
literal "false"
\end_inset
\begin_inset Newline newline
\end_inset
This contains major announcements such as significant upgrades to
\begin_inset Formula $\binaryc$
\end_inset
(or the supporting software)
\end_layout
\begin_layout Itemize
The development list
\begin_inset Newline newline
\end_inset
\begin_inset CommandInset href
LatexCommand href
name "https://groups.google.com/group/binary_c-nucsyn-devel"
literal "false"
\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
Conventions
\end_layout
\begin_layout Standard
It is assumed you are using a
\emph on
bash
\emph default
shell and are familiar with the
\begin_inset Flex OS
status open
\begin_layout Plain Layout
Linux
\end_layout
\end_inset
/
\begin_inset Flex OS
status open
\begin_layout Plain Layout
Unix
\end_layout
\end_inset
command line (
\begin_inset Flex OS
status open
\begin_layout Plain Layout
OSX
\end_layout
\end_inset
is similar and you should install the
\begin_inset Flex Software
status open
\begin_layout Plain Layout
GNU core utilities
\end_layout
\end_inset
).
Instructions which should be executed in a
\emph on
bash
\emph default
shells are preceded by
\family typewriter
$
\family default
symbols, which
\emph on
you should not
\emph default
\emph on
type!
\emph default
, like this:
\begin_inset listings
lstparams "language=bash"
inline false
status open
\begin_layout Plain Layout
cd $HOME
\end_layout
\begin_layout Plain Layout
ls
\end_layout
\end_inset
Bash
\emph on
scripts
\emph default
look like this (with the the leading
\family typewriter
$
\family default
symbols),
\end_layout
\begin_layout Standard\begin_inset listings
inline false
status open
\begin_layout Plain Layout
#!/bin/bash
\end_layout
\begin_layout Plain Layout
# ...
\end_layout
\begin_layout Plain Layout
# this is a bash script
\end_layout
\begin_layout Plain Layout
export BINARY_C=$HOME/progs/stars/binary_c
\end_layout
\begin_layout Plain Layout
cd $BINARY_C
\end_layout
\begin_layout Plain Layout
./binary_c version
\end_layout
\end_inset
while
\emph on
C
\emph default
code looks like this,
\end_layout
\begin_layout Standard
\begin_inset listings
inline false
status open
\begin_layout Plain Layout
int x;
\end_layout
\begin_layout Plain Layout
x++;
\end_layout
\end_inset
\begin_inset Flex ScriptingLanguage
status open
\begin_layout Plain Layout
Perl
\end_layout
\end_inset
code looks like this,
\begin_inset listings
lstparams "language=Perl"
inline false
status open
\begin_layout Plain Layout
my $y;
\end_layout
\begin_layout Plain Layout
$y++;
\end_layout
\end_inset
\end_layout
\begin_layout Standard
\begin_inset Flex ScriptingLanguage
status open
\begin_layout Plain Layout
Python
\end_layout
\end_inset
code looks like this,
\begin_inset listings
lstparams "language=Python"
inline false
status open
\begin_layout Plain Layout
x = x + 1
\end_layout
\begin_layout Plain Layout
print(
\begin_inset Quotes eld
\end_inset
hello binary_c world
\begin_inset Quotes erd
\end_inset
)
\end_layout
\end_inset
\end_layout
\begin_layout Standard
\begin_inset Newpage pagebreak
\end_inset
\end_layout
\begin_layout Section
Quick start guide
\end_layout
\begin_layout Standard
\begin_inset CommandInset label
LatexCommand label
name "sec:Quick-start-guide"
\end_inset
This section is a quick guide to getting
\begin_inset Formula $\binaryc$
\end_inset
,
\begin_inset Formula $\binarygrid$
\end_inset
or
\begin_inset Formula $\binarycpython$
\end_inset
to work.
Please start reading at Section
\begin_inset space ~
\end_inset
\begin_inset CommandInset ref
LatexCommand ref
reference "sec:Introduction"
plural "false"
caps "false"
noprefix "false"
\end_inset
if you want the full manual with complete installation instructions in
Section
\begin_inset space ~
\end_inset
\begin_inset CommandInset ref
LatexCommand ref
reference "subsec:Getting-binary-c"
plural "false"
caps "false"
noprefix "false"
\end_inset
.
\end_layout
\begin_layout Subsection
Ubuntu 20.10 quick start
\end_layout
\begin_layout Standard
If you are running the latest
\begin_inset Flex OS
status open
\begin_layout Plain Layout
Ubuntu
\end_layout
\end_inset
, 20.10 at the time of writing, the
\begin_inset Flex Filestatus open
\begin_layout Plain Layout
ubuntu_install_binary_c.sh
\end_layout
\end_inset
script, in
\begin_inset Formula $\binaryc$
\end_inset
's root directory, will do the installation for you.
Run the following to install even without a
\begin_inset Flex Software
status open
\begin_layout Plain Layout
git
\end_layout
\end_inset
account,
\end_layout
\begin_layout Standard
\begin_inset listings
inline false
status open
\begin_layout Plain Layout
wget http://personal.ph.surrey.ac.uk/~ri0005/ubuntu_install_binary_c.sh
\end_layout
\begin_layout Plain Layout
chmod +x ubuntu_install_binary_c.sh
\end_layout
\begin_layout Plain Layout
./ubuntu_install_binary_c.sh
\end_layout
\end_inset
You will need root access to update and install system packages appropriately.
\end_layout
\begin_layout Subsection
Download and build
\begin_inset Formula $\binaryc$
\end_inset
\end_layout
\begin_layout Standard
In the following, I assume you have internet access.
I also assume you are building for a generic 64-bit CPU on Linux, and have
software like
\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
Perl5
\end_layout
\end_inset
,
\begin_inset Flex Software
status open
\begin_layout Plain Layout
Python3
\end_layout
\end_inset
,
\begin_inset Flex Software
status open
\begin_layout Plain Layout
wget
\end_layout
\end_inset
and other standard build tools installed.
I assume your temporary directory is
\begin_inset Flex File
status open
\begin_layout Plain Layout
/tmp
\end_layout
\end_inset
and you use a shell like
\begin_inset Flex Software
status open
\begin_layout Plain Layout
bash
\end_layout
\end_inset
.
Installed support libraries will be put in
\begin_inset Flex File
status open
\begin_layout Plain Layout
$HOME/lib
\end_layout
\end_inset
(with associated executables in
\begin_inset Flex File
status open
\begin_layout Plain Layout
$HOME/bin\end_layout
\end_inset
, include files in
\begin_inset Flex File
status open
\begin_layout Plain Layout
$HOME/include
\end_layout
\end_inset
, etc.) so they are private to the user, rather than in system locations.
\begin_inset Formula $\binaryc$
\end_inset
will be installed in the
\begin_inset Flex Envvar
status open
\begin_layout Plain Layout
BINARY_C
\end_layout
\end_inset
directory, usually
\begin_inset Flex File
status open
\begin_layout Plain Layout
$HOME/progs/stars/binary_c
\end_layout
\end_inset
, and other software will be downloaded and built in
\begin_inset Flex File
status open
\begin_layout Plain Layout
$HOME/git
\end_layout
\end_inset
.
\end_layout
\begin_layout Itemize
\series bold
Required
\series default
(Do this once) Add to your
\begin_inset Flex File
status open
\begin_layout Plain Layout
.bashrc
\end_layout
\end_inset
or equivalent shell profile
\begin_inset listings
inline falsestatus open
\begin_layout Plain Layout
export BINARY_C=$HOME/progs/stars/binary_c
\end_layout
\end_inset
and
\emph on
\series bold
restart your shell
\series default
\emph default
so that the environment variable
\begin_inset Flex Envvar
status open
\begin_layout Plain Layout
BINARY_C
\end_layout
\end_inset
is defined.
\end_layout
\begin_layout Itemize
\series bold
Required
\series default
(Do this once in
\begin_inset Flex File
status open
\begin_layout Plain Layout
.bashrc
\end_layout
\end_inset
or manually every time) Set up
\begin_inset Flex Envvar
status open
\begin_layout Plain Layout
LIBRARY_PATH
\end_layout
\end_inset
,
\begin_inset Flex Envvar
status open
\begin_layout Plain Layout
LD_LIBRARY_PATH
\end_layout
\end_inset
and
\begin_inset Flex Envvar
status open
\begin_layout Plain LayoutPATH
\end_layout
\end_inset
in
\begin_inset Flex File
status open
\begin_layout Plain Layout
.bashrc
\end_layout
\end_inset
.
For example, add the following to
\begin_inset Flex File
status open
\begin_layout Plain Layout
.bashrc
\end_layout
\end_inset
if you are using
\begin_inset Flex Software
status open
\begin_layout Plain Layout
bash
\end_layout
\end_inset
,
\begin_inset listings
inline false
status open
\begin_layout Plain Layout
export LD_LIBRARY_PATH=$HOME/lib:$BINARY_C/src
\end_layout
\begin_layout Plain Layout
export LIBRARY_PATH=$HOME/lib
\end_layout
\begin_layout Plain Layout
export PATH=$PATH:$HOME/bin
\end_layout
\end_inset
and
\series bold
\emph on
restart your shell
\series default
\emph default
.
\end_layout
\begin_layout Itemize
\series boldOptional
\series default
If you can, install
\begin_inset Flex Software
status open
\begin_layout Plain Layout
libbsd
\end_layout
\end_inset
– this is a system package so requires root access.
You will require the
\emph on
development
\emph default
version which contains the various header files, this is usually called
\begin_inset Flex Software
status open
\begin_layout Plain Layout
libbsd-dev
\end_layout
\end_inset
(or similar).
\begin_inset Flex Software
status open
\begin_layout Plain Layout
libbsd
\end_layout
\end_inset
is not required for
\begin_inset Formula $\binaryc$
\end_inset
but is useful and may speed up the code.
\end_layout
\begin_layout Itemize
\series bold
Probably required
\series default
Update your
\begin_inset Flex Software
status open
\begin_layout Plain Layout
meson
\end_layout
\end_inset
and
\begin_inset Flex Software
status open
\begin_layout Plain Layout
ninja
\end_layout
\end_inset
,
\begin_inset listings
inline false
status open
\begin_layout Plain Layout
pip3 install --upgrade meson
\end_layout
\begin_layout Plain Layout
pip3 install --upgrade ninja
\end_layout
\end_inset
\end_layout
\begin_layout Itemize
\series bold
Optional
\series default
If you can, install RGI's custom
\emph on
\begin_inset Flex Software
status open
\begin_layout Plain Layout
\emph off
GSL
\end_layout
\end_inset
\emph default
which has a few small fixes to make it behave better.
At present, the latest release is 2.6, please replace the 2.
\emph on
x
\emph default
with whatever is the latest version.
\begin_inset listings
inline false
status open
\begin_layout Plain Layout
export PREFIX=$HOME
\end_layout
\begin_layout Plain Layout
cd $HOME/git
\end_layout
\begin_layout Plain Layout
git clone gitlab@gitlab.eps.surrey.ac.uk:ri0005/GSL-RGI.git
\end_layout
\begin_layout Plain Layout
cd GSL-RGI/2.6
\end_layout
\begin_layout Plain Layout
./configure --prefix=$HOME
\end_layout
\begin_layout Plain Layout
make
\end_layout
\begin_layout Plain Layout
make install
\end_layout
\end_inset
\end_layout
\begin_layout Itemize
\series bold
Optional
\series default
If you can, install
\begin_inset Flex Software
status open
\begin_layout Plain Layout
librinterpolate
\end_layout
\end_inset
.
\begin_inset Formula $\binaryc$
\end_inset
includes a version of
\begin_inset Flex Software
status open
\begin_layout Plain Layout
librinterpolate
\end_layout
\end_inset
as a backup, but it's useful to build and install it so you get the latest
version.
\begin_inset listings
inline false
status open
\begin_layout Plain Layout
mkdir $HOME/lib $HOME/git
\end_layout
\begin_layout Plain Layout
cd $HOME/git
\end_layout
\begin_layout Plain Layout
git clone gitlab@gitlab.eps.surrey.ac.uk:ri0005/librinterpolate.git
\end_layout
\begin_layout Plain Layout
cd $HOME/git/librinterpolate
\end_layout
\begin_layout Plain Layout
meson --prefix=$HOME --buildtype=release builddir
\end_layout
\begin_layout Plain Layout
ninja -C builddir install
\end_layout
\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"
thickness "0.4pt"
separation "3pt"
shadowsize "4pt"
framecolor "black"
backgroundcolor "none"
status open
\begin_layout Plain Layout
Note: as of
\begin_inset Formula $\binarygrid2$
\end_inset
v2.17 you
\emph on
require
\emph default
\begin_inset Flex Software
status open
\begin_layout Plain Layout
librinterpolate
\end_layout
\end_inset
for the
\begin_inset Flex Perlmodule
status open
\begin_layout Plain Layout
distribution_functions
\end_layout
\end_inset
module and hence for
\begin_inset Formula $\binarygrid2$
\end_inset
to work.
\end_layout
\end_inset
\end_layout
\begin_layout Itemize
\series bold
Optional
\series default
If you can, install
\begin_inset Flex Software
status open
\begin_layout Plain Layout
libmemoize
\end_layout
\end_inset
.
\begin_inset Formula $\binaryc$
\end_inset
includes a version of
\begin_inset Flex Software
status open
\begin_layout Plain Layout
libmemoize
\end_layout
\end_inset
as a backup, but it's useful to build and install it so you get the latest
version.
\begin_inset listings
inline false
status open
\begin_layout Plain Layout
mkdir $HOME/lib $HOME/git
\end_layout
\begin_layout Plain Layout
cd $HOME/git
\end_layout
\begin_layout Plain Layout
git clone gitlab@gitlab.eps.surrey.ac.uk:ri0005/libmemoize.git
\end_layout
\begin_layout Plain Layout
cd $HOME/git/libmemoize
\end_layout
\begin_layout Plain Layout
meson --prefix=$HOME --buildtype=release builddir
\end_layout
\begin_layout Plain Layout
ninja -C builddir install
\end_layout
\end_inset
\end_layout
\begin_layout Itemize
\series bold
Optional
\series default
If you can, install
\begin_inset Flex Software
status open
\begin_layout Plain Layout
librchash
\end_layout
\end_inset
.
\begin_inset Formula $\binaryc$
\end_inset
includes a version of
\begin_inset Flex Software
status open
\begin_layout Plain Layout
librchash
\end_layout
\end_inset
as a backup, but it's useful to build and install it so you get the latest
version.
\begin_inset listings
inline false
status open
\begin_layout Plain Layout
mkdir $HOME/lib $HOME/git
\end_layout
\begin_layout Plain Layout
cd $HOME/git
\end_layout
\begin_layout Plain Layout
git clone gitlab@gitlab.eps.surrey.ac.uk:ri0005/librchash.git
\end_layout
\begin_layout Plain Layout
cd $HOME/git/librchash
\end_layout
\begin_layout Plain Layout
meson builddir --prefix=$HOME --buildtype=release
\end_layout
\begin_layout Plain Layout
ninja -C builddir install
\end_layout
\end_inset
\end_layout
\begin_layout Itemize
\series bold
Required
\series default
Clone the
\begin_inset Formula $\mainbranch$
\end_inset
branch of
\begin_inset Formula $\binaryc$
\end_inset
.
\begin_inset listings
inline false
status open
\begin_layout Plain Layout
export CC=gcc # or the compiler of your choice
\end_layout
\begin_layout Plain Layout
unset CFLAGS
\end_layout
\begin_layout Plain Layout
mkdir -p $HOME/progs/stars/
\end_layout
\begin_layout Plain Layout
cd $HOME/progs/stars
\end_layout
\begin_layout Plain Layout
git clone gitlab@gitlab.eps.surrey.ac.uk:ri0005/binary_c.git
\end_layout
\end_inset
\end_layout
\begin_layout Itemize
\series bold
Required
\series default Change to the
\begin_inset Formula $\binaryc$
\end_inset
directory, configure and build both
\begin_inset Formula $\binaryc$
\end_inset
and its shared library.
Note: if
\begin_inset Flex File
status open
\begin_layout Plain Layout
builddir
\end_layout
\end_inset
already exists, you need to add
\begin_inset listings
inline true
status open
\begin_layout Plain Layout
--reconfigure
\end_layout
\end_inset
to the
\begin_inset Flex Software
status open
\begin_layout Plain Layout
Meson
\end_layout
\end_inset
command, or delete
\begin_inset Flex File
status open
\begin_layout Plain Layout
builddir
\end_layout
\end_inset
before this step.
\begin_inset listings
inline false
status open
\begin_layout Plain Layout
cd $BINARY_C
\end_layout
\begin_layout Plain Layout
meson builddir --buildtype=release
\end_layout
\begin_layout Plain Layout
ninja -C builddir binary_c_install \end_layout
\begin_layout Plain Layout
cd ..
\end_layout
\end_inset
\begin_inset Formula $\binaryc$
\end_inset
is now installed
\end_layout
\begin_layout Itemize
\series bold
Optional
\series default
If you want to use
\begin_inset Formula $\binarygrid$
\end_inset
:
\end_layout
\begin_deeper
\begin_layout Itemize
Install
\begin_inset Flex Software
status open
\begin_layout Plain Layout
perlbrew
\end_layout
\end_inset
which is your own, custom
\begin_inset Flex Software
status open
\begin_layout Plain Layout
Perl
\end_layout
\end_inset
.
\begin_inset listings
inline false
status open
\begin_layout Plain Layout
wget --no-check-certificate -O - http://install.perlbrew.pl | bash
\end_layout
\begin_layout Plain Layout
export NTHREADS=`cat /proc/cpuinfo |grep cpu
\backslash
famil|wc -l`
\end_layout
\begin_layout Plain Layout
export LATEST_PERL=`perlbrew available | grep
\begin_inset Quotes eld
\end_inset
^[[:space:]]
\backslash
+perl
\begin_inset Quotes erd
\end_inset
| head -1`
\end_layout
\begin_layout Plain Layout
perlbrew -v install $LATEST_PERL --thread --multi --64bitall --notest -Dusethrea
ds -Duselargefiles -Dcccdlflags=-fPIC -Dpager=/usr/bin/sensible-pager -Doptimize
="-O3 -mtune=generic" -Duseshrplib -j $NTHREADS
\end_layout
\end_inset
If you have problems with
\begin_inset Flex Software
status open
\begin_layout Plain Layout
\emph off
wget
\end_layout
\end_inset
, try removing the
\begin_inset Flex Args
status open
\begin_layout Plain Layout
–no-check-certificate
\end_layout
\end_inset
.
\begin_inset Newline newline
\end_inset
\begin_inset Flex Software
status open
\begin_layout Plain Layout
Perl
\end_layout
\end_inset
will, on completion of the build (which takes a little while), tell you
to append some expressions to your shell profile (e.g.
\begin_inset space ~
\end_inset
\begin_inset Flex File
status open
\begin_layout Plain Layout
.bashrc\end_layout
\end_inset
).
Do this, and then
\series bold
\emph on
restart your shell
\series default
\emph default
.
\end_layout
\begin_layout Itemize
Switch to using the new
\begin_inset Flex Software
status open
\begin_layout Plain Layout
Perl
\end_layout
\end_inset
, and install
\begin_inset Flex Software
status open
\begin_layout Plain Layout
cpanminus
\end_layout
\end_inset
(which is the command
\begin_inset Flex Command
status open
\begin_layout Plain Layout
cpanm
\end_layout
\end_inset
)
\begin_inset listings
inline false
status open
\begin_layout Plain Layout
perlbrew switch $LATEST_PERL
\end_layout
\begin_layout Plain Layout
perlbrew install-cpanm
\end_layout
\end_inset
\end_layout
\begin_layout Itemize
Install
\begin_inset Formula $\binarygrid2$
\end_inset
\begin_inset listings
inline false
status open
\begin_layout Plain Layout
cd $BINARY_C
\end_layout
\begin_layout Plain Layout
cd src/perl
\end_layout
\begin_layout Plain Layout
./install_modules.pl
\end_layout
\end_inset
you may well need to run the
\begin_inset Flex Software
status open
\begin_layout Plain Layout
install_modules.pl
\end_layout
\end_inset
script repeatedly to satisfy dependencies, or if there is a failure check
the error message and install the module manually using the
\begin_inset Flex Software
status open
\begin_layout Plain Layout
cpanm
\end_layout
\end_inset
command.
\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
\begin_layout Standard
Go to the
\begin_inset Flex Envvar
status open
\begin_layout Plain Layout
$BINARY_C
\end_layout
\end_inset
directory and open the
\begin_inset Flex Software
status open
\begin_layout Plain Layout
bash
\end_layout
\end_inset
script
\begin_inset Flex File
status open
\begin_layout Plain Layout
tbse
\end_layout
\end_inset
where \emph on
tbse
\emph default
means
\begin_inset Quotes eld
\end_inset
test binary-star evolution
\begin_inset Quotes erd
\end_inset
.
\end_layout
\begin_layout Itemize
In this file you can set every physical parameter of
\begin_inset Formula $\binaryc$
\end_inset
, for example the masses and orbital parameters
\begin_inset listings
inline false
status open
\begin_layout Plain Layout
# stellar masses (solar units)
\end_layout
\begin_layout Plain Layout
M1=6
\end_layout
\begin_layout Plain Layout
M2=0.9
\end_layout
\begin_layout Plain Layout
\end_layout
\begin_layout Plain Layout
# orbit:
\end_layout
\begin_layout Plain Layout
# If the period (days) is given, use it.
\end_layout
\begin_layout Plain Layout
# If the period is zero, use the separation (in Rsun) to calculate the period.
\end_layout
\begin_layout Plain Layout
# (this requires that the masses are already set)
\end_layout
\begin_layout Plain Layout
ORBITAL_PERIOD=0.0
\end_layout
\begin_layout Plain Layout
ORBITAL_SEPARATION=3000.0
\end_layout
\begin_layout Plain Layout
\end_layout
\begin_layout Plain Layout
# Orbital eccentricity should be in the range 0.0-1.0.
\end_layout
\begin_layout Plain Layout
ECCENTRICITY=0.0
\end_layout
\end_inset
\end_layout
\begin_layout Itemize
You can also override physics by running tbse with subsequent command-line
arguments, e.g., to run the default star with a metallicity of
\begin_inset Formula $0.004$
\end_inset
:
\begin_inset listings
inline false
status open
\begin_layout Plain Layout
tbse metallicity 0.004
\end_layout
\end_inset
\end_layout
\begin_layout Itemize
Do not run many stars this way, use
\begin_inset Formula $\binarygrid2$
\end_inset
or
\begin_inset Formula $\binarycpython$
\end_inset
for such a task.
\end_layout
\begin_layout Subsection
Running a grid of stars with
\begin_inset Formula $\binarygrid2$
\end_inset
\end_layout
\begin_layout Itemize
Open the file
\begin_inset Flex File
status open
\begin_layout Plain Layout
$BINARY_C/src/perl/scripts2/template.pl
\end_layout
\end_inset
\end_layout
\begin_layout Itemize
This is an example of how to run
\begin_inset Formula $\binarygrid2$
\end_inset
to extract data from a grid of stars.
You set up a grid of stars as a $population object, and then call that
to set up the physics and run the grid.
\end_layout
\begin_layout Itemize
To make a new population which evolves to
\begin_inset Formula $15000\,\mathrm{Myr}$
\end_inset
with metallicity
\begin_inset Formula $Z=0.02$
\end_inset
, use
\begin_inset Flex Perlscript
status open
\begin_layout Plain Layout
binary_grid2->new()
\end_layout
\end_inset
to make a population object
\begin_inset listings
inline false
status open
\begin_layout Plain Layout
# make a new stellar population
\end_layout
\begin_layout Plain Layout
my $population = binary_grid2->new(
\end_layout
\begin_layout Plain Layout
# options can be given now ...
\end_layout
\begin_layout Plain Layout
metallicity => 0.02, # mass fraction of "metals"
\end_layout
\begin_layout Plain Layout
max_evolution_time => 15000, # Myr
\end_layout
\begin_layout Plain Layout
);
\end_layout
\end_inset
\end_layout
\begin_layout Itemize
To set parameters of an existing population, call
\begin_inset Flex Perlscript
status open
\begin_layout Plain Layout
$population->set()
\end_layout
\end_inset
\begin_inset listings
inline false
status open
\begin_layout Plain Layout
$population->set(
\end_layout
\begin_layout Plain Layout
vb=>1, # turn on verbose logging (can be 0,1,2...)
\end_layout
\begin_layout Plain Layout
return_array_refs=>1, # quicker data parsing mode
\end_layout
\begin_layout Plain Layout
log_args=>1,
\end_layout
\begin_layout Plain Layout
sort_args=>1,
\end_layout
\begin_layout Plain Layout
save_args=>1,
\end_layout
\begin_layout Plain Layout
log_args_dir=>'/tmp',
\end_layout
\begin_layout Plain Layout
C_auto_logging => {
\end_layout
\begin_layout Plain Layout
'MY_STELLAR_DATA' =>
\end_layout
\begin_layout Plain Layout
[
\end_layout
\begin_layout Plain Layout
'model.time',
\end_layout
\begin_layout Plain Layout
'star[0].mass',
\end_layout
\begin_layout Plain Layout
'model.probability',
\end_layout
\begin_layout Plain Layout
'model.dt'
\end_layout
\begin_layout Plain Layout
]
\end_layout
\begin_layout Plain Layout
},
\end_layout
\begin_layout Plain Layout
);
\end_layout
\end_inset
\end_layout
\begin_layout Itemize
To set up the grid, with is
\begin_inset Formula $N$
\end_inset
-dimensional, just call
\begin_inset Flex Perlscript
status open
\begin_layout Plain Layout
add_grid_variable()
\end_layout
\end_inset
for each dimension, for example to set up primary masses in a logarithmic
grid between
\begin_inset Formula $0.1$
\end_inset
and
\begin_inset Formula $50\mathrm{\,M_{\odot}}$
\end_inset
distributed according to Kroupa's 2001 initial mass function.
\begin_inset listings
inline false
status open
\begin_layout Plain Layout
$population->add_grid_variable
\end_layout
\begin_layout Plain Layout
(
\end_layout
\begin_layout Plain Layout
'name' => 'lnm1',
\end_layout
\begin_layout Plain Layout
'longname' =>'Primary mass',
\end_layout
\begin_layout Plain Layout
'range' =>[log(0.1),log(50)],
\end_layout
\begin_layout Plain Layout
'resolution' => 100,
\end_layout
\begin_layout Plain Layout
'spacingfunc'=>"const(log($mmin),log($mmax),$resolution->{m1})",
\end_layout
\begin_layout Plain Layout
'precode' =>'$m1=exp($lnm1);',
\end_layout
\begin_layout Plain Layout
'probdist' =>'Kroupa2001($m1)*$m1',
\end_layout
\begin_layout Plain Layout
'dphasevol' =>'$dlnm1',
\end_layout
\begin_layout Plain Layout
);
\end_layout
\end_inset
\end_layout
\begin_layout Itemize
To analyse the data output from
\begin_inset Formula $\binaryc$
\end_inset
and do something useful with it, set up a
\begin_inset Flex Perlscript
status open
\begin_layout Plain Layout
parse_data()
\end_layout
\end_inset
function.
In this case, we save to the results hash stored in
\begin_inset Flex Perlscript
status open
\begin_layout Plain Layout
$results
\end_layout
\end_inset
.
Each thread contains part of the results, and all the results are automatically
combined at the end of the population run.
\begin_inset listings
inline false
status open
\begin_layout Plain Layout
# link population to custom data parser function
\end_layout
\begin_layout Plain Layout
$population->set(
\end_layout
\begin_layout Plain Layout
parse_bse_function_pointer =>
\backslash
&main::parse_data
\end_layout
\begin_layout Plain Layout
);
\end_layout
\begin_layout Plain Layout
\end_layout
\begin_layout Plain Layout
sub parse_data
\end_layout
\begin_layout Plain Layout
{
\end_layout
\begin_layout Plain Layout
my ($population, $results) = @_;
\end_layout
\begin_layout Plain Layout
\end_layout
\begin_layout Plain Layout
while(1)
\end_layout
\begin_layout Plain Layout
{
\end_layout
\begin_layout Plain Layout
# subsequent calls to tbse_line contain
\end_layout
\begin_layout Plain Layout
# (references to) arrays of data
\end_layout
\begin_layout Plain Layout
my $la = $population->tbse_line();
\end_layout
\begin_layout Plain Layout
\end_layout
\begin_layout Plain Layout
# first element is the "header" line
\end_layout
\begin_layout Plain Layout
my $header = shift @$la;
\end_layout
\begin_layout Plain Layout
\end_layout
\begin_layout Plain Layout
# break out of the look if this is 'fin'
\end_layout
\begin_layout Plain Layout
last if ($header eq 'fin');
\end_layout
\begin_layout Plain Layout
\end_layout
\begin_layout Plain Layout
if($header eq 'MY_STELLAR_DATA')
\end_layout
\begin_layout Plain Layout
{\end_layout
\begin_layout Plain Layout
# matched MY_STELLAR_DATA header
\end_layout
\begin_layout Plain Layout
my $time = $la->[0];
\end_layout
\begin_layout Plain Layout
my $mass = $la->[1];
\end_layout
\begin_layout Plain Layout
my $probability = $la->[2];
\end_layout
\begin_layout Plain Layout
my $timestep = $la->[3];
\end_layout
\begin_layout Plain Layout
\end_layout
\begin_layout Plain Layout
# bin mass to nearest 1.0 Msun
\end_layout
\begin_layout Plain Layout
$mass = $population->rebin($mass, 1.0);
\end_layout
\begin_layout Plain Layout
\end_layout
\begin_layout Plain Layout
# add up the initial mass function
\end_layout
\begin_layout Plain Layout
if($time == 0.0)
\end_layout
\begin_layout Plain Layout
{
\end_layout
\begin_layout Plain Layout
$results->{initial_mass_function}->{$mass} += $probability;
\end_layout
\begin_layout Plain Layout
}
\end_layout
\begin_layout Plain Layout
\end_layout
\begin_layout Plain Layout
# add up the mass distribution
\end_layout
\begin_layout Plain Layout
$results->{mass_distribution}->{$mass} += $probability * $timestep;
\end_layout
\begin_layout Plain Layout
}
\end_layout
\begin_layout Plain Layout
}
\end_layout
\begin_layout Plain Layout
}
\end_layout
\end_inset
\end_layout
\begin_layout Itemize
To run the population, call
\begin_inset Flex Perlscript
status open
\begin_layout Plain Layout
evolve()
\end_layout
\end_inset
\begin_inset listings
inline false
status open
\begin_layout Plain Layout
# evolution the stellar population (this takes some time)
\end_layout
\begin_layout Plain Layout
$population->evolve();
\end_layout
\end_inset
\end_layout
\begin_layout Itemize
To output information, loop through the
\begin_inset Flex Perlscriptstatus open
\begin_layout Plain Layout
$results
\end_layout
\end_inset
hash.
In this case we output to the screen both the initial mass function (with
lines headed by
\emph on
IMF
\emph default
) and time-dependent mass function (lines headed by
\emph on
MASS
\emph default
).
Naturally, you should save this data to a file if you want to further process
it.
\begin_inset listings
inline false
status open
\begin_layout Plain Layout
sub output
\end_layout
\begin_layout Plain Layout
{
\end_layout
\begin_layout Plain Layout
my ($population) = @_;
\end_layout
\begin_layout Plain Layout
\end_layout
\begin_layout Plain Layout
# $results is a hash reference containing
\end_layout
\begin_layout Plain Layout
# the results that were added up in parse_data()
\end_layout
\begin_layout Plain Layout
my $results = $population->results;
\end_layout
\begin_layout Plain Layout
\end_layout
\begin_layout Plain Layout
# output the initial mass function
\end_layout
\begin_layout Plain Layout
foreach my $mass (sort {$a<=>$b} keys %{$results->{initial_mass_function}})
\end_layout
\begin_layout Plain Layout
{
\end_layout
\begin_layout Plain Layout
printf "IMF %g %g
\backslash
n",$mass,$results->{initial_mass_function}->{$mass};
\end_layout
\begin_layout Plain Layout
}
\end_layout
\begin_layout Plain Layout
\end_layout
\begin_layout Plain Layout
# output the mass distribution
\end_layout
\begin_layout Plain Layout
foreach my $mass (sort {$a<=>$b} keys %{$results->{mass_distribution}})
\end_layout
\begin_layout Plain Layout
{
\end_layout
\begin_layout Plain Layout
printf "MASS %g %g
\backslash
n",$mass,$results->{mass_distribution}->{$mass};
\end_layout
\begin_layout Plain Layout
}
\end_layout
\begin_layout Plain Layout
}
\end_layout
\begin_layout Plain Layout
\end_layout
\end_inset
\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"
literal "true"
\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"
literal "true"
\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
A recent review of binary stars can be found in
\begin_inset CommandInset citation
LatexCommand citet
key "2017PASA...34....1D"
literal "false"
\end_inset
.
\end_layout
\begin_layout Standard
To investigate the effect of a companion on stellar nucleosynthesis the
\family roman
\emph on
\begin_inset Formula $\binaryc$
\end_inset
\family default
\emph default
code was developed.
The
\emph on
\begin_inset Formula $\binaryc$
\end_inset
\emph default
code currently uses the
\emph on
SSE/BSE
\emph default
package at its core to provide most of the stellar evolution modeling,
with nucleosynthesis in parallel based on various algorithms, to explore
the large parameter spaces associated with binary stars in reasonable periods
of time.
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 Roche-lobe overflow caused by interaction between a giant
branch or asymptotic giant branch (GB/AGB) star and a main-sequence (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, type Ia supernoave, X-ray bursts, stellar mergers (including neutron-star
/black-hole mergers), etc.
occur in binaries, as do many tidal disruption events.
These may eject material or lead to extra nuclear burning.
\end_layout
\begin_layout Standard
The physics of binary evolution is not all that well understood and, at
the same time, suffers all the uncertainties of single-star evolution.
Some effects which must be considered are:
\end_layout
\begin_layout Itemize
Duplicity: is the star single or binary or perhaps even triple or quadruple?
\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 mixture 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 in
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!).
This problem is very much open
\begin_inset CommandInset citation
LatexCommand citep
key "2012IAUS..283...95I,2013A&ARv..21...59I"
literal "false"
\end_inset
.
\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
\begin_inset Formula $\binaryc$
\end_inset
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"
literal "true"
\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,2009A&A...508.1359I,2018MNRAS.473.2984I"
literal "true"
\end_inset
and many subsequent papers):
\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"
literal "true"
\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"
literal "true"
\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"
literal "true"
\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"
literal "true"
\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"
literal "true"
\end_inset
.
\end_layout
\begin_layout Itemize
Nova yields fitted to
\begin_inset CommandInset citation
LatexCommand citet
key "1998ApJ...494..680J"
literal "true"
\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 and
Simmerer 2004.
\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.
\end_layout
\begin_layout Itemize
SN stripping of companions.
\end_layout
\begin_layout Standard
What does the
\begin_inset Formula $\binaryc$
\end_inset
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
(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 Subsection
\begin_inset Formula $\Binaryc$
\end_inset
: tools for stellar evolution and population synthesis
\end_layout
\begin_layout Standard
The
\begin_inset Formula $\binaryc$
\end_inset
software framework consists of a number of tools, in particular:
\end_layout
\begin_layout Description
\begin_inset Formula $\binaryc$
\end_inset
The
\begin_inset Formula $\binaryc$
\end_inset
code itself.
This is the core code, written in
\emph on
C
\emph default
, which contains the stellar evolution and nucleosynthesis algorithms.
\end_layout
\begin_layout Description
\begin_inset Formula $\libbinaryc$
\end_inset
The shared library based on
\begin_inset Formula $\binaryc$
\end_inset
which should be accessed through the
\begin_inset Formula $\binaryc$
\end_inset
API functions.
This works with other languages such as
\emph on
Python
\emph default
and
\emph on
FORTRAN
\emph default
.
\end_layout
\begin_layout Description
\begin_inset Formula $\binarygrid$
\end_inset
A suite of software to run many stars in a stellar population.
This is written in
\begin_inset Flex ScriptingLanguagestatus open
\begin_layout Plain Layout
Perl
\end_layout
\end_inset
because when I started there was no
\emph on
Python
\emph default
.
Sorry! But before you say
\begin_inset Quotes eld
\end_inset
oh but Perl is not Python
\begin_inset Quotes erd
\end_inset
– true, but it's a damned powerful language.
You only need it to run the populations: after that, you can process the
resulting data however you like (even in Excel if you want – but please
don't!).
\end_layout
\begin_layout Description
\begin_inset Formula $\binarycpython$
\end_inset
A port of
\begin_inset Formula $\binarygrid$
\end_inset
which, as of version 2.2.0, will become the default
\begin_inset Formula $\binaryc$
\end_inset
population synthesis tool.
\end_layout
\begin_layout Standard
\begin_inset Newpage pagebreak
\end_inset
\end_layout
\begin_layout Section
Installation
\end_layout
\begin_layout Standard
The following is an installation guide for installing
\begin_inset Formula $\binaryc$
\end_inset
and some of its support tools.
If you know how to run code, and want to run
\begin_inset Formula $\binaryc$
\end_inset
as quickly as possible, just go for the quick start guide.
If you want to get
\begin_inset Formula $\binaryc$
\end_inset
, either as source code, a virtual machine or Docker image, see section
\begin_inset space ~\end_inset
\begin_inset CommandInset ref
LatexCommand ref
reference "subsec:Getting-binary-c"
plural "false"
caps "false"
noprefix "false"
\end_inset
.
Technical system requirements are discussed in section
\begin_inset space ~
\end_inset
\begin_inset CommandInset ref
LatexCommand ref
reference "subsec:system-requirements"
plural "false"
caps "false"
noprefix "false"
\end_inset
.
Building
\begin_inset Formula $\binaryc$
\end_inset
is described in section
\begin_inset space ~
\end_inset
\begin_inset CommandInset ref
LatexCommand ref
reference "subsec:Building"
plural "false"
caps "false"
noprefix "false"
\end_inset
.
\end_layout
\begin_layout Standard
The
\begin_inset Formula $\binarygrid$
\end_inset
software is described in section
\begin_inset space ~
\end_inset
\begin_inset CommandInset ref
LatexCommand ref
reference "subsec:installing binary_grid"
plural "false"
caps "false"
noprefix "false"
\end_inset
.
\end_layout
\begin_layout Subsection
Quick start
\end_layout
\begin_layout Standard
See Sec.
\begin_inset space ~
\end_inset
\begin_inset CommandInset ref
LatexCommand ref
reference "sec:Quick-start-guide"
plural "false"
caps "false"
noprefix "false"
\end_inset
.
\end_layout
\begin_layout Subsection
Getting
\begin_inset Formula $\binaryc$
\end_inset
\begin_inset CommandInset label
LatexCommand label
name "subsec:Getting-binary-c"
\end_inset
\end_layout
\begin_layout Standard
You can either get the
\begin_inset Formula $\binaryc$
\end_inset
source code, and build it yourself, or use the prebuilt
\begin_inset Flex Software
status open
\begin_layout Plain Layout
Docker
\end_layout
\end_inset
\emph on
\emph default
image.
\end_layout
\begin_layout Standard
\begin_inset CommandInset include
LatexCommand input
filename "getting_binary_c.lyx"
\end_inset
\end_layout
\begin_layout Subsection
System Requirements
\end_layout
\begin_layout Standard
\begin_inset CommandInset label
LatexCommand label
name "subsec:system-requirements"
\end_inset
In the following I assume you are using a
\begin_inset Flex OS
status open
\begin_layout Plain Layout
Linux
\end_layout
\end_inset
-type system (e.g
\begin_inset space ~
\end_inset
running an distribution like
\begin_inset Flex OS
status open
\begin_layout Plain Layout
Ubuntu
\end_layout
\end_inset
).
If you are not, I highly recommend using a virtual machine (e.g.
\begin_inset space ~
\end_inset
\begin_inset Flex Software
status open
\begin_layout Plain Layout
Virtualbox
\end_layout
\end_inset
) to run
\begin_inset Flex OS
status open
\begin_layout Plain Layout
Linux
\end_layout
\end_inset
on your system.
\begin_inset Flex OS
status open
\begin_layout Plain Layout
MacOSX
\end_layout
\end_inset
and
\begin_inset Flex OS
status open
\begin_layout Plain Layout
Windows
\end_layout
\end_inset
have a quite different build structure compared to
\begin_inset Flex OS
status open
\begin_layout Plain Layout
Linux
\end_layout
\end_inset
, please see Section
\begin_inset space ~
\end_inset
\begin_inset CommandInset ref
LatexCommand ref
reference "subsec:binaryc-on-MacOSX"
plural "false"
caps "false"
noprefix "false"
\end_inset
for OSX-specific advice.
You can also run the
\emph on
\begin_inset Flex Software
status open
\begin_layout Plain Layout
\emph off
Docker
\end_layout
\end_inset
\emph default
directly on
\begin_inset Flex OS
status open
\begin_layout Plain Layout
MacOSX
\end_layout
\end_inset
.
\end_layout
\begin_layout Standard
To build
\begin_inset Formula $\binaryc$
\end_inset
from source, the following software is required on your system:
\end_layout
\begin_layout Itemize
A
\emph on
\begin_inset Flex ProgrammingLanguage
status open
\begin_layout Plain Layout
\emph on
C
\end_layout
\end_inset
\emph default
compiler e.g.
\begin_inset space ~
\end_inset
one of,
\begin_inset Separator latexpar
\end_inset
\end_layout
\begin_deeper
\begin_layout Itemize
\begin_inset Flex Software
status open
\begin_layout Plain Layout
gcc
\end_layout
\end_inset
(the
\emph on
GNU
\emph default
compiler
\begin_inset CommandInset href
LatexCommand href
target "http://gcc.gnu.org/"
\end_inset
) this comes as standard on most
\begin_inset Flex OS
status open
\begin_layout Plain Layout
Linux
\end_layout
\end_inset
and
\begin_inset Flex OS
status open
\begin_layout Plain Layout
MacOSX
\end_layout
\end_inset
systems and is easily installed on others, and is free software.
\end_layout
\begin_layout Itemize
\begin_inset Flex Software
status open
\begin_layout Plain Layout
clang
\end_layout
\end_inset
(
\emph on
C
\emph default
compiler for
\begin_inset Flex Software
status open
\begin_layout Plain Layout
LLVM
\end_layout
\end_inset
\begin_inset CommandInset href
LatexCommand href
target "http://clang.llvm.org/"
literal "false"
\end_inset
) is also free, and may be faster than
\begin_inset Flex Software
status open
\begin_layout Plain Layout
gcc
\end_layout
\end_inset
\emph on
.
\end_layout
\begin_layout Itemize
\begin_inset Flex Software
status open
\begin_layout Plain Layout
icc
\end_layout
\end_inset
(Intel compiler
\begin_inset CommandInset href
LatexCommand href
target "http://software.intel.com/en-us/articles/intel-compilers/"
\end_inset
) this costs money but it is probably faster than
\begin_inset Flex Software
status open
\begin_layout Plain Layout
\emph off
gcc
\end_layout
\end_inset
.
\end_layout
\begin_layout Standard
Your system should include such a compiler unless you're using
\begin_inset Flex OS
status open
\begin_layout Plain Layout
Windows
\end_layout
\end_inset
.
\emph on
\begin_inset Formula $\Binaryc$
\end_inset
\emph default
has been tested on
\begin_inset Flex OS
status open
\begin_layout Plain Layout
Linux
\end_layout
\end_inset
,
\begin_inset Flex OS
status open
\begin_layout Plain Layout
Solaris
\end_layout
\end_inset
,
\begin_inset Flex OS
status open
\begin_layout Plain Layout
Windows
\end_layout
\end_inset
(using Windows Subsystem for Linux) and
\begin_inset Flex OS
status open
\begin_layout Plain LayoutMacOSX
\end_layout
\end_inset
.
\end_layout
\end_deeper
\begin_layout Itemize
Standard build tools and system commands, such as
\begin_inset Flex Command
status open
\begin_layout Plain Layout
make
\end_layout
\end_inset
,
\begin_inset Flex Command
status open
\begin_layout Plain Layout
tr
\end_layout
\end_inset
,
\begin_inset Flex Command
status open
\begin_layout Plain Layout
sed
\end_layout
\end_inset
,
\begin_inset Flex Command
status open
\begin_layout Plain Layout
head
\end_layout
\end_inset
,
\begin_inset Flex Command
status open
\begin_layout Plain Layout
tail
\end_layout
\end_inset
,
\begin_inset Flex Command
status open
\begin_layout Plain Layout
cd
\end_layout
\end_inset
,
\begin_inset Flex Command
status open
\begin_layout Plain Layout
which
\end_layout
\end_inset
,
\begin_inset Flex Command
status open
\begin_layout Plain Layout
grep
\end_layout
\end_inset
,
\begin_inset Flex Command
status open
\begin_layout Plain Layout
gawk
\end_layout
\end_inset
,
\begin_inset Flex Command
status open
\begin_layout Plain Layout
cp
\end_layout
\end_inset
,
\begin_inset Flex Command
status open
\begin_layout Plain Layout
ln
\end_layout
\end_inset
,
\begin_inset Flex Command
status open
\begin_layout Plain Layout
wc
\end_layout
\end_inset
,
\begin_inset Flex Command
status open
\begin_layout Plain Layout
env
\end_layout
\end_inset
,
\begin_inset Flex Command
status open
\begin_layout Plain Layout
ls
\end_layout
\end_inset
,
\begin_inset Flex Command
status open
\begin_layout Plain Layout
rm
\end_layout
\end_inset
,
\begin_inset Flex Command
status open
\begin_layout Plain Layout
objdump
\end_layout
\end_inset
and
\begin_inset Flex Command
status open
\begin_layout Plain Layout
objcopy
\end_layout
\end_inset
.
I will also assume you are using the
\begin_inset Flex Command
status open
\begin_layout Plain Layout
bash
\end_layout
\end_inset
shell.
These are all available as system packages in
\begin_inset Flex OS
status open
\begin_layout Plain Layout
Linux
\end_layout
\end_inset
and other Unix variants, such as
\begin_inset Flex OS
status open
\begin_layout Plain Layout
MacOSX
\end_layout
\end_inset
(please install the GNU core utils and see Section
\begin_inset space ~
\end_inset
\begin_inset CommandInset ref
LatexCommand ref
reference "subsec:binaryc-on-MacOSX"
plural "false"
caps "false"
noprefix "false"
\end_inset
), e.g.
\begin_inset space ~
\end_inset
the
\begin_inset Flex Software
status open
\begin_layout Plain Layout
coreutils
\end_layout
\end_inset
,
\begin_inset Flex Software
status open
\begin_layout Plain Layout
binutils
\end_layout
\end_inset
,
\begin_inset Flex Software
status open
\begin_layout Plain Layout
bash
\end_layout
\end_inset
and
\begin_inset Flex Software
status open
\begin_layout Plain Layout
build-essential
\end_layout
\end_inset
packages on
\begin_inset Flex OS
status open
\begin_layout Plain Layout
Ubuntu
\end_layout
\end_inset
.
\end_layout
\begin_layout Itemize
\begin_inset Flex ScriptingLanguage
status open
\begin_layout Plain Layout
Python
\end_layout
\end_inset
,
\begin_inset Flex Software
status open
\begin_layout Plain Layout
\emph off
meson
\end_layout
\end_inset
and
\begin_inset Flex Software
status open
\begin_layout Plain Layout
\emph off
ninja
\end_layout
\end_inset
.
You can install these tools on your system, or follow installation instructions
at
\begin_inset CommandInset href
LatexCommand href
target "https://mesonbuild.com/Getting-meson.html"
literal "false"
\end_inset
.
You should make sure you have
\begin_inset Flex Software
status open
\begin_layout Plain Layout
\emph off
meson
\end_layout
\end_inset
V0.52.0 or later.
If you have
\begin_inset Flex ScriptingLanguage
status open
\begin_layout Plain Layout
Python3
\end_layout
\end_inset
installed, you can get the latest versions of
\begin_inset Flex Software
status open
\begin_layout Plain Layout
\emph off
meson
\end_layout
\end_inset
and
\begin_inset Flex Software
status open
\begin_layout Plain Layout
\emph off
ninja
\end_layout
\end_inset
with,
\begin_inset listings
inline false
status open
\begin_layout Plain Layout
pip3 install meson
\end_layout
\begin_layout Plain Layout
pip3 install ninja
\end_layout
\end_inset
or, if these modules are already installed,
\begin_inset listings
inline false
status open
\begin_layout Plain Layout
pip3 install --upgrade meson
\end_layout
\begin_layout Plain Layout
pip3 install --upgrade ninja
\end_layout
\end_inset
Note:
\begin_inset Flex Software
status open
\begin_layout Plain Layout
emacs
\end_layout
\end_inset
users should install the
\begin_inset Flex Software
status open
\begin_layout Plain Layout
meson-mode
\end_layout
\end_inset
.
Go to
\begin_inset CommandInset href
LatexCommand href
target "https://github.com/wentasah/meson-mode"
literal "false"
\end_inset
and download
\begin_inset Flex File
status open
\begin_layout Plain Layout
meson-mode.el
\end_layout
\end_inset
to your
\begin_inset Flex File
status open
\begin_layout Plain Layout
~/.emacs-el
\end_layout
\end_inset
directory.
In your
\begin_inset Flex File
status open
\begin_layout Plain Layout
~/.emacs
\end_layout
\end_inset
file add the following.
\begin_inset listings
inline false
status open
\begin_layout Plain Layout
; meson support
\end_layout
\begin_layout Plain Layout
(load "~/.emacs-el/meson-mode.el")
\end_layout
\end_inset
You can edit the
\begin_inset Flex File
status open
\begin_layout Plain Layout
meson-mode.el
\end_layout
\end_inset
to suit your needs: I changed the indentation from 2 to 4, for example.
\end_layout
\begin_layout Itemize
\begin_inset Flex ScriptingLanguage
status open
\begin_layout Plain Layout
Perl
\end_layout
\end_inset
- this is required for the
\emph on
\begin_inset Formula $\binarygrid2$
\end_inset
\emph default
software.
\begin_inset Flex ScriptingLanguage
status open
\begin_layout Plain Layout
Perl
\end_layout
\end_inset
is usually installed on your system, or you can download
\begin_inset Flex ScriptingLanguage
status open
\begin_layout Plain Layout
Perl
\end_layout
\end_inset
at
\begin_inset CommandInset href
LatexCommand href
name "www.perl.com"
literal "false"
\end_inset
, but I recommend
\begin_inset Flex Software
status open
\begin_layout Plain Layout
\emph off
Perlbrew
\end_layout
\end_inset
instead. Please try to use a version of
\begin_inset Flex ScriptingLanguage
status open
\begin_layout Plain Layout
Perl
\end_layout
\end_inset
that is 5.16 or later: 5.31.11 is currently the latest version and works
just fine.
\emph on
\begin_inset Newline newline
\end_inset
NOTE:
\emph default
\begin_inset Flex Software
status open
\begin_layout Plain Layout
\emph off
Perlbrew
\end_layout
\end_inset
and
\begin_inset Flex Software
status open
\begin_layout Plain Layout
cpanm
\end_layout
\end_inset
are
\emph on
essential
\emph default
if you want to use
\begin_inset Formula $\binarygrid2$
\end_inset
.
\end_layout
\begin_layout Itemize
You will want to use
\emph on
git
\emph default
to get
\emph on
\begin_inset Formula $\binaryc$
\end_inset
\emph default
, see the document
\emph on
getting_binary_c
\begin_inset space ~
\end_inset
\emph default
.
\end_layout
\begin_layout Itemize
You should install support libraries, e.g.
\begin_inset space ~
\end_inset
\begin_inset Flex Software
status open
\begin_layout Plain Layout
librchash
\end_layout
\end_inset
which is required for
\begin_inset Formula $\binarygrid2$
\end_inset
.
\end_layout
\begin_layout Standard
By using
\emph on
\begin_inset Formula $\binaryc$
\end_inset
\emph default
and
\emph on
\begin_inset Formula $\binarygrid$
\end_inset
\emph default
you are part of a community.
You are therefore jointly responsible for helping with the never-ending
process of improvement and bug fixing.
\emph on
\begin_inset Formula $\Binaryc$
\end_inset
\emph default
(and its
\begin_inset Flex ScriptingLanguage
status open
\begin_layout Plain Layout
Perl
\end_layout
\end_inset
modules, such as
\emph on
\begin_inset Formula $\binarygrid$\end_inset
\emph default
) is stored on a
\emph on
\emph default
\begin_inset Flex Software
status open
\begin_layout Plain Layout
git
\end_layout
\end_inset
server.
Please read the
\begin_inset Flex File
status open
\begin_layout Plain Layout
LICENCE
\end_layout
\end_inset
file before use.
\end_layout
\begin_layout Subsection
System recommendations
\end_layout
\begin_layout Standard
\begin_inset CommandInset label
LatexCommand label
name "subsec:System-recommendations"
\end_inset
\end_layout
\begin_layout Itemize
If you plan to modify
\emph on
\begin_inset Formula $\binaryc$
\end_inset
\emph default
you probably want a debugger of some sort.
\begin_inset Flex Software
status open
\begin_layout Plain Layout
Valgrind
\end_layout
\end_inset
and
\begin_inset Flex Software
status open
\begin_layout Plain Layout
\emph off
gdb
\end_layout
\end_inset
are both excellent, the former for detecting memory leaks and the latter
for backtracing, but both are very powerful and flexible tools.
\end_layout
\begin_layout Itemize
I highly recommend the use of
\begin_inset Flex Software
status open
\begin_layout Plain Layout
\emph off
ccache
\end_layout
\end_inset
to speed up builds.
You can usually install this as a system package, or see
\begin_inset CommandInset href
LatexCommand href
name "the ccache homepage"
target "https://ccache.dev/"
literal "false"
\end_inset
.
\end_layout
\begin_layout Itemize
If you can, install RGI's custom version of
\begin_inset Flex Software
status open
\begin_layout Plain Layout
GSL
\end_layout
\end_inset
which has a few small fixes to make it behave better.
At present, the latest release is 2.6, please replace the 2.
\emph on
x
\emph default
with whatever is the latest version (check at
\begin_inset Flex URL
status open
\begin_layout Plain Layout
https://gitlab.eps.surrey.ac.uk/ri0005/GSL-RGI
\end_layout
\end_inset
).
\begin_inset listings
inline false
status open
\begin_layout Plain Layout
export PREFIX=$HOME
\end_layout
\begin_layout Plain Layout
cd $HOME/git
\end_layout
\begin_layout Plain Layout
git clone gitlab@gitlab.eps.surrey.ac.uk:ri0005/GSL-RGI.git
\end_layout
\begin_layout Plain Layout
cd GSL-RGI/2.6
\end_layout
\begin_layout Plain Layout
./configure --prefix=$HOME
\end_layout
\begin_layout Plain Layout
make
\end_layout
\begin_layout Plain Layout
make install
\end_layout
\end_inset
\end_layout
\begin_layout Itemize
If you can, install
\begin_inset Flex Software
status open
\begin_layout Plain Layout
librinterpolate
\end_layout
\end_inset
.
\begin_inset listings
inline false
status open
\begin_layout Plain Layout
export PREFIX=$HOME
\end_layout
\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
\begin_layout Plain Layout
cd $HOME/git
\end_layout
\begin_layout Plain Layout
git clone gitlab@gitlab.eps.surrey.ac.uk:ri0005/librinterpolate.git
\end_layout
\begin_layout Plain Layout
cd $HOME/git/librinterpolate/src
\end_layout
\begin_layout Plain Layout
make
\end_layout
\begin_layout Plain Layout
make install
\end_layout
\begin_layout Plain Layout
unset CFLAGS
\end_layout
\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"
thickness "0.4pt"
separation "3pt"
shadowsize "4pt"
framecolor "black"
backgroundcolor "none"
status open
\begin_layout Plain Layout
Note: as of
\begin_inset Formula $\binarygrid2$
\end_inset
v2.17 you
\emph on
require\emph default
\begin_inset Flex Software
status open
\begin_layout Plain Layout
librinterpolate
\end_layout
\end_inset
for the
\begin_inset Flex Perlmodule
status open
\begin_layout Plain Layout
distribution_functions
\end_layout
\end_inset
module and hence for
\begin_inset Formula $\binarygrid2$
\end_inset
to work.
\end_layout
\end_inset
\end_layout
\begin_layout Itemize
If you can, install
\begin_inset Flex Software
status open
\begin_layout Plain Layout
libmemoize
\end_layout
\end_inset
.
\begin_inset listings
inline false
status open
\begin_layout Plain Layout
export PREFIX=$HOME
\end_layout
\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
\begin_layout Plain Layout
cd $HOME/git
\end_layout
\begin_layout Plain Layout
git clone gitlab@gitlab.eps.surrey.ac.uk:ri0005/libmemoize.git
\end_layout
\begin_layout Plain Layout
cd $HOME/git/libmemoize/src
\end_layout
\begin_layout Plain Layout
make
\end_layout
\begin_layout Plain Layout
make install
\end_layout
\begin_layout Plain Layout
unset CFLAGS
\end_layout
\end_inset
\end_layout
\begin_layout Itemize
If you can, install
\begin_inset Flex Software
status open
\begin_layout Plain Layout
librchash
\end_layout
\end_inset
(this requires
\begin_inset Flex Software
status open
\begin_layout Plain Layout
meson
\end_layout
\end_inset
and
\begin_inset Flex Software
status open
\begin_layout Plain Layout
ninja
\end_layout
\end_inset
).\begin_inset listings
inline false
status open
\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/git
\end_layout
\begin_layout Plain Layout
cd $HOME/git
\end_layout
\begin_layout Plain Layout
git clone gitlab@gitlab.eps.surrey.ac.uk:ri0005/librchash.git
\end_layout
\begin_layout Plain Layout
cd $HOME/git/librchash
\end_layout
\begin_layout Plain Layout
meson builddir --prefix=$HOME --buildtype release
\end_layout
\begin_layout Plain Layout
cd builddir
\end_layout
\begin_layout Plain Layout
ninja install
\end_layout
\end_inset
\end_layout
\begin_layout Subsection
Configuring and building
\begin_inset Formula $\binaryc$
\end_inset
\end_layout
\begin_layout Standard
\begin_inset CommandInset label
LatexCommand label
name "subsec:Building"
\end_inset
\end_layout
\begin_layout Subsubsection
From
\emph on
git
\end_layout
\begin_layout Standard
Assuming you have checked out your branch, a release or the trunk, from
the
\emph on
git
\emph default
repository (see Sec.
\begin_inset space ~
\end_inset
\begin_inset CommandInset ref
LatexCommand ref
reference "subsec:Getting-binary-c"
\end_inset
), go to that directory (which will be called the
\begin_inset Flex File
status open
\begin_layout Plain Layout
binary_c
\end_layout
\end_inset
directory below) and skip to
\begin_inset CommandInset ref
LatexCommand ref
reference "subsec:Configuration"
plural "false"
caps "false"
noprefix "false"
\end_inset
.
\end_layout
\begin_layout Subsubsection
From a
\emph on
zip
\emph default
file or tarball
\end_layout
\begin_layout Standard
If have been given a file
\begin_inset Flex Software
status open
\begin_layout Plain Layout
zip
\end_layout
\end_inset
file
\begin_inset Flex File
status open
\begin_layout Plain Layout
binary_c.zip
\end_layout
\end_inset
\family typewriter
,
\family default
or a tarball e.g.
\begin_inset space ~
\end_inset
\begin_inset Flex File
status open
\begin_layout Plain Layout
binary_c.tar.gz
\end_layout
\end_inset
or
\begin_inset Flex File
status open
\begin_layout Plain Layout
binary_c.tar.bz2
\end_layout
\end_inset
, you should copy it to a directory (hereafter
\begin_inset Flex File
status open
\begin_layout Plain Layout
binary_c
\end_layout
\end_inset
, usually I put everything in
\begin_inset Flex File
status open
\begin_layout Plain Layout
\begin_inset Formula $\sim$
\end_inset
/progs/stars/binary_c
\end_layout
\end_inset
where
\begin_inset Flex File
status open
\begin_layout Plain Layout
\begin_inset Formula $\sim$
\end_inset
\end_layout
\end_inset
is your home directory – if you put it there then all the scripts will
work) and
\begin_inset Flex Software
status open
\begin_layout Plain Layout
unzip
\end_layout
\end_inset
it with one of the following commands (depending on the type of file you
were given):
\end_layout
\begin_layout Standard
\family typewriter
\series bold
\begin_inset listings
lstparams "language=bash"
inline false
status open
\begin_layout Plain Layout
unzip binary_c.zip
\end_layout
\begin_layout Plain Layout
tar -xvf binary_c.tar.gz
\end_layout
\begin_layout Plain Layout
tar -xvf binary_c.tar.bz2
\end_layout
\end_inset
\end_layout
\begin_layout Standard
which will
\begin_inset Flex Software
status open
\begin_layout Plain Layout
unzip
\end_layout
\end_inset
the files in the appropriate places.
\end_layout
\begin_layout Subsubsection
Set up ccache (optional)
\end_layout
\begin_layout Standard
If you have
\begin_inset Flex Software
status open
\begin_layout Plain Layout
ccache
\end_layout
\end_inset
installed, you will need to set it up so that it works with precompiled
headers.
To do this, run the following command.
\begin_inset listings
lstparams "language=bash"
inline false
status open
\begin_layout Plain Layout
ccache --set-config=sloppiness=pch_defines,time_macros
\end_layout
\end_inset
\end_layout
\begin_layout Standard
Alternatively, if you are using
\begin_inset Flex Software
status open
\begin_layout Plain Layout
bash
\end_layout
\end_inset
as your shell and
\begin_inset Flex Software
status open
\begin_layout Plain Layout
ccache
\end_layout
\end_inset
is installed in
\begin_inset Flex File
status open
\begin_layout Plain Layout
binary_c
\end_layout
\end_inset
(the standard location in
\begin_inset Flex OS
status open
\begin_layout Plain Layout
Ubuntu Linux
\end_layout
\end_inset
, put the following in your
\begin_inset Flex File
status open
\begin_layout Plain Layout
.bashrc
\end_layout
\end_inset
to have
\begin_inset Flex Software
status open
\begin_layout Plain Layout
ccache
\end_layout
\end_inset
always behave as you wish.
\begin_inset listings
inline false
status open
\begin_layout Plain Layout
# use ccache if available
\end_layout
\begin_layout Plain Layout
if [[ -d /usr/lib/ccache ]]; then
\end_layout
\begin_layout Plain Layout
export PATH=/usr/lib/ccache/:$PATH
\end_layout
\begin_layout Plain Layout
export CCACHE_SLOPPINESS=pch_defines,time_macros
\end_layout
\begin_layout Plain Layout
fi
\end_layout
\end_inset
\end_layout
\begin_layout Subsubsection
Building with Meson
\begin_inset CommandInset label
LatexCommand label
name "subsec:Configuration"
\end_inset
\end_layout
\begin_layout Standard
Now, from the
\begin_inset Flex File
status open
\begin_layout Plain Layout
binary_c
\end_layout
\end_inset
directory, you need to use
\begin_inset Flex Software
status open
\begin_layout Plain Layout
Meson
\end_layout
\end_inset
to make
\begin_inset Foot
status open
\begin_layout Plain Layout
Consider installing also
\begin_inset Flex Software
status open
\begin_layout Plain Layout
ccache
\end_layout
\end_inset
and bash auto-completion for
\begin_inset Flex Software
status open
\begin_layout Plain Layout
Meson
\end_layout
\end_inset
.
\end_layout
\end_inset
a build directory, e.g.,
\family typewriter
\series bold
\begin_inset listings
lstparams "language=bash"
inline false
status open
\begin_layout Plain Layout
meson builddir --buildtype release
\end_layout
\end_inset
\family default
\series default
and now you should go to that directory to build the code using
\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"
caps "false"
noprefix "false"
\end_inset
for
\begin_inset Flex Software
status open
\begin_layout Plain Layout
meson
\end_layout
\end_inset
- and
\begin_inset Flex Software
status open
\begin_layout Plain Layout
ninja
\end_layout
\end_inset
-
\begin_inset Flex Software
status open
\begin_layout Plain Layout
bash
\end_layout
\end_inset
autocompletion instructions).
\end_layout
\begin_layout Standard
\family typewriter
\series bold
\begin_inset listings
lstparams "language=bash"
inline false
status open
\begin_layout Plain Layout
cd builddir
\end_layout
\begin_layout Plain Layout
ninja
\end_layout
\end_inset
\family default
\series default
The code will now build, assuming everything worked ok.
If it does
\emph on
not
\emph default
work then please try to fix it (using, e.g.
\begin_inset space ~
\end_inset
your favourite search engine) before running to me with complaints.
It works fine on
\begin_inset Flex OS
status open
\begin_layout Plain Layout
Linux
\end_layout
\end_inset
and will revert to
\begin_inset Flex Software
status open
\begin_layout Plain Layout
gcc
\end_layout
\end_inset
as the default compiler if something goes wrong.
\end_layout
\begin_layout Standard
The executable is called
\begin_inset Flex File
status open
\begin_layout Plain Layout
binary_c
\end_layout
\end_inset
.
To run a star go back to the main binary_c directory and run tbse, e.g.,
\family typewriter
\series bold
\begin_inset listings
lstparams "language=bash"
inline false
status open
\begin_layout Plain Layout
cd ..
\end_layout
\begin_layout Plain Layout
tbse
\end_layout
\end_inset
\end_layout
\begin_layout Standard
Note:
\begin_inset Flex File
status open
\begin_layout Plain Layout
binary_c
\end_layout
\end_inset
is built as a single, possibly
\emph on
large
\emph default
(many MB) executable.
The reason for this is the ease of use when transferring the executable
from one machine to another (e.g.
\begin_inset space ~
\end_inset
for use with distributed computing).
It is possible to build a shared library instead (see below) and future
\begin_inset Formula $\binaryc$
\end_inset
versions will probably use environment variables to point to data directories.
\end_layout
\begin_layout Subsubsection
Meson buildtypes
\end_layout
\begin_layout Standard
Meson takes an argument
\begin_inset Flex Args
status open
\begin_layout Plain Layout
buildtype
\end_layout
\end_inset
which changes whether the build is for development (i.e.
\begin_inset space ~
\end_inset
a debug build), testing or for software release.
For example, to build for release – which is what you want when installing
for a
\begin_inset Formula $\binarygrid$
\end_inset
run because this is as optimized as possible – run:\end_layout
\begin_layout Standard
\begin_inset listings
lstparams "language=bash"
inline false
status open
\begin_layout Plain Layout
meson builddir --buildtype release
\end_layout
\end_inset
\end_layout
\begin_layout Standard
You can change the
\begin_inset Flex Args
status open
\begin_layout Plain Layout
buildtype
\end_layout
\end_inset
to debug if you want to build for testing: this is the default if you do
not include any
\begin_inset Flex Args
status open
\begin_layout Plain Layout
buildtype
\end_layout
\end_inset
argument.
\end_layout
\begin_layout Standard
\begin_inset listings
lstparams "language=bash"
inline false
status open
\begin_layout Plain Layout
meson builddir --buildtype debug
\end_layout
\end_inset
\end_layout
\begin_layout Standard
The full list of
\begin_inset Flex Args
status open
\begin_layout Plain Layout
buildtype
\end_layout
\end_inset
s is
\begin_inset Flex Args
status open
\begin_layout Plain Layout
plain
\end_layout
\end_inset
,
\begin_inset Flex Args
status open
\begin_layout Plain Layout
debug
\end_layout
\end_inset
,
\begin_inset Flex Args
status open
\begin_layout Plain Layout
debugoptimized
\end_layout
\end_inset
,
\begin_inset Flex Args
status open
\begin_layout Plain Layout
release
\end_layout
\end_inset
and
\begin_inset Flex Args
status open
\begin_layout Plain Layout
minsize
\end_layout
\end_inset
with details at
\begin_inset Flex URL
status open
\begin_layout Plain Layout
https://mesonbuild.com/Running-Meson.html
\end_layout
\end_inset
.
\end_layout
\begin_layout Subsubsection
Cleaning the build tree
\end_layout
\begin_layout Standard
You can clean the build directory with\family typewriter
\series bold
\begin_inset listings
lstparams "language=bash"
inline false
status open
\begin_layout Plain Layout
cd builddir
\end_layout
\begin_layout Plain Layout
ninja clean
\end_layout
\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
Building the shared library
\begin_inset Formula $\libbinaryc$
\end_inset
\end_layout
\begin_layout Standard
To build the shared library, go back into the builddir and run,
\end_layout
\begin_layout Standard
\begin_inset listings
lstparams "language=bash"
inline false
status open
\begin_layout Plain Layout
cd builddir
\end_layout
\begin_layout Plain Layout
ninja libbinary_c.so
\end_layout
\begin_layout Plain Layout
ninja libbinary_c_symlink
\end_layout
\end_inset
\end_layout
\begin_layout Standard
This makes the
\begin_inset Flex File
status open
\begin_layout Plain Layout
libbinary_c.so
\end_layout
\end_inset
shared library which can be used, for example, by the
\begin_inset Flex ProgrammingLanguage
status open
\begin_layout Plain Layout
C
\end_layout
\end_inset
backend to
\begin_inset Formula $\binarygrid$
\end_inset
\emph on
2
\emph default
, or to access
\begin_inset Formula $\binaryc$
\end_inset
through its
\emph on
API
\emph default
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$
\end_inset
and
\begin_inset Formula $\libbinaryc$
\end_inset
, and installing them for
\begin_inset Formula $\binarygrid2$
\end_inset
\end_layout
\begin_layout Standard
You can build and install both
\begin_inset Formula $\binaryc$
\end_inset
and
\begin_inset Formula $\libbinaryc$
\end_inset
in locations which are compatible with legacy builds and
\begin_inset Formula $\binarygrid2$
\end_inset
with one command:
\end_layout
\begin_layout Standard
\begin_inset listings
lstparams "language=bash"
inline false
status open
\begin_layout Plain Layout
cd builddir
\end_layout
\begin_layout Plain Layout
ninja binary_c_install
\end_layout
\end_inset
This puts a copy of the
\begin_inset Flex File
status open
\begin_layout Plain Layout
binary_c
\end_layout
\end_inset
executable in the root
\begin_inset Formula $\binaryc$
\end_inset
directory, and copies the shared library file \begin_inset Flex File
status open
\begin_layout Plain Layout
libbinary_c.so
\end_layout
\end_inset
to the
\begin_inset Flex File
status open
\begin_layout Plain Layout
src
\end_layout
\end_inset
directory, i.e.
\begin_inset space ~
\end_inset
the locations
\begin_inset Formula $\binarygrid$
\end_inset
2 expects.
\end_layout
\begin_layout Standard
After doing the above, you can remove the
\begin_inset Flex File
status open
\begin_layout Plain Layout
builddir
\end_layout
\end_inset
completely.
\end_layout
\begin_layout Subsubsection
Alternative compiler
\end_layout
\begin_layout Standard
You can build with another compiler, e.g.
\emph on
\begin_inset space ~
\end_inset
\begin_inset Flex Software
status open
\begin_layout Plain Layout
clang
\end_layout
\end_inset
\emph default
, by setting the
\begin_inset Flex Envvar
status open
\begin_layout Plain Layout
CC
\end_layout
\end_inset
environment variable.
If you have not yet made a builddir, do the following.
\end_layout
\begin_layout Standard
\begin_inset listings
lstparams "language=bash"
inline false
status open
\begin_layout Plain Layout
export CC=clang
\end_layout
\begin_layout Plain Layout
meson builddir --buildtype release
\end_layout
\begin_layout Plain Layout
cd builddir
\end_layout
\begin_layout Plain Layout
ninja
\end_layout
\end_inset
\end_layout
\begin_layout Subsubsection
Existing builddir
\end_layout
\begin_layout Standard
If you already have a
\begin_inset Flex File
status open
\begin_layout Plain Layout
builddir
\end_layout
\end_inset
, instead of deleting it, do the following,
\begin_inset listings
lstparams "language=bash"
inline false
status open
\begin_layout Plain Layout
export CC=clang
\end_layout
\begin_layout Plain Layout
cd builddir
\end_layout
\begin_layout Plain Layout
meson --reconfigure --buildtype release
\end_layout
\begin_layout Plain Layout
ninja
\end_layout
\end_inset
\end_layout
\begin_layout Subsubsection
Debugging build
\end_layout
\begin_layout Standard
To enable full debugging, run, from within
\begin_inset Flex File
status open
\begin_layout Plain Layout
builddir
\end_layout
\end_inset
,
\family typewriter
\series bold
\begin_inset listings
lstparams "language=bash"
inline false
status open
\begin_layout Plain Layout
meson builddir -Dvalgrind=true --buildtype debug
\end_layout
\begin_layout Plain Layout
ninja
\end_layout
\end_inset
\family default
\series default
or just
\family typewriter
\series bold
\begin_inset listings
lstparams "language=bash"
inline false
status open
\begin_layout Plain Layout
meson builddir
\end_layout
\begin_layout Plain Layout
cd builddir
\end_layout
\begin_layout Plain Layout
ninja
\end_layout
\end_inset
\family default
\series default
because
\begin_inset Flex Args
status open
\begin_layout Plain Layout
debug
\end_layout
\end_inset
is the default
\begin_inset Flex Args
status open
\begin_layout Plain Layout
buildtype
\end_layout
\end_inset
.
You require debugging to use
\begin_inset Flex Software
status open
\begin_layout Plain Layout
gdb
\end_layout
\end_inset
,
\begin_inset Flex Software
status open
\begin_layout Plain Layout
valgrind
\end_layout
\end_inset
, etc.
\end_layout
\begin_layout Standard
Many
\begin_inset Flex Software
status open
\begin_layout Plain Layout
GCC
\end_layout
\end_inset
installations include
\begin_inset Flex Software
status open
\begin_layout Plain Layout
libbacktrace
\end_layout
\end_inset
.
If
\begin_inset Flex Software
status open
\begin_layout Plain Layout
meson
\end_layout
\end_inset
is telling you it is missing, you might want to install it from the code
at
\begin_inset Flex URL
status collapsed
\begin_layout Plain Layout
https://github.com/ianlancetaylor/libbacktrace
\end_layout
\end_inset
.
Problems have been reported with the libbacktrace static library on
\emph on
Windows Subsystem for Linux
\emph default
because it is not compiled with
\begin_inset Flex Args
status open
\begin_layout Plain Layout
-fPIC
\end_layout
\end_inset
.
This is not a
\begin_inset Formula $\binaryc$
\end_inset
bug.
\end_layout
\begin_layout Subsubsection
Valgrind build
\end_layout
\begin_layout Standard
The extra flag
\begin_inset Flex Args
status open
\begin_layout Plain Layout
-Dvalgrind=true
\end_layout
\end_inset
is required on some newer CPUs because the CPU contains instructions which
are unknown to the latest version of
\begin_inset Flex Software
status open
\begin_layout Plain Layout
Valgrind
\end_layout
\end_inset
.
As of
\begin_inset Formula $\binaryc$
\end_inset
2.2.0 you are required to use
\begin_inset Flex Args
status open
\begin_layout Plain Layout
-Dvalgrind=true
\end_layout
\end_inset
if you want to run through
\begin_inset Flex Software
status open
\begin_layout Plain Layout
Valgrind
\end_layout
\end_inset
.
\end_layout
\begin_layout Subsubsection
Accurate floating point build
\end_layout
\begin_layout Standard
\begin_inset Formula $\Binaryc$
\end_inset
generally does not require perfect floating-point accuracy and uses
\begin_inset Flex CFlags
status open
\begin_layout Plain Layout
-ffast-math
\end_layout
\end_inset
for extra speed, but you can turn on
\begin_inset Flex Software
status open
\begin_layout Plain Layout
gcc
\end_layout
\end_inset
's various flags to improve accuracy with \family typewriter
\series bold
\begin_inset listings
lstparams "language=bash"
inline false
status open
\begin_layout Plain Layout
meson builddir -Daccurate=true
\end_layout
\end_inset
\end_layout
\begin_layout Subsubsection
Generic build, e.g.
\begin_inset space ~
\end_inset
for
\emph on
HTCondor
\end_layout
\begin_layout Standard
You may wish to build a generic version of
\begin_inset Formula $\binaryc$
\end_inset
which is not tied to the CPU architecture or operating system on which
you are building, e.g.
\begin_inset space ~
\end_inset
if your
\begin_inset Formula $\binaryc$
\end_inset
is required for use on the many machines of an
\begin_inset Flex Software
status open
\begin_layout Plain Layout
HTCondor
\end_layout
\end_inset
\emph on
\emph default
or
\begin_inset Flex Software
status open
\begin_layout Plain Layout
Slurm
\end_layout
\end_inset
grid.
Try
\family typewriter
\series bold
\begin_inset listings
lstparams "language=bash"
inline false
status open
\begin_layout Plain Layout
meson builddir -Dgeneric=true
\end_layout
\end_inset
\end_layout
\begin_layout Subsubsection
Libraries for
\begin_inset Formula $\binaryc$
\end_inset
\end_layout
\begin_layout Standard
\begin_inset Formula $\binaryc$
\end_inset
(optionally) uses
\begin_inset CommandInset href
LatexCommand href
name "libmemoize"
target "https://gitlab.eps.surrey.ac.uk/ri0005/libmemoize"
literal "false"
\end_inset
,
\begin_inset CommandInset href
LatexCommand href
name "librinterpolate"
target "https://gitlab.eps.surrey.ac.uk/ri0005/librinterpolate"
literal "false"
\end_inset
and
\begin_inset CommandInset href
LatexCommand href
name "librchash"
target "https://gitlab.eps.surrey.ac.uk/ri0005/librchash"
literal "false"
\end_inset
, written by RGI, and RGI's customized
\begin_inset Flex Software
status open
\begin_layout Plain Layout
Gnu Scientific Library
\end_layout
\end_inset
(at
\begin_inset CommandInset href
LatexCommand href
name "this link"
target "https://gitlab.eps.surrey.ac.uk/ri0005/GSL-RGI"literal "false"
\end_inset
).
These should really just be installed locally, but there are internal versions
inside
\begin_inset Formula $\binaryc$
\end_inset
just in case you cannot install them, and a standard system
\begin_inset Flex Software
status open
\begin_layout Plain Layout
GSL
\end_layout
\end_inset
should work.
\end_layout
\begin_layout Standard
You should make sure
\begin_inset Flex Software
status open
\begin_layout Plain Layout
Meson
\end_layout
\end_inset
knows about the locations of your libraries should you choose to use them.
Usually it is sufficient to set their locations (i.e.
\begin_inset space ~
\end_inset
the directories in which they reside) in the environment variables
\begin_inset Flex Envvar
status open
\begin_layout Plain Layout
LIBRARY_PATH
\end_layout
\end_inset
(for compilation) and
\begin_inset Flex Envvar
status open
\begin_layout Plain Layout
LD_LIBRARY_PATH
\end_layout
\end_inset
(at runtime).
For example, to point to the directories
\begin_inset Flex File
status open
\begin_layout Plain Layout
$HOME/lib
\end_layout
\end_inset
and
\begin_inset Flex File
status open
\begin_layout Plain Layout
$HOME/otherlibs
\end_layout
\end_inset
, using
\begin_inset Flex Software
status open
\begin_layout Plain Layout
bash
\end_layout
\end_inset
,
\family typewriter
\series bold
\begin_inset listings
lstparams "language=bash"
inline false
status open
\begin_layout Plain Layout
export LIBRARY_PATH=$HOME/lib:$HOME/otherlibs
\end_layout
\begin_layout Plain Layout
export LD_LIBRARY_PATH=$HOME/lib:$HOME/otherlibs
\end_layout
\end_inset
\end_layout
\begin_layout Standard
If you are using a non-system
\begin_inset Flex Software
status open
\begin_layout Plain Layout
GSL
\end_layout
\end_inset
, and have a system
\begin_inset Flex Software
status open
\begin_layout Plain Layout
GSL
\end_layout
\end_inset
installed at the same time, you need to make sure the location of the non-syste
m
\begin_inset Flex Command
status open
\begin_layout Plain Layout
gsl-config
\end_layout
\end_inset
is first in your
\begin_inset Flex Envvar
status open
\begin_layout Plain Layout
PATH
\end_layout
\end_inset
.
Try running
\begin_inset listings
lstparams "language=bash"
inline false
status open
\begin_layout Plain Layout
gsl-config --cflags
\end_layout
\end_inset
and this should, if you have installed
\begin_inset Flex Software
status open
\begin_layout Plain Layout
GSL
\end_layout
\end_inset
in
\begin_inset Flex File
status open
\begin_layout Plain Layout
/home/user
\end_layout
\end_inset
(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
\end_layout
\end_inset
or run
\begin_inset listings
inline false
status open
\begin_layout Plain Layout
echo 0 | sudo tee /proc/sys/kernel/randomize_va_space
\end_layout
\end_inset
(note: this requires root access)
\end_layout
\begin_layout Itemize
If you see errors like
\begin_inset listings
inline false
status open
\begin_layout Plain Layout
libbinary_c_objects___src_tables.a(src_tables_table_novae.c.o): In function
`table_novae':
\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
\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
\begin_layout Plain Layout
libbinary_c_objects___src_tables.a(src_tables_table_s_process.c.o): In function
`table_s_process':
\end_layout
\begin_layout Plain Layout
/home/izzard/progs/stars/binary_c/builddir/../src/tables/table_s_process.c:32:
undefined reference to `_binary_nucsyn_extended_s_process_dat_start'
\end_layout
\end_inset
this is because you have run
\begin_inset Flex Software
status open
\begin_layout Plain Layout
meson
\end_layout
\end_inset
and built with
\begin_inset Flex Software
status open
\begin_layout Plain Layout
ninja
\end_layout
\end_inset
with
\begin_inset Flex CMacro
status open
\begin_layout Plain Layout
NUCSYN
\end_layout
\end_inset
undefined (in
\begin_inset Flex File
status open
\begin_layout Plain Layout
binary_c_parameters.h
\end_layout
\end_inset
), then you have turned
\begin_inset Flex CMacro
status open
\begin_layout Plain Layout
NUCSYN
\end_layout
\end_inset
on and tried to rebuild with
\begin_inset Flex Software
status open
\begin_layout Plain Layout
ninja
\end_layout
\end_inset
without rerunning
\begin_inset Flex Software
status open
\begin_layout Plain Layout
meson
\end_layout
\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
meson --reconfigure
\end_layout
\begin_layout Plain Layout
ninja
\end_layout
\end_inset
or delete the
\begin_inset Flex File
status open
\begin_layout Plain Layout
builddir
\end_layout
\end_inset
and rerun
\begin_inset Flex Software
status open
\begin_layout Plain Layout
meson
\end_layout
\end_inset
and
\begin_inset Flex Software
status open
\begin_layout Plain Layout
ninja
\end_layout
\end_inset
, e.g.,
\begin_inset listings
lstparams "language=bash"
inline false
status open
\begin_layout Plain Layout
cd ..
\end_layout
\begin_layout Plain Layout
rm -r builddir
\end_layout
\begin_layout Plain Layout
meson builddir
\end_layout
\begin_layout Plain Layout
cd builddir
\end_layout
\begin_layout Plain Layout
ninja
\end_layout
\end_inset
\end_layout
\begin_layout Subsection
Testing
\begin_inset Formula $\binaryc$
\end_inset
\end_layout
\begin_layout Standard
Run the
\begin_inset Flex ScriptingLanguage
status open
\begin_layout Plain Layout
bash
\end_layout
\end_inset
script to
\begin_inset Quotes eld
\end_inset
test binary star evolution
\begin_inset Quotes erd
\end_inset
which is located in the main
\begin_inset Formula $\binaryc$
\end_inset
directory, called,
\end_layout
\begin_layout Standard
\begin_inset listings
lstparams "language=bash"
inline false
status open
\begin_layout Plain Layout
tbse
\end_layout
\end_inset
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
tbse commands
\begin_inset CommandInset label
LatexCommand label
name "subsec:tbse-commands"
\end_inset
\end_layout
\begin_layout Standard
\begin_inset Flex bashscript
status open
\begin_layout Plain Layout
tbse
\end_layout
\end_inset
\emph on
\emph default
can take extra arguments, which are often passed to
\emph on
\begin_inset Formula $\binaryc$
\end_inset
\emph default
directly or are directives to perform special tasks.
\end_layout
\begin_layout Description
tbse
\begin_inset space ~
\end_inset
echo This outputs (to
\emph on
stdout
\emph default
) the arguments that would have been sent to
\emph on
binary_c
\emph default
.
\end_layout
\begin_layout Description
tbse_echolines As
\emph on
tbse echo
\emph default
but in a single line of output.
Newlines are converted to
\family typewriter
\backslash
n
\family default
.
\end_layout
\begin_layout Description
tbse
\begin_inset space ~
\end_inset
args Ignores settings in the
\emph on
tbse
\emph default
file and runs only with the extra arguments given on the command line.
\end_layout
\begin_layout Description
tbse
\begin_inset space ~
\end_inset
arglines As
\emph on
tbse args
\emph default
but in a single line of output.
Newlines are converted to
\family typewriter
\backslash
n
\family default
.
\end_layout
\begin_layout Description
tbse
\begin_inset space ~
\end_inset
debug This runs
\emph on
\begin_inset Formula $\binaryc$
\end_inset
\emph default
with the gdb debugger
\end_layout
\begin_layout Description
tbse
\begin_inset space ~
\end_inset
valgrind This runs
\emph on
\begin_inset Formula $\binaryc$
\end_inset
\emph default
through
\emph on
Valgrind
\emph default
's
\emph on
memcheck
\emph default
tool to detect memory leaks.
Remember to use the flag
\begin_inset Flex Args
status open
\begin_layout Plain Layout
-Dvalgrind=true
\end_layout
\end_inset
when running
\begin_inset Flex Command
status open
\begin_layout Plain Layout
meson
\end_layout
\end_inset
.
\end_layout
\begin_layout Description
tbse
\begin_inset space ~
\end_inset
valgrind_args This shows the command-line arguments that are passed to
\emph on
Valgrind
\emph default
and then exits.
\end_layout
\begin_layout Description
tbse
\begin_inset space ~
\end_inset
massif This runs
\emph on
\begin_inset Formula $\binaryc$
\end_inset
\emph default
through
\emph on
Valgrind
\emph default
's
\emph on
massif
\emph default heap checker.
\end_layout
\begin_layout Description
tbse
\begin_inset space ~
\end_inset
callgrind This runs
\begin_inset Formula $\binaryc$
\end_inset
through
\emph on
Valgrind
\emph default
's
\emph on
callgrind
\emph default
tool.
\end_layout
\begin_layout Description
tbse
\begin_inset space ~
\end_inset
cachegrind This runs
\emph on
\begin_inset Formula $\binaryc$
\end_inset
\emph default
through
\emph on
Valgrind
\emph default
's
\emph on
cachegrind
\emph default
tool.
\end_layout
\begin_layout Description
tbse
\begin_inset space ~
\end_inset
ptrcheck This runs
\emph on
\begin_inset Formula $\binaryc$
\end_inset
\emph default
through
\emph on
Valgrind
\emph default
's
\emph on
ptrcheck
\emph default
tool.
\end_layout
\begin_layout Description
tbse
\begin_inset space ~
\end_inset
sgcheck This runs
\emph on
\begin_inset Formula $\binaryc$
\end_inset
\emph default
through
\emph on
Valgrind
\emph default
's
\emph on
sgcheck
\emph default
tool.
\end_layout
\begin_layout Description
tbse
\begin_inset space ~
\end_inset
drd This runs
\emph on
\begin_inset Formula $\binaryc$
\end_inset
\emph default
through
\emph on
Valgrind
\emph default
's
\emph on
drd
\emph default
tool.
\end_layout
\begin_layout Description
tbse
\begin_inset space ~
\end_inset
gprof This runs
\emph on
\begin_inset Formula $\binaryc$
\end_inset
\emph default
through
\emph on
gprof
\emph default
, the
\emph on
GNU
\emph default profiler.
\end_layout
\begin_layout Description
tbse
\begin_inset space ~
\end_inset
gprof_lines This runs
\emph on
\begin_inset Formula $\binaryc$
\end_inset
\emph default
through
\emph on
gprof
\emph default
, the
\emph on
GNU
\emph default
profiler, doing line-by-line accounting.
\end_layout
\begin_layout Description
tbse
\begin_inset space ~
\end_inset
gprof_with_stdout This runs
\emph on
\begin_inset Formula $\binaryc$
\end_inset
\emph default
through
\emph on
gprof
\emph default
, the
\emph on
GNU
\emph default
profiler, showing
\emph on
stdout
\emph default
.
\end_layout
\begin_layout Description
tbse
\begin_inset space ~
\end_inset
pgo Profile guided optimization.
This option is deprecated.
Please use the
\begin_inset Flex File
status open
\begin_layout Plain Layout
meson/pgo.sh
\end_layout
\end_inset
script instead (see
\begin_inset space ~
\end_inset
.
\end_layout
\begin_layout Description
tbse
\begin_inset space ~
\end_inset
bug This runs
\emph on
\begin_inset Formula $\binaryc$
\end_inset
\emph default
and outputs information which is suitable for reporting a bug to Rob.
\end_layout
\begin_layout Description
tbse
\begin_inset space ~
\end_inset
multicore This runs
\emph on
\begin_inset Formula $\binaryc$
\end_inset
\emph default
on many CPU cores at once.
Exits immediately on failure, so this is useful for testing e.g.
Monte carlo kicks.
\end_layout
\begin_layout Description
tbse
\begin_inset space ~
\end_inset
multicore_valgrind As
\emph on
tbse_multicore
\emph default
but using
\emph on
Valgrind
\emph default
.
\end_layout
\begin_layout Description
tbse
\begin_inset space ~
\end_inset
\emph on
<filename>
\emph default This runs the set of arguments specified in the file given by
\emph on
filename
\emph default
.
\end_layout
\begin_layout Description
tbse
\begin_inset space ~
\end_inset
clip Runs
\begin_inset Formula $\binaryc$
\end_inset
and saves the output to the clipboard (requires
\emph on
xclip
\emph default
).
\end_layout
\begin_layout Subsubsection
Testing many (random) systems
\end_layout
\begin_layout Standard
Sometimes the best thing to do is test many random systems.
You can do this with the
\begin_inset Flex File
status open
\begin_layout Plain Layout
test_random.pl
\end_layout
\end_inset
script.
I usually run it with something like:
\begin_inset listings
lstparams "language=bash"
inline false
status open
\begin_layout Plain Layout
cd $BINARY_C
\end_layout
\begin_layout Plain Layout
nice -n +19 ./src/perl/scripts2/test_random.pl threads=cpu newlogs logtimes
updatetime=0.25 sleeptime=0.25 valgrind
\end_layout
\end_inset
where the options are
\end_layout
\begin_layout Description
nice
\begin_inset space ~
\end_inset
-n
\begin_inset space ~
\end_inset
+19 to make sure we only use idle CPU cycles
\end_layout
\begin_layout Description
threads=cpu this uses
\begin_inset Formula $N-1$
\end_inset
threads, where
\begin_inset Formula $N$
\end_inset
is the number of CPU cores (this leaves one for managing the runs)
\end_layout
\begin_layout Description
newlogs Makes a new log file in
\begin_inset Flex File
status open
\begin_layout Plain Layout
$HOME/binary_c_test_random.log
\end_layout
\end_inset
\end_layout
\begin_layout Description
logtimes Makes a file
\begin_inset Flex File
status open
\begin_layout Plain Layout
$HOME/binary_c_test_random.logtimes
\end_layout
\end_inset
containing data that tells us how long each system takes to run
\end_layout
\begin_layout Description
updatetime=0.25 Number of seconds between updating the screen
\end_layout
\begin_layout Description
sleeptime=0.25 Internal sleep time before checking things
\end_layout
\begin_layout Description
valgrind Run binary_c through
\begin_inset Flex Software
status open
\begin_layout Plain Layout
valgrind
\end_layout
\end_inset
(warning will be slow, but thorough)
\end_layout
\begin_layout Subsection
Directory structure
\end_layout
\begin_layout Itemize
The
\begin_inset Flex File
status open
\begin_layout Plain Layout
src
\end_layout
\end_inset
directory, which holds all the
\family typewriter
.c
\family default
files
\end_layout
\begin_layout Itemize
\begin_inset Flex File
status open
\begin_layout Plain Layout
src/doc
\end_layout
\end_inset
contains documentation
\end_layout
\begin_layout Itemize
\begin_inset Flex File
status open
\begin_layout Plain Layout
src/perl
\end_layout
\end_inset
contains the
\begin_inset Flex ScriptingLanguage
status open
\begin_layout Plain Layout
Perl
\end_layout
\end_inset
scripts e.g.
\family typewriter
\begin_inset space ~
\end_inset
\family default
\begin_inset Flex File
status open
\begin_layout Plain Layout
grid.pl
\end_layout
\end_inset
\family typewriter
\family default
as well as latest
\emph on
\begin_inset Formula $\binarygrid$
\end_inset
\emph default
and helper modules, as well as some useful scripts.
Please see the installation guide for help on installing these components.
\end_layout
\begin_layout Itemize
\begin_inset Flex File
status open
\begin_layout Plain Layout
src/python
\end_layout
\end_inset
contains some experimental
\begin_inset Flex ScriptingLanguage
status open
\begin_layout Plain Layout
Python
\end_layout
\end_inset
scripts.
These are designed to work with
\begin_inset Formula $\binarycpython$
\end_inset
: please see its repository for those scripts.
\end_layout
\begin_layout Itemize
\begin_inset Flex File
status open
\begin_layout Plain Layout
unit_tests
\end_layout
\end_inset
contains some test components (likely to be updated in later versions)
\end_layout
\begin_layout Itemize
\begin_inset Flex File
status open
\begin_layout Plain Layout
builddir
\end_layout
\end_inset
contains the
\begin_inset Flex Software
status open
\begin_layout Plain Layout
Meson
\end_layout
\end_inset
/
\begin_inset Flex Software
status open
\begin_layout Plain Layout
Ninja
\end_layout
\end_inset
build information.
You can delete this at any time, but you will have to rebuild everything
from scratch.
\end_layout
\begin_layout Standard
\begin_inset Newpage pagebreak
\end_inset
\end_layout
\begin_layout Subsection
Building binary_grid2: the (old?) population synthesis module
\end_layout
\begin_layout Standard
This section describes in some detail the installation of
\emph on
\begin_inset Formula $\binarygrid$
\end_inset
2
\emph default
.
If you prefer to use
\begin_inset Flex ScriptingLanguage
status open
\begin_layout Plain Layout
Python
\end_layout
\end_inset
I recommend installing
\begin_inset Formula $\binarycpython$
\end_inset
instead (Sec.
\begin_inset space ~
\end_inset
\begin_inset CommandInset ref
LatexCommand ref
reference "subsec:Running-a-grid-python"
plural "false"
caps "false"
noprefix "false"
\end_inset
).
\end_layout
\begin_layout Standard
Note that sometimes you will require the latest version of pieces of software,
in particular
\begin_inset Flex ScriptingLanguage
status open
\begin_layout Plain Layout
Perl
\end_layout
\end_inset
which should be at least version 5.16.
I show you how to do this
\emph on
without
\emph default
requiring root permissions on your machine.
Should you require packages to be installed that require root permission,
you can always set up
\emph on
\begin_inset Formula $\binaryc$
\end_inset
\emph default
and
\emph on
\begin_inset Formula $\binarygrid$
\end_inset
\emph default
on a
\emph on
virtual machine
\emph default
which runs as a guest on your operating system, I do this with
\begin_inset Flex Software
status open
\begin_layout Plain Layout
Virtualbox
\end_layout
\end_inset
(
\begin_inset CommandInset href
LatexCommand href
target "https://www.virtualbox.org/"
literal "false"
\end_inset
).
This would be my advice if you are running on a non-standard operating
system, e.g.
\emph on
\begin_inset space ~
\end_inset
\emph default
\begin_inset Flex OS
status open
\begin_layout Plain Layout
Windows
\end_layout
\end_inset
.
You will have the root password for your virtual machine, so there are
never permissions problems.
\end_layout
\begin_layout Standard
You will need some basic tools installed to make everything work:
\begin_inset Flex ScriptingLanguage
status open
\begin_layout Plain Layout
bash
\end_layout
\end_inset
,
\begin_inset Flex Software
status open
\begin_layout Plain Layout
subversion
\end_layout
\end_inset
,
\begin_inset Flex ScriptingLanguage
status open
\begin_layout Plain Layout
Perl
\end_layout
\end_inset
,
\begin_inset Flex Software
status open
\begin_layout Plain Layout
gmake
\end_layout
\end_inset
,
\begin_inset Flex Software
status open
\begin_layout Plain Layout
wget
\end_layout
\end_inset
,
\begin_inset Flex Software
status open
\begin_layout Plain Layout
gcc
\end_layout
\end_inset
.
These are available on all good operating systems, and come by default
– or after a simple install – with most flavours of
\begin_inset Flex OS
status open
\begin_layout Plain Layout
Linux
\end_layout
\end_inset
/
\begin_inset Flex OS
status open
\begin_layout Plain Layout
Unix
\end_layout
\end_inset
and
\begin_inset Flex OS
status open
\begin_layout Plain Layout
MacOSX
\end_layout
\end_inset
(please see also Section
\begin_inset space ~
\end_inset
\begin_inset CommandInset ref
LatexCommand ref
reference "subsec:binaryc-on-MacOSX"
plural "false"
caps "false"
noprefix "false"
\end_inset
for OSX-specific instructions).
\end_layout
\begin_layout Standard
Some
\begin_inset Flex ScriptingLanguage
status open
\begin_layout Plain Layout
Perl
\end_layout
\end_inset
\emph on
\emph defaultmodules also require some other system libraries and development files.
It is difficult to know exactly what these would be for every operating
system.
You may have to use a web search to find out, but that's fine because you
are smart!
\end_layout
\begin_layout Subsubsection
Get the latest
\begin_inset Flex ScriptingLanguage
status open
\begin_layout Plain Layout
Perl
\end_layout
\end_inset
with
\emph on
perlbrew
\end_layout
\begin_layout Standard
I highly recommend that you install the latest version of
\begin_inset Flex ScriptingLanguage
status open
\begin_layout Plain Layout
Perl
\end_layout
\end_inset
\emph on
\emph default
using
\begin_inset Flex Software
status open
\begin_layout Plain Layout
perlbrew
\end_layout
\end_inset
and install modules using
\begin_inset Flex Software
status open
\begin_layout Plain Layout
cpanm
\end_layout
\end_inset
\emph on
.
\emph default
I describe how to do this below, but also please see
\begin_inset CommandInset href
LatexCommand href
target "http://perlbrew.pl/"
literal "false"
\end_inset
and
\begin_inset CommandInset href
LatexCommand href
target "http://perlbrew.pl/Perlbrew-and-Friends.html "
literal "false"
\end_inset
for further instructions and documentation.
\end_layout
\begin_layout Subsubsection
Installing
\emph on
\begin_inset Formula $\binaryc$
\end_inset
\end_layout
\begin_layout Standard
Please see Sec.
\begin_inset space ~
\end_inset
\begin_inset CommandInset ref
LatexCommand ref
reference "subsec:Building"
plural "false"
caps "false"
noprefix "false"
\end_inset
above for details about how to install
\begin_inset Formula $\binaryc$
\end_inset
.
\end_layout
\begin_layout Subsubsection
Installing
\emph on
\begin_inset Formula $\binarygrid$
\end_inset
2
\end_layout
\begin_layout Standard
\begin_inset CommandInset label
LatexCommand label
name "subsec:installing binary_grid"
\end_inset
\end_layout
\begin_layout Standard
\emph on
\begin_inset Formula $\binarygrid$
\end_inset
2
\emph default
is written in
\begin_inset Flex ScriptingLanguage
status open
\begin_layout Plain Layout
\begin_inset Flex ScriptingLanguage
status open
\begin_layout Plain Layout
Perl
\end_layout
\end_inset
\end_layout
\end_inset
(
\begin_inset CommandInset href
LatexCommand href
target "http://www.perl.org/"
literal "false"
\end_inset
) which is available on almost every modern operating system, although to
my knowledge
\emph on
\begin_inset Formula $\binarygrid$
\end_inset
2
\emph default
has never been tested on anything other than
\begin_inset Flex OS
status open
\begin_layout Plain Layout
Linux
\end_layout
\end_inset
(
\begin_inset CommandInset href
LatexCommand href
target "http://www.linux.org/"
literal "false"
\end_inset
),
\begin_inset Flex OS
status open
\begin_layout Plain Layout
Solaris
\end_layout
\end_inset
and
\begin_inset Flex OS
status open
\begin_layout Plain Layout
MacOSX
\end_layout
\end_inset
.
\end_layout
\begin_layout Standard
The newest
\emph on
\begin_inset Formula $\binarygrid$
\end_inset
2
\emph default
uses features from the latest
\begin_inset Flex ScriptingLanguage
status open
\begin_layout Plain Layout
Perl
\end_layout
\end_inset
(5.16 or above, currently testing on 5.29.8) so you'll need a recent
\begin_inset Flex ScriptingLanguage
status open
\begin_layout Plain Layout
Perl
\end_layout
\end_inset
to be installed.
Unfortunately most versions of
\begin_inset Flex OS
status open
\begin_layout Plain Layout
Linux
\end_layout
\end_inset
run an older
\begin_inset Flex ScriptingLanguage
status open
\begin_layout Plain Layout
Perl
\end_layout
\end_inset
without support for many of the required features.
You will also need to have the latest versions of a number of
\begin_inset Flex ScriptingLanguage
status open
\begin_layout Plain Layout
Perl
\end_layout
\end_inset
modules which come from either from the online resource
\emph on
CPAN
\emph default
\begin_inset Foot
status open
\begin_layout Plain Layout
\emph on
Comprehensive Perl Archive Network
\end_layout
\end_inset
(
\begin_inset CommandInset href
LatexCommand href
target "http://www.cpan.org/"
literal "false"
\end_inset
) or as part of the
\emph on
\begin_inset Formula $\binaryc$
\end_inset
\emph default
package.
\end_layout
\begin_layout Standard
My recommendation is to use
\series bold
\emph on
perlbrew
\series default
\emph default
to make your own
\begin_inset Flex ScriptingLanguage
status open
\begin_layout Plain Layout
Perl
\end_layout
\end_inset
and
\begin_inset Flex Software
status open
\begin_layout Plain Layout
cpanminus
\end_layout
\end_inset
(the command is
\begin_inset Flex Software
status open
\begin_layout Plain Layout
cpanm\end_layout
\end_inset
) to install the modules.
\end_layout
\begin_layout Standard
You can find
\begin_inset Flex Software
status open
\begin_layout Plain Layout
perlbrew
\end_layout
\end_inset
at
\begin_inset CommandInset href
LatexCommand href
target "http://perlbrew.pl/"
literal "false"
\end_inset
: please follow the instructions on that page to install the latest
\begin_inset Flex ScriptingLanguage
status open
\begin_layout Plain Layout
Perl
\end_layout
\end_inset
on your system if you do not trust my instructions below.
Typically do the following, but remember you
\emph on
must
\emph default
install
\begin_inset Flex Software
status open
\begin_layout Plain Layout
perlbrew
\end_layout
\end_inset
with
\begin_inset Flex CFlags
status open
\begin_layout Plain Layout
-Dusethreads
\end_layout
\end_inset
otherwise
\begin_inset Flex ScriptingLanguage
status open
\begin_layout Plain Layout
Perl
\end_layout
\end_inset
will not use threads and you will lose the multi-CPU features of
\emph on
\begin_inset Formula $\binarygrid$
\end_inset
\emph default
2.
Please note that I assume you are using the
\begin_inset Flex Software
status open
\begin_layout Plain Layout
bash
\end_layout
\end_inset
shell.
\end_layout
\begin_layout Enumerate
\begin_inset listings
lstparams "language=bash"
inline false
status open
\begin_layout Plain Layout
wget --no-check-certificate -O - http://install.perlbrew.pl | bash
\end_layout
\end_inset
or
\begin_inset listings
lstparams "language=bash"
inline false
status open
\begin_layout Plain Layout
curl -kL http://install.perlbrew.pl | bash
\end_layout
\end_inset
If you have problems with
\begin_inset Flex Software
status open
\begin_layout Plain Layout
\emph off
wget
\end_layout
\end_inset
, try removing the
\begin_inset Flex Args
status open
\begin_layout Plain Layout
--no-check-certificate
\end_layout
\end_inset
.
\end_layout
\begin_layout Enumerate
Run
\begin_inset Flex Software
status open
\begin_layout Plain Layout
perlbrew
\end_layout
\end_inset
\family typewriter
available
\family default
to find a list of available versions, you should choose the newest, e.g.
\begin_inset space ~
\end_inset
\begin_inset Flex File
status open
\begin_layout Plain Layout
perl-5.29.8
\end_layout
\end_inset
, and then run the following command to install
\begin_inset Flex ScriptingLanguage
status open
\begin_layout Plain Layout
Perl
\end_layout
\end_inset
:
\begin_inset listings
lstparams "language=bash"
inline false
status open
\begin_layout Plain Layout
perlbrew -v install perl-5.29.8 --thread --multi --64bitall --notest -Dusethreads
-Duselargefiles -Duseshrplib -Dcccdlflags=-fPIC -Dpager=/usr/bin/sensible-pager
-Doptimize="-O3 -march=x86-64 -mtune=generic" -Duseshrplib -j 8
\end_layout
\end_inset
You can use
\begin_inset Flex CFlags
status open
\begin_layout Plain Layout
-march=native -mtune=native
\end_layout
\end_inset
if you are quite sure you will not use this version of
\begin_inset Flex ScriptingLanguagestatus open
\begin_layout Plain Layout
Perl
\end_layout
\end_inset
, or its modules, on a machine with a different architecture.
If you are building for use with an
\begin_inset Flex Software
status open
\begin_layout Plain Layout
HTCondor
\end_layout
\end_inset
grid or on a shared (e.g.
\begin_inset space ~
\end_inset
\emph on
\begin_inset Flex Software
status open
\begin_layout Plain Layout
NFS
\end_layout
\end_inset
\emph default
) filesystem which is used on many different machines, I highly recommend
using the
\begin_inset Flex Args
status open
\begin_layout Plain Layout
generic
\end_layout
\end_inset
option.
\begin_inset Newline newline
\end_inset
Note that the final
\emph on
8
\emph default
should be replaced by the number of CPUs you wish to use for the build
(it is an option passed to
\emph on
make
\emph default
).
Note also that
\begin_inset Flex CFlags
status open
\begin_layout Plain Layout
-Duseshrplib
\end_layout
\end_inset
may no longer be required.
I have recently added
\begin_inset Flex CFlags
status open
\begin_layout Plain Layout
–thread-multi –64bitall
\end_layout
\end_inset
so if you have trouble, please remove these and try again.
\begin_inset Foot
status open
\begin_layout Plain Layout
In
\begin_inset Flex ScriptingLanguage
status open
\begin_layout Plain Layout
Perl
\end_layout
\end_inset
5.27.5 there is a (known) bug in the test routines which may (or may not)
stop your installation.
For this reason the
\begin_inset Flex CFlags
status open
\begin_layout Plain Layout
--notest
\end_layout
\end_inset
flag if set.
Remove this if you want testing back (also, it is slow).
\end_layout
\end_inset
The installation process can take a long time, go and have lunch\SpecialChar ldots
then:
\end_layout
\begin_layout Enumerate
Do what
\begin_inset Flex Software
status open
\begin_layout Plain Layout
perlbrew
\end_layout
\end_inset
suggests with your
\begin_inset Flex File
status open
\begin_layout Plain Layout
.bashrc
\end_layout
\end_inset
(or whatever shell initialization script you use) to fix the
\begin_inset Flex Envvar
status open
\begin_layout Plain Layout
PERLBREW_PATH
\end_layout
\end_inset
.
\end_layout
\begin_layout Enumerate
Restart your shell (e.g.
\begin_inset space ~
\end_inset
close your terminal and open a new one, or just run
\begin_inset Flex ScriptingLanguage
status open
\begin_layout Plain Layout
bash
\end_layout
\end_inset
again) to update your environment and
\begin_inset Flex Envvar
status open
\begin_layout Plain Layout
$PATH
\end_layout
\end_inset
.
\end_layout
\begin_layout Enumerate
Check you're using the correct
\begin_inset Flex ScriptingLanguage
status open
\begin_layout Plain Layout
Perl
\end_layout
\end_inset
with
\begin_inset listings
lstparams "language=bash"
inline false
status open
\begin_layout Plain Layout
perl -v
\end_layout
\end_inset
This should say something like
\begin_inset Newline newline
\end_inset
\begin_inset listings
inline false
status open
\begin_layout Plain Layout
This is perl 5, version 29, subversion 8 (v5.29.8) built for x86_64-linux-thread-m
ulti
\end_layout
\end_inset
Check that the
\begin_inset Flex Args
status open
\begin_layout Plain Layout
-thread-
\end_layout
\end_inset
is there – without threads,
\emph on
\begin_inset Formula $\binarygrid$
\end_inset
2
\emph default
multi-CPU options will not function.
\begin_inset Newline newline
\end_inset
\begin_inset Newline newline
\end_inset
If you have a previous version of
\begin_inset Flex ScriptingLanguage
status open
\begin_layout Plain Layout
Perl
\end_layout
\end_inset
installed by
\begin_inset Flex Software
status open
\begin_layout Plain Layout
perlbrew
\end_layout
\end_inset
, you will have to do something like
\begin_inset Newline newline
\end_inset
\begin_inset listings
lstparams "language=bash"
inline false
status open
\begin_layout Plain Layout
perlbrew switch perl-5.29.8
\end_layout
\end_inset
\end_layout
\begin_layout Enumerate
If the installation was successful, but you see an older
\begin_inset Flex ScriptingLanguage
status open
\begin_layout Plain Layout
Perl
\end_layout
\end_inset
, check that your
\begin_inset Flex Envvar
status open
\begin_layout Plain Layout
$PATH
\end_layout
\end_inset
variable points to the new
\begin_inset Flex ScriptingLanguage
status open
\begin_layout Plain Layout
Perl
\end_layout
\end_inset
, and check that
\begin_inset Flex Envvar
status open
\begin_layout Plain Layout
$PERLBREW_PATH
\end_layout
\end_inset
exists.
\end_layout
\begin_layout Enumerate
Install
\begin_inset Flex Software
status open
\begin_layout Plain Layout
cpanminus
\end_layout
\end_inset
by running
\begin_inset Newline newline
\end_inset
\begin_inset listings
lstparams "language=bash"
inline false
status open
\begin_layout Plain Layout
perlbrew install-cpanm
\end_layout
\end_inset
\end_layout
\begin_layout Standard
Now you have the latest
\begin_inset Flex ScriptingLanguage
status open
\begin_layout Plain Layout
Perl
\end_layout
\end_inset
and
\begin_inset Flex Software
status open
\begin_layout Plain Layout
cpanm
\end_layout
\end_inset
installed, you can start to install the modules needed for
\emph on
\begin_inset Formula $\binarygrid$
\end_inset
\emph default
2.
(Un?)fortunately, there are many of them, so I have made a script to do
it for you
\end_layout
\begin_layout Enumerate
From the
\begin_inset Flex File
status open
\begin_layout Plain Layout
binary_c
\end_layout
\end_inset
directory, go to
\begin_inset Flex File
status open
\begin_layout Plain Layout
src/perl
\end_layout
\end_inset
with
\begin_inset listings
lstparams "language=bash"
inline false
status open
\begin_layout Plain Layout
cd src/perl
\end_layout
\end_inset
\end_layout
\begin_layout Enumerate
Run the install script which uses
\begin_inset Flex Software
status open
\begin_layout Plain Layout
cpanminus
\end_layout
\end_inset
to install the modules
\begin_inset Newline newline
\end_inset
\begin_inset listings
lstparams "language=bash"
inline false
status open
\begin_layout Plain Layout
./install_modules.pl
\end_layout
\end_inset
\end_layout
\begin_layout Enumerate
Wait.
Watch the output flow past your eyes.
Note that you can
\emph on
also
\emph default
install the modules yourself from their tarballs in
\begin_inset Flex File
status open
\begin_layout Plain Layout
src/perl/modules_targz
\end_layout
\end_inset
, e.g.,
\begin_inset listings
lstparams "language=bash"
inline false
status open
\begin_layout Plain Layout
cd src/perl/modules_targz
\end_layout
\begin_layout Plain Layout
cpanm ./<modname>.tar.gz
\end_layout
\end_inset
but please note the
\begin_inset Flex Args
status open
\begin_layout Plain Layout
./
\end_layout
\end_inset
in the filename is
\emph on
required
\emph default
.
\end_layout
\begin_layout Enumerate
In case of errors, try installing the module with verbose logging switched
on
\family typewriter
\series bold
\begin_inset Newline newline
\end_inset
\family default
\series default
\begin_inset listings
lstparams "language=bash"
inline false
status open
\begin_layout Plain Layout
cpanm -v ./<modname>.tar.gz
\end_layout
\end_inset
\end_layout
\begin_layout Enumerate
Check the output.
If there is a failure, it should say.
You will have to fix it by looking at the output to see where it went wrong.
The most common cause of failure is that you need some kind of development
(
\emph on
-dev
\emph default
or
\emph on
-devel
\emph default) packages to be installed on your system, e.g.
through
\emph on
\begin_inset Flex Software
status open
\begin_layout Plain Layout
apt
\end_layout
\end_inset
\emph default
,
\begin_inset Flex Software
status open
\begin_layout Plain Layout
yum
\end_layout
\end_inset
or
\begin_inset Flex Software
status open
\begin_layout Plain Layout
synaptic
\end_layout
\end_inset
or the system package manager.
This may require root permission.
\begin_inset Newline newline
\end_inset
If all else fails, you can ask RGI for help, but he's not a sysadmin!
\end_layout
\begin_layout Enumerate
Your installed modules are usually in (for
\begin_inset Flex ScriptingLanguage
status open
\begin_layout Plain Layout
Perl
\end_layout
\end_inset
5.29.8)
\begin_inset Flex File
status open
\begin_layout Plain Layout
$HOME/perl5/perlbrew/perls/5.29.8/lib/site_perl/5.29.8
\end_layout
\end_inset
\begin_inset Newline newline
\end_inset
You should not have to set the
\begin_inset Flex Envvarstatus open
\begin_layout Plain Layout
PERL5LIB
\end_layout
\end_inset
environment variable when installing with a modern
\begin_inset Flex Software
status open
\begin_layout Plain Layout
cpanminus
\end_layout
\end_inset
.
\begin_inset Newline newline
\end_inset
If you
\emph on
do
\emph default
have trouble, try
\begin_inset listings
lstparams "language=bash"
inline false
status open
\begin_layout Plain Layout
export PERL5LIB=$HOME/perl5/perlbrew/perls/5.29.8/lib/site_perl/5.29.8
\end_layout
\end_inset
(or similar).
\end_layout
\begin_layout Standard
Now you should have everything installed and be able to run a
\emph on
\begin_inset Formula $\binarygrid$
\end_inset
\emph default
script.
\end_layout
\begin_layout Subsubsection
Troubleshooting
\emph on
\begin_inset Flex ScriptingLanguage
status open
\begin_layout Plain Layout
\emph on
Perl
\end_layout
\end_inset
\end_layout
\begin_layout Description
Module
\begin_inset space ~
\end_inset
not
\begin_inset space ~
\end_inset
found Check the
\begin_inset Flex Envvar
status open
\begin_layout Plain Layout
PERL5LIB
\end_layout
\end_inset
environment variable.
When it is empty,
\begin_inset Flex Software
status open
\begin_layout Plain Layout
cpanm
\end_layout
\end_inset
/
\begin_inset Flex Software
status open
\begin_layout Plain Layout
perlbrew
\end_layout
\end_inset
should find your modules automatically,
\emph on
if
\emph default
they are installed correctly by
\begin_inset Flex Software
status open
\begin_layout Plain Layout
cpanm
\end_layout
\end_inset
(in the
\begin_inset Flex File
status open
\begin_layout Plain Layout
site_perl
\end_layout
\end_inset
directory, see above).
You can try installing modules again with
\begin_inset listings
lstparams "language=bash"inline false
status open
\begin_layout Plain Layout
cpanm --force --reinstall
\end_layout
\end_inset
to force a reinstallation, and with
\begin_inset Flex Args
status open
\begin_layout Plain Layout
-v
\end_layout
\end_inset
for extra logging.
\end_layout
\begin_layout Description
Module
\begin_inset space ~
\end_inset
fails
\begin_inset space ~
\end_inset
to
\begin_inset space ~
\end_inset
build Try
\begin_inset listings
lstparams "language=bash"
inline false
status open
\begin_layout Plain Layout
cpanm --notests
\end_layout
\end_inset
to not run all tests.
Sometimes these fail for spurious reasons, e.g.
in the case of
\emph on
\begin_inset Formula $\binarygrid$
\end_inset
\emph default
because there are
\emph on
no tests,
\emph default
but
\emph on
\emph default
the module still functions.
\end_layout
\begin_layout Description
Perlbrew
\begin_inset space ~
\end_inset
build
\begin_inset space ~
\end_inset
flags I would recommend at least
\begin_inset Newline newline
\end_inset
\begin_inset Flex CFlags
status open
\begin_layout Plain Layout
-Dusethreads -Duselargefiles -Doptimize="-O3 -march=native -mtune=native"
\end_layout
\end_inset
\family typewriter
\begin_inset Newline newline
\end_inset
\family default
although you may wish to use
\begin_inset Flex CFlags
status open
\begin_layout Plain Layout
-O2
\end_layout
\end_inset
if you feel mathematical precision is key to your application (I have never
noticed a problem with the above).
\begin_inset Newline newline
\end_inset
I also recommend
\begin_inset Flex CFlags
status open
\begin_layout Plain Layout
-Dcccdlflags=-fPIC
\end_layout
\end_inset
\family typewriter
\family default
so that module code is position independent and
\family typewriter
-Duseshrplib
\family default
so that the appropriate threading library is used.
(These flags are passed to the
\emph on
C
\emph default
compiler that builds \begin_inset Flex ScriptingLanguage
status open
\begin_layout Plain Layout
Perl
\end_layout
\end_inset
.)
\end_layout
\begin_layout Description
Rebuild
\begin_inset space ~
\end_inset
modules
\begin_inset space ~
\end_inset
for
\begin_inset space ~
\end_inset
new
\begin_inset space ~
\end_inset
\begin_inset Flex ScriptingLanguage
status open
\begin_layout Plain Layout
Perl
\end_layout
\end_inset
Let's say you had an old
\begin_inset Flex ScriptingLanguage
status open
\begin_layout Plain Layout
Perl
\end_layout
\end_inset
\emph on
\emph default
built with
\begin_inset Flex ScriptingLanguage
status open
\begin_layout Plain Layout
perlbrew
\end_layout
\end_inset
, have installed a shiny new
\begin_inset Flex ScriptingLanguage
status open
\begin_layout Plain Layout
Perl
\end_layout
\end_inset
version with
\begin_inset Flex Software
status open
\begin_layout Plain Layout
perlbrew
\end_layout
\end_inset
, and now you want to rebuild all your existing modules.
Try this after the install, but before switching to the new
\begin_inset Flex ScriptingLanguage
status open
\begin_layout Plain Layout
Perl
\end_layout
\end_inset
, replacing
\family typewriter
5.xx.yy
\family default
with the new
\begin_inset Flex ScriptingLanguage
status open
\begin_layout Plain Layout
Perl
\end_layout
\end_inset
version:
\begin_inset Newline newline
\end_inset
\begin_inset listings
lstparams "language=bash"
inline false
status open
\begin_layout Plain Layout
perlbrew list-modules | perlbrew exec --with 5.xx.yy cpanm
\end_layout
\end_inset
\end_layout
\begin_layout Subsection
\emph on
\begin_inset Formula $\binarygrid$
\end_inset
2
\emph default
backends
\begin_inset CommandInset label
LatexCommand label
name "subsec:binary_grid2-backends"
\end_inset
\end_layout
\begin_layout Standard
The
\begin_inset Quotes eld
\end_inset
backend
\begin_inset Quotes erd
\end_inset
of
\emph on
\begin_inset Formula $\binaryc$
\end_inset
\emph default
is a set of interface code between
\emph on
\begin_inset Formula $\binaryc$
\end_inset
\emph default
and
\begin_inset Formula $\binarygrid$
\end_inset
\emph on
2
\emph default
.
To understand what a backend is, please see
\begin_inset CommandInset href
LatexCommand href
target "https://en.wikipedia.org/wiki/Front_and_back_ends"
literal "false"
\end_inset
.
There are two backends –
\begin_inset Flex ScriptingLanguage
status open
\begin_layout Plain Layout
Perl
\end_layout
\end_inset
and
\begin_inset Flex ProgrammingLanguage
status open
\begin_layout Plain Layout
C
\end_layout
\end_inset
– corresponding to the two different ways \emph on
\begin_inset Formula $\binaryc$
\end_inset
\emph default
can talk to
\begin_inset Formula $\binarygrid$
\end_inset
.
You should always use the
\begin_inset Flex ProgrammingLanguage
status open
\begin_layout Plain Layout
C
\end_layout
\end_inset
backend if at all possible: it is faster and has more features, and the
\begin_inset Flex ScriptingLanguage
status open
\begin_layout Plain Layout
Perl
\end_layout
\end_inset
backend will be deprecated at some point.
\end_layout
\begin_layout Subsubsection
\begin_inset Flex ProgrammingLanguage
status open
\begin_layout Plain Layout
C
\end_layout
\end_inset
backend
\end_layout
\begin_layout Standard
New to
\emph on
\begin_inset Formula $\binarygrid$
\end_inset
2
\emph default
is the
\emph on
\emph default
\begin_inset Flex ProgrammingLanguage
status open
\begin_layout Plain Layout
C
\end_layout
\end_inset
backend.
This features simpler code and uses
\emph on
\begin_inset Formula $\binaryc$
\end_inset
\emph default
's
\emph on
API
\emph default
to access data directly, hence it is a lot faster than the
\begin_inset Flex ScriptingLanguage
status open
\begin_layout Plain Layout
Perl
\end_layout
\end_inset
backend, and scales better on multi-core architectures.
The down side is that installation is more difficult, especially if you
have multiple projects.
\end_layout
\begin_layout Standard
If you see errors like:
\end_layout
\begin_layout Standard
\series bold
\begin_inset listings
inline false
status open
\begin_layout Plain Layout
perl: symbol lookup error: /.../perl5/perlbrew/perls/perl-5.29.8/lib/site_perl/5.29.8/x
86_64-linux-thread-multi/auto/binary_grid/C/C.so: undefined symbol: new_system
\end_layout
\end_inset
\series default
then you have failed to build the shared library as is required when using
the
\begin_inset Flex ProgrammingLanguage
status open
\begin_layout Plain Layout
C
\end_layout
\end_inset
backend.
\begin_inset Newline newline
\end_inset
To make the
\begin_inset Flex ProgrammingLanguage
status open
\begin_layout Plain Layout
C
\end_layout
\end_inset
backend work, you have to
\emph on
first
\emph default
build
\begin_inset Flex File
status open
\begin_layout Plain Layout
libbinary_c.so
\end_layout
\end_inset
and
\emph on
then
\emph default
install
\emph on
\begin_inset Formula $\binarygrid$
\end_inset
2
\emph default
.
In summary:
\end_layout
\begin_layout Enumerate
Build
\emph on
\begin_inset Formula $\binaryc$
\end_inset
\emph default
and the shared library,
\emph on
libbinary_c.so
\emph default
,
\emph on
\emph default
e.g.
with,
\begin_inset listings
lstparams "language=bash"
inline false
status open
\begin_layout Plain Layout
cd builddir
\end_layout
\begin_layout Plain Layout
ninja binary_c_install
\end_layout
\begin_layout Plain Layout
cd ..
\end_layout
\end_inset
\end_layout
\begin_layout Enumerate
Install
\emph on
\begin_inset Formula $\binarygrid$
\end_inset
2
\emph default
and the other modules using
\emph on
cpanm
\emph default
\begin_inset listings
lstparams "language=bash"
inline false
status open
\begin_layout Plain Layout
cd src/perl
\end_layout
\begin_layout Plain Layout
./install_modules.pl
\end_layout
\end_inset
\end_layout
\begin_layout Standard
Because this module is written partly in
\begin_inset Flex ProgrammingLanguage
status open
\begin_layout Plain Layout
C
\end_layout
\end_inset
and partly in
\begin_inset Flex ScriptingLanguage
status open
\begin_layout Plain Layout
Perl
\end_layout
\end_inset
, everything has to work perfectly or it will crash (usually with a segmentatio
n fault).
The shared library file
\begin_inset Flex File
status open
\begin_layout Plain Layout
libbinary_c.so
\end_layout
\end_inset
\emph on
\emph default
must match with
\emph on
\begin_inset Formula $\binarygrid$
\end_inset
2
\emph default
\series bold
at compile time
\series default
, and if you change anything in
\emph on
\begin_inset Formula $\binaryc$
\end_inset
\emph default
you probably have to follow the above instructions to reinstall the
\begin_inset Flex ProgrammingLanguage
status open
\begin_layout Plain Layout
C
\end_layout
\end_inset
backend.
\end_layout
\begin_layout Standard
\series bold
You may have to run
\begin_inset Flex Command
status open
\begin_layout Plain Layout
\series bold
install_modules.pl
\end_layout
\end_inset
a few times because of a dependency error.
If you see a
\begin_inset Quotes eld
\end_inset
FAIL
\begin_inset Quotes erd
\end_inset
in the output, go to the src/perl/modules_targz directory and run,\series default
\begin_inset listings
lstparams "language=bash"
inline false
status open
\begin_layout Plain Layout
./install_all.pl
\end_layout
\begin_layout Plain Layout
./install_all.pl
\end_layout
\begin_layout Plain Layout
./install_all.pl
\end_layout
\end_inset
\end_layout
\begin_layout Standard
You can change the name of the shared library by setting the environment
variable
\family typewriter
BINARY_GRID2_LIB
\family default
to the name of the library, and pointing
\begin_inset Flex Envvar
status open
\begin_layout Plain Layout
BINARY_C
\end_layout
\end_inset
to your
\emph on
\begin_inset Formula $\binaryc$
\end_inset
\emph default
tree.
Then rebuild, e.g., assuming you already have a
\begin_inset Flex File
status open
\begin_layout Plain Layout
builddir
\end_layout
\end_inset
,
\end_layout
\begin_layout Standard
\begin_inset listings
lstparams "language=bash"
inline false
status open
\begin_layout Plain Layout
export BINARY_GRID2_LIB=binary_c_custom
\end_layout
\begin_layout Plain Layout
export BINARY_C=$HOME/binary_c
\end_layout
\begin_layout Plain Layout
cd builddir
\end_layout
\begin_layout Plain Layout
meson --reconfigure -Dlibname=binary_c_custom
\end_layout
\begin_layout Plain Layout
ninja libbinary_c_custom.so
\end_layout
\begin_layout Plain Layout
\end_layout
\begin_layout Plain Layout
# ...
change directory to where you have binary_grid2.tar.gz ...
\end_layout
\begin_layout Plain Layout
\end_layout
\begin_layout Plain Layout
cpanm binary_grid2.tar.gz
\end_layout
\end_inset
\end_layout
\begin_layout Standard
The
\emph on
\begin_inset Formula $\binarygrid$
\end_inset
2
\emph default
module respects the
\begin_inset Flex Envvar
status open
\begin_layout Plain Layout
BINARY_GRID2_LIB
\end_layout
\end_inset
environment variable.
\end_layout
\begin_layout Standard
I do not yet know how to have custom
\begin_inset Flex ProgrammingLanguage
status open
\begin_layout Plain Layout
C
\end_layout
\end_inset
backend modules with different shared libraries.
It is quite possible that you could use the
\begin_inset Flex Envvar
status open
\begin_layout Plain Layout
PERL_INLINE_DIRECTORY
\end_layout
\end_inset
environment variable to have multiple builds, and point to the appropriate
one.
Please read
\begin_inset CommandInset href
LatexCommand href
target "http://search.cpan.org/~ingy/Inline-0.44/Inline.pod"
literal "false"
\end_inset
especially the section
\emph on
The Inline DIRECTORY
\emph default
for instructions on how it is best to set up production code for multiple
projects.
Let RGI know if it works, so better instructions can be put in here.
\end_layout
\begin_layout Standard
There are a number of environment variables which can be set when installing
\emph on
\begin_inset Formula $\binarygrid$
\end_inset
2
\emph default
's
\emph on
C
\emph default
backend:
\end_layout
\begin_layout Description
BINARY_C The directory in which your
\begin_inset Formula $\binaryc$
\end_inset
source tree lives.
From this, the
\begin_inset Flex Filestatus open
\begin_layout Plain Layout
src
\end_layout
\end_inset
directory is at
\begin_inset Flex File
status open
\begin_layout Plain Layout
\begin_inset Flex Envvar
status open
\begin_layout Plain Layout
$BINARY_C
\end_layout
\end_inset
/src
\end_layout
\end_inset
\end_layout
\begin_layout Description
BINARY_GRID2_LIB The name of the shared library.
Usually this is
\emph on
'binary_c
\emph default
'.
\end_layout
\begin_layout Description
BINARY_GRID2_CC The name of the compiler used to build the
\begin_inset Flex ProgrammingLanguage
status open
\begin_layout Plain Layout
C
\end_layout
\end_inset
backend.
Set by
\begin_inset Flex bashscript
status open
\begin_layout Plain Layout
binary_c-config
\end_layout
\end_inset
by default (section
\begin_inset space ~
\end_inset
\begin_inset CommandInset ref
LatexCommand ref
reference "subsec:binary_c-config"
plural "false"caps "false"
noprefix "false"
\end_inset
).
\end_layout
\begin_layout Description
BINARY_GRID2_LD The name of the linker used to build the
\begin_inset Flex ProgrammingLanguage
status open
\begin_layout Plain Layout
C
\end_layout
\end_inset
backend.
Set by
\begin_inset Flex bashscript
status open
\begin_layout Plain Layout
binary_c-config
\end_layout
\end_inset
by default (section
\begin_inset space ~
\end_inset
\begin_inset CommandInset ref
LatexCommand ref
reference "subsec:binary_c-config"
plural "false"
caps "false"
noprefix "false"
\end_inset
).
\end_layout
\begin_layout Description
BINARY_GRID2_INC Include flags for the build.
Set by
\begin_inset Flex bashscript
status open
\begin_layout Plain Layout
binary_c-config
\end_layout
\end_inset
by default (section
\begin_inset space ~
\end_inset
\begin_inset CommandInset ref
LatexCommand ref
reference "subsec:binary_c-config"
plural "false"
caps "false"
noprefix "false"
\end_inset
).
\end_layout
\begin_layout Description
BINARY_GRID2_EXTRAINC Include flags to be postfixed to the
\emph on
inc
\emph default
flags set above.
\end_layout
\begin_layout Description
BINARY_GRID2_LIBS Library flags.
Set by
\begin_inset Flex bashscript
status open
\begin_layout Plain Layout
binary_c-config
\end_layout
\end_inset
by default (section
\begin_inset space ~
\end_inset
\begin_inset CommandInset ref
LatexCommand ref
reference "subsec:binary_c-config"
plural "false"
caps "false"
noprefix "false"
\end_inset
).
\end_layout
\begin_layout Description
BINARY_GRID2_EXTRALIBS Library flags appended to the
\emph on
libs
\emph default
flags set above.
\end_layout
\begin_layout Description
BINARY_GRID2_CCFLAGS Compiler flags.
\family typewriter
\family default
Set by
\begin_inset Flex bashscript
status open
\begin_layout Plain Layout
binary_c-config
\end_layout
\end_inset
by default (section
\begin_inset space ~
\end_inset
\begin_inset CommandInset ref
LatexCommand ref
reference "subsec:binary_c-config"
plural "false"
caps "false"
noprefix "false"
\end_inset
).
\end_layout
\begin_layout Description
BINARY_GRID2_EXTRACCFLAGS C compiler flags postfixed to the
\emph on
ccflags
\emph default
set above.
\end_layout
\begin_layout Description
BINARY_GRID2_DEBUG If non-zero, is used at the debugging flag when building
the
\begin_inset Flex Perlmodule
status open
\begin_layout Plain Layout
binary_grid::C
\end_layout
\end_inset
backend.
\end_layout
\begin_layout Subsubsection
The C backend with multiple versions of
\emph on
\begin_inset Formula $\binaryc$
\end_inset
\end_layout
\begin_layout Standard
You may well have several branches, each of which uses a different
\emph on
\begin_inset Formula $\binaryc$
\end_inset
\emph default
setup (e.g.
one with
\begin_inset Flex CMacro
status open
\begin_layout Plain Layout
NUCSYN
\end_layout
\end_inset
, one without).
However, using
\begin_inset Flex Softwarestatus open
\begin_layout Plain Layout
cpanm
\end_layout
\end_inset
the
\begin_inset Flex Perlmodule
status open
\begin_layout Plain Layout
binary_grid::C
\end_layout
\end_inset
module is installed only
\emph on
once
\emph default
and cannot possibly thus work with all your branches.
(The reason is that in each branch the various structures used by
\emph on
\begin_inset Formula $\binaryc$
\end_inset
\emph default
will be of different sizes in memory, so trying to access them from an
incompatible version will likely give you a segmentation fault.)
\end_layout
\begin_layout Standard
There is a solution.
Make two directories containing your
\emph on
\begin_inset Formula $\binaryc$
\end_inset
\emph default
trees.
You can either check out new copies of your git branches, or use
\begin_inset Quotes eld
\end_inset
git archive
\begin_inset Quotes erd
\end_inset
to copy a tree.
In each tree, build a local copy of the
\emph on
\begin_inset Formula $\binarygrid$
\end_inset
\emph default
modules using
\begin_inset Flex ScriptingLanguage
status open
\begin_layout Plain Layout
Perl
\end_layout
\end_inset
's
\begin_inset Flex Perlmodule
status open
\begin_layout Plain Layout
local::lib
\end_layout
\end_inset
and use this when calling your
\begin_inset Flex ScriptingLanguage
status open
\begin_layout Plain Layout
Perl
\end_layout
\end_inset
grid script.
\end_layout
\begin_layout Standard
Note: it is important to set
\begin_inset Flex Envvar
status open
\begin_layout Plain Layout
BINARY_C
\end_layout
\end_inset
prior to the rebuild, this points to your
\begin_inset Formula $\binaryc$
\end_inset
directory (as checked out using
\emph on
git
\emph default
), because the
\begin_inset Formula $\binarygrid$
\end_inset
module looks in these locations for source code (which is different from
tree to tree).
So, from within the tree directory, run the following:
\end_layout
\begin_layout Standard
\begin_inset listings
lstparams "language=bash"
inline false
status open
\begin_layout Plain Layout
export BINARY_C=
\begin_inset Quotes erd
\end_inset
path_to_tree
\begin_inset Quotes erd
\end_inset
# you have to set this to the git checkout directory
\end_layout
\begin_layout Plain Layout
PERL_LIBDIR=
\begin_inset Quotes erd
\end_inset
path_to_binary_grid_perl_module
\begin_inset Quotes erd
\end_inset
# you have to set this
\end_layout
\begin_layout Plain Layout
\end_layout
\begin_layout Plain Layout
# make a Perl module build directory specific to this tree
\end_layout
\begin_layout Plain Layout
PERL_MODDIR=
\begin_inset Quotes erd
\end_inset
$BINARY_C/src/perl_local_lib
\begin_inset Quotes erd
\end_inset
\end_layout
\begin_layout Plain Layout
mkdir -p $PERL_MODDIR
\end_layout
\begin_layout Plain Layout
\end_layout
\begin_layout Plain Layout
# install binary_grid.
Note, we install from a clean directory
\end_layout
\begin_layout Plain Layout
mkdir -p build
\end_layout
\begin_layout Plain Layout
cd build
\end_layout
\begin_layout Plain Layout
cpanm --local-lib $PERL_MODDIR --reinstall $PERL_MODDIR
\end_layout
\begin_layout Plain Layout
cd ..
\end_layout
\begin_layout Plain Layout
rmdir build
\end_layout
\begin_layout Plain Layout
\end_layout
\begin_layout Plain Layout
# run your grid
\end_layout
\begin_layout Plain Layout
perl -Mlocal::lib=$PER_MODDIR your_grid_script.pl ...
\end_layout
\begin_layout Plain Layout
\end_layout
\end_inset
\end_layout
\begin_layout Subsubsection
Perl backend
\end_layout
\begin_layout Standard
\series bold
Warning: the
\begin_inset Flex ScriptingLanguage
status open
\begin_layout Plain Layout
Perl
\end_layout
\end_inset
backend will soon be deprecated.
\end_layout
\begin_layout Standard
In
\emph on
\begin_inset Formula $\binarygrid$
\end_inset
\emph default
version 1, the only backend available was the
\begin_inset Flex ScriptingLanguage
status open
\begin_layout Plain Layout
Perl
\end_layout
\end_inset
backend which communicates with
\emph on
\begin_inset Formula $\binaryc$
\end_inset
\emph default
via a set of
\begin_inset Flex OS
status open
\begin_layout Plain Layout
Unix
\end_layout
\end_inset
pipes.
This is portable and flexible, and hence for many years was the default.
It does not, however, scale very well in multi-CPU architectures (mostly
because of the bandwidth required for the pipes).
In
\emph on
\begin_inset Formula $\binarygrid$
\end_inset
2
\emph default
a pure
\begin_inset Flex ScriptingLanguage
status open
\begin_layout Plain Layout
Perl
\end_layout
\end_inset
module is also provided, both for backwards compatibility and because
the code is well tested and stable.
The
\begin_inset Flex ScriptingLanguage
status open
\begin_layout Plain Layout
Perl
\end_layout
\end_inset
backend is installed by default with
\emph on
\begin_inset Formula $\binarygrid$
\end_inset
2
\emph default
although the
\begin_inset Flex ProgrammingLanguage
status open
\begin_layout Plain Layout
C
\end_layout
\end_inset
\emph on
\emph default
backend will replace it eventually.
\end_layout
\begin_layout Standard
It is a simple matter of changing the
\begin_inset Flex Perlcode
status open
\begin_layout Plain Layout
prog
\end_layout
\end_inset
grid variable if you want to use a different version of
\emph on
\begin_inset Formula $\binaryc$
\end_inset
\emph default
with each grid script.
\end_layout
\begin_layout Subsection
\begin_inset Formula $\binaryc$
\end_inset
on MacOSX
\end_layout
\begin_layout Standard
\begin_inset CommandInset label
LatexCommand label
name "subsec:binaryc-on-MacOSX"
\end_inset
To run
\begin_inset Formula $\binaryc$
\end_inset
on
\begin_inset Flex OS
status open
\begin_layout Plain Layout
OSX
\end_layout
\end_inset
first you should install the GNU core utilities, e.g.
\begin_inset space ~
\end_inset
using
\begin_inset Flex Software
status open
\begin_layout Plain Layout
homebrew
\end_layout
\end_inset
.
Then, set up your path to include the GNU utilities, e.g.
\begin_inset space ~
\end_inset
with
\begin_inset listings
lstparams "language=bash"
inline false
status open
\begin_layout Plain Layout
export PATH=/usr/local/opt/coreutils/libexec/gnubin/:/usr/local/bin:$PATH
\end_layout
\end_inset
You should, if you want to use
\begin_inset Formula $\binarygrid$
\end_inset
, install
\begin_inset Flex Software
status open
\begin_layout Plain Layout
Perl
\end_layout
\end_inset
using
\begin_inset Flex Software
status open
\begin_layout Plain Layout
Perlbrew
\end_layout
\end_inset
, as directed above.
\end_layout
\begin_layout Standard
Now,
\begin_inset Flex Software
status open
\begin_layout Plain Layout
meson
\end_layout
\end_inset
and
\begin_inset Flex Software
status open
\begin_layout Plain Layout
ninja
\end_layout
\end_inset
should work just as on
\begin_inset Flex OS
status open
\begin_layout Plain Layout
Linux
\end_layout
\end_inset
.
You should be able to run
\begin_inset Flex File
status open
\begin_layout Plain Layout
tbse
\end_layout
\end_inset
to test that one star runs.
\end_layout
\begin_layout Standard
Things are more complicated if you want to run
\begin_inset Formula $\binarygrid$
\end_inset
.
You need to use the
\begin_inset Flex Envvar
status open
\begin_layout Plain Layout
DYLD_INSERT_LIBRARIES
\end_layout
\end_inset
environment variable to to locate the
\begin_inset Formula $\binaryc$
\end_inset
library, and make sure
\begin_inset Flex Software
status open
\begin_layout Plain Layout
Perl
\end_layout
\end_inset
is the executable that is called, e.g., to run
\begin_inset Flex Perlscript
status open
\begin_layout Plain Layout
template.pl
\end_layout
\end_inset
,
\begin_inset listings
lstparams "language=bash"
inline false
status open
\begin_layout Plain Layout
DYLD_INSERT_LIBRARIES=/Users/rob_izzard/progs/stars/binary_c/src/libbinary_c.dylib perl5.35.1 src/perl/scripts2/template.pl
\end_layout
\end_inset
\end_layout
\begin_layout Standard
Should you need to debug your code,
\begin_inset Flex Software
status open
\begin_layout Plain Layout
valgrind
\end_layout
\end_inset
may not be available, and you should use
\begin_inset Flex Software
status open
\begin_layout Plain Layout
lldb
\end_layout
\end_inset
as a debugger in place of
\begin_inset Flex Software
status open
\begin_layout Plain Layout
gdb
\end_layout
\end_inset
.
To run a
\begin_inset Formula $\binarygrid$
\end_inset
instance through the debugger, you probably need to launch it as root and
set the location of the
\begin_inset Formula $\binaryc$
\end_inset
library,
\begin_inset listings
lstparams "language=bash"
inline false
status open
\begin_layout Plain Layout
sudo DYLD_INSERT_LIBRARIES=/Users/rob_izzard/progs/stars/binary_c/src/libbinary_
c.dylib lldb perl5.35.1
\end_layout
\end_inset
then in
\begin_inset Flex Software
status open
\begin_layout Plain Layout
lldb
\end_layout
\end_inset
, you have to also set
\begin_inset Flex Envvar
status open
\begin_layout Plain Layout
DYLD_INSERT_LIBRARIES
\end_layout
\end_inset
before running the code with the following commands.
\begin_inset listings
inline false
status open
\begin_layout Plain Layout
env DYLD_INSERT_LIBRARIES=/Users/rob_izzard/progs/stars/binary_c/src/libbinary_c.
dylib
\end_layout
\begin_layout Plain Layout
run /Users/rob_izzard/progs/stars/binary_c/src/perl/scripts2/template.pl
metallicity=0.02
\end_layout
\end_inset
\end_layout
\begin_layout Standard
\begin_inset Newpage pagebreak
\end_inset
\end_layout
\begin_layout Section
Evolving single and binary stars
\end_layout
\begin_layout Standard
\begin_inset CommandInset label
LatexCommand label
name "sec:Simple-Use"
\end_inset
This section describes how to run
\emph on
\begin_inset Formula $\binaryc$
\end_inset
\emph default
on one stellar system, be it single or binary.
The web home of
\begin_inset Formula $\binaryc$
\end_inset
is
\begin_inset CommandInset href
LatexCommand href
name "http://personal.ph.surrey.ac.uk/~ri0005/binary_c.html"literal "false"
\end_inset
.
The online binary-star simulator is at
\begin_inset CommandInset href
LatexCommand href
name "http://personal.ph.surrey.ac.uk/~ri0005/cgi-bin/binary5.cgi"
literal "false"
\end_inset
.
If these should move, you can use your favourite web-search engine to locate
the code.
\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 "subsec:mailing-lists"
\end_inset
).
\end_layout
\begin_layout Subsection
Running one star with
\begin_inset Quotes eld
\end_inset
test binary star evolution
\begin_inset Quotes erd
\end_inset
:
\emph on
\begin_inset Flex File
status open
\begin_layout Plain Layout
\emph on
tbse
\end_layout
\end_inset
\end_layout
\begin_layout Standard
\begin_inset CommandInset label
LatexCommand label
name "subsec:Running"
\end_inset
\end_layout
\begin_layout StandardA
\begin_inset Flex ScriptingLanguage
status open
\begin_layout Plain Layout
bash
\end_layout
\end_inset
script called
\begin_inset Flex File
status open
\begin_layout Plain Layout
tbse
\end_layout
\end_inset
is provided to run one single or binary star system.
Run it with
\begin_inset Newline newline
\end_inset
\begin_inset listings
lstparams "language=bash"
inline false
status open
\begin_layout Plain Layout
./tbse
\end_layout
\end_inset
\end_layout
\begin_layout Standard
from the
\emph on
\begin_inset Formula $\binaryc$
\end_inset
\emph default
directory (you can omit the
\begin_inset Flex File
status open
\begin_layout Plain Layout
.
\end_layout
\end_inset
if it is in your
\begin_inset Flex Envvar
status open
\begin_layout Plain Layout
PATH
\end_layout
\end_inset
).
The script sets a number of
\begin_inset Flex ScriptingLanguage
status open
\begin_layout Plain Layout
bash
\end_layout
\end_inset
variables (in capital letters) which are then passed to
\begin_inset Formula $\binaryc$
\end_inset
.
In general, the capitalized
\begin_inset Flex ScriptingLanguage
status open
\begin_layout Plain Layout
bash
\end_layout
\end_inset
\emph on
\emph default
variable corresponds to the same variable in
\begin_inset Formula $\binaryc$
\end_inset
in lower case.
For example,
\end_layout
\begin_layout Standard
\begin_inset listings
inline false
status open
\begin_layout Plain Layout
# Initial primary mass
\end_layout
\begin_layout Plain Layout
M1=6
\end_layout
\begin_layout Plain Layout
# Initial secondary mass
\end_layout
\begin_layout Plain Layout
M2=3
\end_layout
\begin_layout Plain Layout
# Initial orbital period (days)
\end_layout
\begin_layout Plain Layout
ORBITAL_PERIOD=100
\end_layout
\begin_layout Plain Layout
# Initial eccentricity
\end_layout
\begin_layout Plain Layout
ECCENTRICITY=0.2
\end_layout
\begin_layout Plain Layout
# (Initial) Metallicity
\end_layout
\begin_layout Plain Layout
METALLICITY=0.02
\end_layout
\begin_layout Plain Layout
# Maximum evolution time (MYr)
\end_layout
\begin_layout Plain Layout
MAX_EVOLUTION_TIME=16000
\end_layout
\end_inset
\end_layout
\begin_layout Standard
Many parameters are not just simple floating-point numbers, they are choices
of algorithms.
You can replace the numerical algorithm number, as usually defined by a
macro in a header file, with the macro itself.
For example, the following two are equivalent because the macro
\begin_inset Flex CMacro
status open
\begin_layout Plain Layout
MAGNETIC_BRAKING_ALGORITHM_HURLEY_2002
\end_layout
\end_inset
is defined to be
\begin_inset Flex CVar
status open
\begin_layout Plain Layout
0
\end_layout
\end_inset
,
\begin_inset listings
inline false
status open
\begin_layout Plain Layout
MAGNETIC_BRAKING_ALGORITHM=0
\end_layout
\begin_layout Plain Layout
MAGNETIC_BRAKING_ALGORITHM=MAGNETIC_BRAKING_ALGORITHM_HURLEY_2002
\end_layout
\end_inset
similarly, you can use
\begin_inset Flex CMacro
status open
\begin_layout Plain Layout
True
\end_layout
\end_inset
and
\begin_inset Flex CMacro
status open
\begin_layout Plain Layout
False
\end_layout
\end_inset
(or
\begin_inset Flex CMacro
status open
\begin_layout Plain Layout
t
\end_layout
\end_inset
,
\begin_inset Flex CMacro
status open
\begin_layout Plain Layout
T
\end_layout
\end_inset
,
\begin_inset Flex CMacro
status open
\begin_layout Plain Layout
true
\end_layout
\end_inset
, etc.) to represent
\begin_inset Flex CVar
status open
\begin_layout Plain Layout
1
\end_layout
\end_inset
and
\begin_inset Flex CVar
status open
\begin_layout Plain Layout
0
\end_layout
\end_inset
respectively when setting boolean options,
\begin_inset listings
inline false
status open
\begin_layout Plain Layout
PRE_MAIN_SEQUENCE=True
\end_layout
\begin_layout Plain Layout
PRE_MAIN_SEQUENCE_FIT_LOBES=False
\end_layout
\end_inset
\end_layout
\begin_layout Standard
A simple output log is sent to the file defined in
\begin_inset Flex CMacro
status open
\begin_layout Plain Layout
LOG_FILENAME
\end_layout
\end_inset
which is
\begin_inset Flex File
status open
\begin_layout Plain Layout
/tmp/c_log2.out
\end_layout
\end_inset
by default.
\begin_inset listings
inline false
status open
\begin_layout Plain Layout
LOG_FILENAME=
\begin_inset Quotes erd
\end_inset
/tmp/c_log2.out
\begin_inset Quotes erd
\end_inset
\end_layout
\end_inset
\end_layout
\begin_layout Standard
What gets output to the screen depends on what options you select and what
logging you put in (see section
\begin_inset CommandInset ref
LatexCommand ref
reference "subsec:Advanced-Configuration"
\end_inset
).
\end_layout
\begin_layout Standard
Run
\begin_inset listings
lstparams "language=bash"
inline false
status open
\begin_layout Plain Layout
tbse help
\end_layout
\end_inset
to obtain general help for
\begin_inset Flex File
status open
\begin_layout Plain Layout
tbse
\end_layout
\end_inset
or read Section
\begin_inset space ~
\end_inset
\begin_inset CommandInset ref
LatexCommand ref
reference "subsec:tbse-commands"
\end_inset
to see more options.
\end_layout
\begin_layout Standard
Use
\begin_inset listings
lstparams "language=bash"
inline false
status open
\begin_layout Plain Layout
./binary_c help
\end_layout
\end_inset
for general \begin_inset Formula $\binaryc$
\end_inset
help, or
\begin_inset listings
lstparams "language=bash"
inline false
status open
\begin_layout Plain Layout
./binary_c help <string>
\end_layout
\end_inset
to get help on the contents of string, for example let's say you want to
know which options are available for the
\begin_inset Flex CVar
status open
\begin_layout Plain Layout
magnetic_braking_algorithm
\end_layout
\end_inset
preference:
\begin_inset listings
inline false
status open
\begin_layout Plain Layout
./binary_c help magnetic_braking_algorithm
\end_layout
\begin_layout Plain Layout
binary_c help for variable : magnetic_braking_algorithm <Integer>
\end_layout
\begin_layout Plain Layout
\end_layout
\begin_layout Plain Layout
Algorithm for the magnetic braking angular momentum loss rate.
0 = Hurley et al.
2002, 1 = Andronov, Pinnsonneault and Sills 2003, 2 = Barnes and Kim 2010,
3 = Rappaport 1983
\end_layout
\begin_layout Plain Layout
\end_layout
\begin_layout Plain Layout
Available macros:
\end_layout
\begin_layout Plain Layout
\end_layout
\begin_layout Plain Layout
MAGNETIC_BRAKING_ALGORITHM_HURLEY_2002 = 0\end_layout
\begin_layout Plain Layout
MAGNETIC_BRAKING_ALGORITHM_ANDRONOV_2003 = 1
\end_layout
\begin_layout Plain Layout
MAGNETIC_BRAKING_ALGORITHM_BARNES_2010 = 2
\end_layout
\begin_layout Plain Layout
MAGNETIC_BRAKING_ALGORITHM_RAPPAPORT_1983 = 3
\end_layout
\begin_layout Plain Layout
\end_layout
\end_inset
\end_layout
\begin_layout Standard
Do
\emph on
not
\emph default
use
\begin_inset Flex File
status open
\begin_layout Plain Layout
tbse
\end_layout
\end_inset
to run many stars in a stellar population! This is amazingly inefficient:
you'll waste a huge amount of time just loading
\begin_inset Flex ScriptingLanguage
status open
\begin_layout Plain Layout
bash
\end_layout
\end_inset
and saving your data.
\end_layout
\begin_layout Standard
\begin_inset Newpage pagebreak
\end_inset
\end_layout
\begin_layout Section
Making populations of stars with
\begin_inset Formula $\binarygrid$
\end_inset
2
\end_layout
\begin_layout Standard
\begin_inset CommandInset label
LatexCommand label
name "subsec:Running-a-grid"
\end_inset
You
\emph on
could
\emph default
run many stars by directly calling
\emph on
\begin_inset Formula $\binaryc$
\end_inset
\emph default
with the appropriate arguments or making many
\begin_inset Flex File
status open
\begin_layout Plain Layout
tbse
\end_layout
\end_inset
\emph on
\emph default
scripts.
This is
\series bold
\emph on
very
\series default
\emph default
\series bold
\emph on
inefficient
\series default
\emph default
.
Instead,
\family roman
\emph on
\begin_inset Formula $\binaryc$
\end_inset
\family default
\emph default
can be controlled by a
\begin_inset Flex ScriptingLanguage
status open
\begin_layout Plain Layout
Perl
\end_layout
\end_inset
script, e.g.
\begin_inset space ~
\end_inset
\begin_inset Flex File
status open
\begin_layout Plain Layout
grid.pl
\end_layout
\end_inset
, which uses a library of functions in the
\emph on
\begin_inset Formula $\binarygrid2$
\end_inset
\emph default
\begin_inset Flex ScriptingLanguage
status open
\begin_layout Plain Layout
Perl
\end_layout
\end_inset
module to run the stars on a grid for you.
\end_layout
\begin_layout Standard
\begin_inset CommandInset include
LatexCommand input
filename "binary_grid2.lyx"
\end_inset
\begin_inset Newpage pagebreak
\end_inset
\end_layout
\begin_layout Section
Making populations of stars with
\begin_inset Formula $\binarycpython$
\end_inset
\end_layout
\begin_layout Standard
\begin_inset CommandInset label
LatexCommand label
name "subsec:Running-a-grid-python"
\end_inset
Please see instructions at
\end_layout
\begin_layout Itemize
\begin_inset Flex URL
status open
\begin_layout Plain Layout
https://gitlab.eps.surrey.ac.uk/ri0005/binary_c-python
\end_layout
\end_inset
\end_layout
\begin_layout Itemize
\begin_inset Flex URL
status open
\begin_layout Plain Layout
https://pypi.org/project/binarycpython/
\end_layout
\end_inset
\end_layout
\begin_layout Standard
\begin_inset Newpage pagebreak
\end_inset
\end_layout
\begin_layout Section
The
\begin_inset Formula $\binaryc$
\end_inset
ensemble
\end_layout
\begin_layout Standard
\begin_inset CommandInset include
LatexCommand input
filename "binary_c-ensemble.lyx"
\end_inset
\end_layout
\begin_layout Standard
\begin_inset Newpage pagebreak
\end_inset
\end_layout
\begin_layout Section
\emph on
\begin_inset Formula $\binaryc$
\end_inset
\emph default
API
\end_layout
\begin_layout Standard
\begin_inset CommandInset include
LatexCommand input
filename "binary_c-API.lyx"
\end_inset
\end_layout
\begin_layout Section
Code description and internals
\end_layout
\begin_layout Standard
\begin_inset CommandInset label
LatexCommand label
name "sec:Code-description"
\end_inset
\end_layout
\begin_layout Standard
This section describes some of the internal details of the
\emph on
\begin_inset Formula $\binaryc$
\end_inset
\emph default
code.
\end_layout
\begin_layout Subsection
History
\end_layout
\begin_layout Standard
\begin_inset CommandInset label
LatexCommand label
name "subsec:History"
\end_inset
First, a bit of history.
The
\emph on
\begin_inset Flex Software
status open
\begin_layout Plain Layout
\emph off
BSE
\end_layout
\end_inset
\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
\begin_inset Flex ProgrammingLanguage
status open
\begin_layout Plain Layout
Fortran
\end_layout
\end_inset
, 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
\begin_inset Flex ProgrammingLanguage
status open
\begin_layout Plain Layout
Fortran
\end_layout
\end_inset
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 the code out quite differently.
\end_layout
\begin_layout Standard
One major change is in the organisation of the variables.
In the
\begin_inset Flex ProgrammingLanguage
status open
\begin_layout Plain Layout
Fortran
\end_layout
\end_inset
code there are lots of arrays of size 2 (there are two stars) and a load
of evil common blocks.
These have been replaced by structures, one for each
\family typewriter
star
\family default
, the
\begin_inset Flex CStruct
status open
\begin_layout Plain Layout
common
\end_layout
\end_inset
and
\begin_inset Flex CStruct
status open
\begin_layout Plain Layout
model
\end_layout
\end_inset
structures, a
\begin_inset Flex CStruct
status open
\begin_layout Plain Layout
preferences
\end_layout
\end_inset
structure to contain user-defined options, and a
\begin_inset Flex CStruct
status open
\begin_layout Plain Layout
stardata
\end_layout
\end_inset
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 (and pointers are fast).
\end_layout
\begin_layout Standard
Throughout the code you'll see lots of
\family typewriter
Dprint
\family default
statements, these are enabled when debugging is turned on.
These are very useful when something goes wrong (see section
\begin_inset space ~
\end_inset
\begin_inset CommandInset ref
LatexCommand ref
reference "sec:debugging"
plural "false"
caps "false"
noprefix "false"
\end_inset
).
\end_layout
\begin_layout Standard
If you change anything, and would like me to debug it or you would like
to commit it to the
\begin_inset Formula $\mainbranch$
\end_inset
branch, I insist on the following.
\end_layout
\begin_layout Itemize
Learn about how to write
\begin_inset Flex ProgrammingLanguage
status open
\begin_layout Plain Layout
C
\end_layout
\end_inset
, e.g.
\begin_inset CommandInset href
LatexCommand href
name "https://www.maultech.com/chrislott/resources/cstyle/indhill-cstyle.pdf"
target "https://www.maultech.com/chrislott/resources/cstyle/indhill-cstyle.pdf"
literal "false"
\end_inset
or
\begin_inset CommandInset href
LatexCommand href
name "https://en.wikipedia.org/wiki/The_C_Programming_Language"
target "https://en.wikipedia.org/wiki/The_C_Programming_Language"
literal "false"
\end_inset
.
\end_layout
\begin_layout Itemize
Learn how to format your
\begin_inset Flex ProgrammingLanguage
status open
\begin_layout Plain Layout
C
\end_layout
\end_inset
code properly.
Please use the
\begin_inset CommandInset href
LatexCommand href
name "Allman style"
target "https://en.wikipedia.org/wiki/Indentation_style#Allman_style"
literal "false"
\end_inset
and indent with four spaces (
\begin_inset CommandInset href
LatexCommand href
name "emacs"
target "https://www.gnu.org/software/emacs/"
literal "false"
\end_inset
indents
\begin_inset Flex ProgrammingLanguage
status open
\begin_layout Plain Layout
C
\end_layout
\end_inset
like this automatically).\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 change
the code in the future, and I have to check it before it is committed.
Descriptions of the physics, paraphrased from a paper if you have to (but
remember to give appropriate credit) are encouraged.
\end_layout
\begin_layout Itemize
Include
\begin_inset Flex CMacro
status open
\begin_layout Plain Layout
Dprint()
\end_layout
\end_inset
statements so that if there is a
\begin_inset Flex CMacro
status open
\begin_layout Plain Layout
DEBUG
\end_layout
\end_inset
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.
\end_layout
\begin_layout Subsection
How the
\emph on
\begin_inset Formula $\binaryc$
\end_inset
\emph default
code works
\end_layout
\begin_layout Standard
\begin_inset CommandInset labelLatexCommand label
name "subsec:How-the-code"
\end_inset
The
\emph on
\begin_inset Formula $\binaryc$
\end_inset
\emph default
code, based on
\emph on
\begin_inset Flex Software
status open
\begin_layout Plain Layout
BSE
\end_layout
\end_inset
\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.
Its
\emph on
nucleosynthesis
\emph default
(
\begin_inset Quotes eld
\end_inset
\emph on
nucsyn
\emph default
\begin_inset Quotes erd
\end_inset
) 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! So as the
\emph on
\begin_inset Formula $\binaryc$
\end_inset
\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 \emph on
nucsyn
\emph default
code identifies when the surface abundances change.
\end_layout
\begin_layout Standard
\begin_inset CommandInset include
LatexCommand input
filename "binary_cV2.lyx"
\end_inset
\end_layout
\begin_layout Subsection
Code layout, header files, flow
\end_layout
\begin_layout Standard
\begin_inset CommandInset label
LatexCommand label
name "subsec:Code-layout"
\end_inset
The code is split into a series of directories.
Some header file information is in
\begin_inset CommandInset ref
LatexCommand ref
reference "subsec:Advanced-Configuration"
\end_inset
.
\end_layout
\begin_layout Subsubsection
API
\end_layout
\begin_layout Standard
You can build
\begin_inset Formula $\binaryc$
\end_inset
as a shared library, and enable the API interface.
The functions which do this are in this directory.
\end_layout
\begin_layout Subsubsection
batchmode
\end_layout
\begin_layout Standard
The batch mode functions handle the use of
\begin_inset Formula $\binaryc$
\end_inset
as part of
\begin_inset Formula $\binarygrid$
\end_inset
.
Essentially they are a loop wrapped around the evolution functions which
also scans arguments passed from
\begin_inset Formula $\binarygrid$
\end_inset
as if they were command line arguments.
\end_layout
\begin_layout Subsubsection
binary_star_functions
\end_layout
\begin_layout Standard
\begin_inset CommandInset label
LatexCommand label
name "subsec:binary_star_functions"
\end_inset
This directory contains functions which deal with the binary system such
as Roche-Lobe radius calculation, contact systems (
\begin_inset Flex SourceFile
status open
\begin_layout Plain Layout
contact_system.c
\end_layout
\end_inset
), stellar mergers (
\begin_inset Flex SourceFile
status open
\begin_layout Plain Layout
mix.c
\end_layout
\end_inset
) and common envelope evolution (
\begin_inset Flex SourceFile
status open
\begin_layout Plain Layout
common_envelope_evolution.c
\end_layout
\end_inset
).
\end_layout
\begin_layout Subsubsection
buffering
\end_layout
\begin_layout Standard
These functions provide an interface with
\emph on
\begin_inset Formula $\binarygrid$
\end_inset
\emph default
that improves buffering and hence
\emph on
\begin_inset Formula $\binarygrid$
\end_inset
\emph default
's performance.
When you use the
\begin_inset Flex CMacro
status open
\begin_layout Plain Layout
Printf
\end_layout
\end_inset
macro, rather than
\begin_inset Flex ProgrammingLanguage
status open
\begin_layout Plain Layout
C
\end_layout
\end_inset
's native
\begin_inset Flex CFunction
status open
\begin_layout Plain Layout
printf
\end_layout
\end_inset
routine, you are using the routines in here to put data into a memory buffer
which is then sent to
\begin_inset Formula $\binarygrid$
\end_inset
for processing and statistical analysis.
\end_layout
\begin_layout Standard
When you output with
\begin_inset Flex CMacro
status open
\begin_layout Plain Layout
Printf
\end_layout
\end_inset
your output either goes into a buffer or to the screen, according to the
parameter
\begin_inset Flex CVar
status open
\begin_layout Plain Layout
stardata->preferences->internal_buffering
\end_layout
\end_inset
.
You can access the buffer either through the internal
\begin_inset Flex CFunction
status open
\begin_layout Plain Layout
buffer_info
\end_layout
\end_inset
function, or the API's
\begin_inset Flex CFunction
status open
\begin_layout Plain Layout
binary_c_buffer_info
\end_layout
\end_inset
function.
\end_layout
\begin_layout Description
INTERNAL_BUFFERING_OFF Output to
\begin_inset Flex File
status open
\begin_layout Plain Layout
stdout
\end_layout
\end_inset
(no buffer is stored).
\end_layout
\begin_layout Description
INTERNAL_BUFFERING_PRINT Store in the buffer and dump the buffer's contents
to
\begin_inset Flex File
status open
\begin_layout Plain Layout
stdout
\end_layout
\end_inset
at the end of each timestep.
\end_layout
\begin_layout Description
INTERNAL_BUFFERING_STORE Store in the buffer for later use (this is probably
what you want if you are using the API).
\end_layout
\begin_layout Subsubsection
common_envelope
\end_layout
\begin_layout Standard
Common envelope evolution is dealt with in here.
At present there is only the
\begin_inset Flex Software
status open
\begin_layout Plain Layout
BSE
\end_layout
\end_inset
algorithm, but you could put your own in here too.
\end_layout
\begin_layout Subsubsectiondebug
\end_layout
\begin_layout Standard
This contains various debugging functions, such as
\begin_inset Flex CFunction
status open
\begin_layout Plain Layout
debug_fprintf
\end_layout
\end_inset
which is called when you put
\begin_inset Flex CMacro
status open
\begin_layout Plain Layout
Dprint
\end_layout
\end_inset
statements into
\begin_inset Formula $\binaryc$
\end_inset
.
The
\begin_inset Flex CFunction
status open
\begin_layout Plain Layout
backtrace
\end_layout
\end_inset
functionality is also in this directory, as is the
\begin_inset Flex CFunction
status open
\begin_layout Plain Layout
show_stardata
\end_layout
\end_inset
function which allows you to output, in a readable way, the contents of
a
\begin_inset Flex CStruct
status open
\begin_layout Plain Layout
stardata
\end_layout
\end_inset
structure.
Given this you can compare one structure's contents to another quickly
and easily.
\end_layout
\begin_layout Subsubsection
disc
\end_layout
\begin_layout StandardWork in progress, please ask RGI for details.
\end_layout
\begin_layout Subsubsection
envelope_intgeration
\end_layout
\begin_layout Standard
Experimental code.
\end_layout
\begin_layout Subsubsection
equation_of_state
\end_layout
\begin_layout Standard
Experimental code.
\end_layout
\begin_layout Subsubsection
events
\end_layout
\begin_layout Standard
See section
\begin_inset space ~
\end_inset
\begin_inset CommandInset ref
LatexCommand ref
reference "subsec:Events"
plural "false"
caps "false"
noprefix "false"
\end_inset
.
\end_layout
\begin_layout Subsubsection
evolution
\end_layout
\begin_layout Standard
\begin_inset CommandInset label
LatexCommand label
name "subsec:evolution"
\end_inset
The time integration, i.e.
evolution, of the binary system.
This contains the logic flow of the
\emph on
\begin_inset Formula $\binaryc$
\end_inset
\emph default
code.
Of interest to the general user are:
\end_layout
\begin_layout Itemize
\begin_inset Flex CFunction
status open
\begin_layout Plain Layout
evolve_system_binary_c
\end_layout
\end_inset
is the main time loop which sets up the system at its initiation, loops
over time (at each timestep calling
\begin_inset Flex CFunction
status open
\begin_layout Plain Layout
evolution
\end_layout
\end_inset
, see below) and then cleans up when things are all finished.
\end_layout
\begin_layout Itemize
\begin_inset Flex CFunction
status open
\begin_layout Plain Layout
evolution
\end_layout
\end_inset
The main time-evolution function.
This calls the appropriate integration scheme to further the binary system
under investigation in time.
The default scheme is forward-Euler, but Runge-Kutta 2nd and 4th order
are also available.
The function
\begin_inset Flex CFunction
status open
\begin_layout Plain Layout
evolution_step
\end_layout
\end_inset
in turn, for all the schemes, calls the other parts of
\begin_inset Formula $\binaryc$
\end_inset
that do all the appropriate physics.
\end_layout
\begin_layout Subsubsection
file
\end_layout
\begin_layout Standard
File input/output code.
\begin_inset Formula $\binaryc$
\end_inset
provides a custom file output routine which can limit output by size of
the file, as well as output filtering routines.
\end_layout
\begin_layout Subsubsection
galactic
\end_layout
\begin_layout Standard
Experimental! A set of routines to calculate apparent and bolometric luminositie
s, and develop a model of galactic coordinates.
It's not clear that we should be even doing this in
\begin_inset Formula $\binaryc$
\end_inset
\SpecialChar ldots
\end_layout
\begin_layout Subsubsection
libmemoize
\end_layout
\begin_layout Standard
This is a copy of RGI's memoizing library
\begin_inset Flex Software
status open
\begin_layout Plain Layout
libmemoize
\end_layout
\end_inset
.
The idea is that repeated calls to a function with the same arguments are
automatically cached so that the function is actually only called once.
Note: if you have
\begin_inset Flex Software
status open
\begin_layout Plain Layout
libmemoize
\end_layout
\end_inset
properly installed on your system, e.g.
in
\begin_inset Flex File
status open
\begin_layout Plain Layout
\begin_inset Flex Envvar
status open
\begin_layout Plain Layout
$HOME
\end_layout
\end_inset
/lib
\end_layout
\end_inset
or
\begin_inset Flex File
status open
\begin_layout Plain Layout
/usr/local/lib
\end_layout
\end_inset
, which is what you \emph on
should
\emph default
do, then the installed version is used.
The version in
\begin_inset Formula $\binaryc$
\end_inset
is a backup version only, and may lack the latest features.
\end_layout
\begin_layout Subsubsection
librinterpolate
\end_layout
\begin_layout Standard
This is a copy of RGI's
\begin_inset Flex Software
status open
\begin_layout Plain Layout
librinterpolate
\end_layout
\end_inset
linear interpolation library.
If you have
\begin_inset Flex Software
status open
\begin_layout Plain Layout
librinterpolate
\end_layout
\end_inset
installed properly, e.g.
in
\begin_inset Flex File
status open
\begin_layout Plain Layout
\begin_inset Flex Envvar
status open
\begin_layout Plain Layout
$HOME
\end_layout
\end_inset
/lib
\end_layout
\end_inset
or
\begin_inset Flex File
status open
\begin_layout Plain Layout
/usr/local/lib
\end_layout
\end_inset
, which is what you should do, then the version in
\begin_inset Formula $\binaryc$
\end_inset
is ignored.
\begin_inset Newline newline
\end_inset
Note:
\series bold
as of
\begin_inset Formula $\binarygrid2$
\end_inset
v2.17 you
\emph on
require
\emph default
\begin_inset Flex Software
status open
\begin_layout Plain Layout
\series bold
librinterpolate
\end_layout
\end_inset
for the
\begin_inset Flex Perlmodule
status open
\begin_layout Plain Layout
\series bold
distribution_functions
\end_layout
\end_inset
module and hence for
\begin_inset Formula $\binarygrid2$
\end_inset
to work.
\end_layout
\begin_layout Subsubsection
logging
\end_layout
\begin_layout Standard
\begin_inset CommandInset label
LatexCommand label
name "subsec:logging"
\end_inset
Contains some functions used to output either to the screen or a file.
Not very interesting but vital if you are to get anything out of
\begin_inset Formula $\binaryc$
\end_inset
.
\end_layout
\begin_layout Itemize
\begin_inset Flex CFunction
status open
\begin_layout Plain Layoutlog_every_timestep
\end_layout
\end_inset
which is called every (successful) timestep to output the current state
of the star.
This is where you want to put your logging code! Please remember: when
logging use the
\begin_inset Flex CMacro
status open
\begin_layout Plain Layout
Printf
\end_layout
\end_inset
macro, not
\begin_inset Flex ProgrammingLanguage
status open
\begin_layout Plain Layout
C
\end_layout
\end_inset
's
\begin_inset Flex CFunction
status open
\begin_layout Plain Layout
printf
\end_layout
\end_inset
-type function calls.
\end_layout
\begin_layout Subsubsection
maths
\end_layout
\begin_layout Standard
Contains a selection of routines to do some mathematical tasks that are
useful to
\emph on
\begin_inset Formula $\binaryc$
\end_inset
\emph default
, many of these routines are wrappers to
\begin_inset Flex Software
status open
\begin_layout Plain Layout
GSL
\end_layout
\end_inset
functions.
There are not-a-number (NaN) checking routines, random number generators,
a Kaps-Rentrop solver, a generic Brent minimizer, and the
\begin_inset Flex CFunction
status open
\begin_layout Plain Layout
apply_derivative
\end_layout
\end_inset
function which is used by
\begin_inset Flex CFunction
status open
\begin_layout Plain Layout
evolution
\end_layout
\end_inset
to integrate numerical derivatives at each timestep.
\end_layout
\begin_layout Itemize
Some of the code is experimental so probably not used.
\end_layout
\begin_layout Itemize
Anything you put in this directory must be free and freely distributable
software.
There are no routines from
\emph on
Numerical Recipes in C
\emph default
because these are not free software.
\end_layout
\begin_layout Subsubsection
memory
\end_layout
\begin_layout Standard
In here reside
\begin_inset Formula $\binaryc$
\end_inset
's memory allocation and freeing (garbage collection) routines.
\end_layout
\begin_layout Subsubsection
misc
\end_layout
\begin_layout Standard
Routines that don't go anywhere else.
At the moment this contains nothing.
\end_layout
\begin_layout Subsubsection
nucsyn
\end_layout
\begin_layout Standard
See section
\begin_inset space ~
\end_inset
\begin_inset CommandInset ref
LatexCommand ref
reference "subsec:nucsyn"
\end_inset
.
\end_layout
\begin_layout Subsubsection
opacity
\end_layout
\begin_layout Standard
Experimental.
\end_layout
\begin_layout Subsubsection
orbit
\end_layout
\begin_layout Standard
Routines which calculate orbital properties go in here.
\end_layout
\begin_layout Subsubsection
perl
\end_layout
\begin_layout Standard
Not strictly part of the
\emph on
\begin_inset Formula $\binaryc$
\end_inset
\emph default
\begin_inset Flex ProgrammingLanguage
status open
\begin_layout Plain Layout
C
\end_layout
\end_inset
source, but contains some useful
\begin_inset Flex ScriptingLanguage
status open
\begin_layout Plain Layout
Perl
\end_layout
\end_inset
modules (e.g.
\emph on
\begin_inset space ~
\end_inset
\begin_inset Formula $\binarygrid$
\end_inset
\emph default
) and scripts.
\end_layout
\begin_layout Subsubsection
python\end_layout
\begin_layout Standard
\begin_inset Flex ScriptingLanguage
status open
\begin_layout Plain Layout
Python
\end_layout
\end_inset
scripts, e.g.
to access the API through
\begin_inset Flex ScriptingLanguage
status open
\begin_layout Plain Layout
Python
\end_layout
\end_inset
, are in here.
\end_layout
\begin_layout Subsubsection
RLOF
\end_layout
\begin_layout Standard
\begin_inset CommandInset label
LatexCommand label
name "subsec:RLOF"
\end_inset
This has functions which deal with dynamical timescale Roche lobe overflow.
\end_layout
\begin_layout Standard
First, there is the question of when
\begin_inset Formula $R=R_{L}$
\end_inset
.
Because of limited time resolution, if RLOF happens then it starts with
\begin_inset Formula $R\gg R_{L}$
\end_inset
(the code overshoots the
\begin_inset Formula $R=R_{L}$
\end_inset
time).
In the original
\begin_inset Flex Software
status open
\begin_layout Plain Layout
BSE
\end_layout
\end_inset
code, and still in
\emph on
\begin_inset Formula $\binaryc$
\end_inset
\emph default
if you set
\begin_inset Flex Envvar
status open
\begin_layout Plain Layout
RLOF_interpolation_method=RLOF_INTERPOLATION_BSE(=1)
\end_layout
\end_inset
, interpolation in time is performed to find
\begin_inset Formula $R=R_{L}$
\end_inset
to within some threshold (usually 2%).
However, this means taking
\emph on
negative
\emph default
timesteps, which plays havoc with logging and nucleosynthesis algorithms.
\end_layout
\begin_layout Standard
In the latest
\emph on
\begin_inset Formula $\binaryc$
\end_inset
\emph default
, a simpler (albeit slower) algorithm is used which rejects the evolution
when
\begin_inset Formula $R\gg R_{L}.$
\end_inset
The previous
\begin_inset Flex CStruct
status open
\begin_layout Plain Layout
stardata
\end_layout
\end_inset
is loaded over the top of the current
\begin_inset Flex CStruct
status open
\begin_layout Plain Layout
stardata
\end_layout
\end_inset
, and the timestep is halved.
Evolution then continues until
\begin_inset Formula $R=R_{L}$
\end_inset
, to within a small threshold (e.g.
\begin_inset space ~
\end_inset
\begin_inset Formula $10^{-6}$
\end_inset
), always with a positive timestep.
\end_layout
\begin_layout Standard
RLOF itself is followed according to one of a number of algorithms.
First, the system is tested for the stability of RLOF (
\begin_inset Flex CFunction
status open
\begin_layout Plain Layout
RLOF_stability_tests
\end_layout
\end_inset
).
If RLOF is unstable, a merger or common envelope usually entails.
Second, if the RLOF is stable, there are several methods for calculating
the mass transfer rate.
The formulaic approach assumes that for a given
\begin_inset Formula $R\geq R_{L}$
\end_inset
there is a function,
\begin_inset Formula $\dot{M}(R-R_{L})$
\end_inset
, which gives the mass transfer rate.
This is numerically quite stable.
The alternative
\emph on
adpative
\emph default
approach consists of iterating to find a solution to
\begin_inset Formula $R=R_{L}$
\end_inset
.
This is more exact, but requires more calculation steps.
Usually, the two methods give similar answers, but if mass transfer is
particularly fast, e.g.
in massive stars, this may not be the case.
\end_layout
\begin_layout Subsubsection
\family typewriter
setup
\end_layout
\begin_layout Standard
\begin_inset CommandInset label
LatexCommand label
name "subsec:setup"
\end_inset
This sets the code up because
\begin_inset Flex CFunction
status open
\begin_layout Plain Layout
set_up_variables
\end_layout
\end_inset
is called by the
\begin_inset Flex CFunction
status open
\begin_layout Plain Layout
main
\end_layout
\end_inset
function.
It reads in the command line arguments and sets them to variables.
\end_layout
\begin_layout Standard
The
\begin_inset Flex CFunction
status open
\begin_layout Plain Layout
parse_arguments
\end_layout
\end_inset
function 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,
which should go into
\begin_inset Flex HeaderFile
status open
\begin_layout Plain Layout
cmd_line_args_list.h
\end_layout
\end_inset
.
\end_layout
\begin_layout Subsubsection
signals
\end_layout
\begin_layout Standard
\begin_inset Flex OS
status open
\begin_layout Plain Layout
Unix
\end_layout
\end_inset
/
\begin_inset Flex OS
status open
\begin_layout Plain Layout
Linux
\end_layout
\end_inset
uses signals to communicate with running programs.
Code in here allows you to catch signals, as well as catching (and trapping)
segmentation faults which is very useful for debugging (e.g.
with
\begin_inset Flex Software
status open
\begin_layout Plain Layout
gdb
\end_layout
\end_inset
and/or
\begin_inset Flex Software
status open
\begin_layout Plain Layout
valgrind
\end_layout
\end_inset
).
\end_layout
\begin_layout Subsubsection
single_star_functions
\end_layout
\begin_layout Standard
Many functions which only affect single star, or detached binary, evolution
are in this directory.
\end_layout
\begin_layout Subsubsection
spectra
\end_layout
\begin_layout Standard
Functions in here link stars, through their temperature and luminosity,
to spectra.
At present only a blackbody spectrum is supported, but the algorithm for
calculating the blackbody flux in regions of wavelength parameter space
is fast and accurate.
\end_layout
\begin_layout Subsubsection
stellar_colours
\end_layout
\begin_layout Standard
This contains some routines to calculate stellar colours, which may or may
not be reliable.
\end_layout
\begin_layout Subsubsection
stellar_structure
\end_layout
\begin_layout Standard
\begin_inset CommandInset label
LatexCommand label
name "subsec:stellar_structure"
\end_inset
Sets up a
\begin_inset Flex CStruct
status open
\begin_layout Plain Layout
new_structure
\end_layout
\end_inset
struct, and passes this to the appropriate stellar structure calculation
code.
Currently only
\family typewriter
stellar_structure_BSE
\family default
is available, but in future different codes may arise.
\end_layout
\begin_layout Standard
\begin_inset Flex CFunction
status open
\begin_layout Plain Layout
stellar_structure_BSE
\end_layout
\end_inset
is based on the
\begin_inset Flex FortranFunction
status open
\begin_layout Plain Layout
hrdiag
\end_layout
\end_inset
function of
\begin_inset Flex Software
status open
\begin_layout Plain Layout
SSE/BSE
\end_layout
\end_inset
.
It computes the stellar structure variables at a given time.
In addition, it handles supernova explosions and kicks.
Note that this functionality may eventually be removed from the stellar_structu
re directory.
\end_layout
\begin_layout Subsubsection
stellar_timescales
\end_layout
\begin_layout Standard
This set of functions calculates the timescales required by stellar_evolution,
as in the
\begin_inset Flex Software
status open
\begin_layout Plain Layout
SSE/BSE
\end_layout
\end_inset
stellar evolution package (in which it is the function \begin_inset Flex FortranFunction
status open
\begin_layout Plain Layout
star.f
\end_layout
\end_inset
, and in
\emph on
\begin_inset Formula $\binaryc$
\end_inset
\emph default
V1.x it is
\begin_inset Flex CFunction
status open
\begin_layout Plain Layout
calc_lum_and_evol_time
\end_layout
\end_inset
in
\begin_inset Flex File
status open
\begin_layout Plain Layout
claet
\end_layout
\end_inset
).
\end_layout
\begin_layout Subsubsection
string
\end_layout
\begin_layout Standard
Functions to manipulate strings go in here, including
\begin_inset Flex CFunction
status open
\begin_layout Plain Layout
binary_c_asprintf
\end_layout
\end_inset
(to replace asprintf if
\begin_inset Flex Software
status open
\begin_layout Plain Layout
Gnu
\end_layout
\end_inset
or
\begin_inset Flex Software
status open
\begin_layout Plain Layoutlibbsd
\end_layout
\end_inset
's version is not available) and
\begin_inset Flex CFunction
status open
\begin_layout Plain Layout
chomp
\end_layout
\end_inset
(to remove newlines at the end of a string, identical to
\begin_inset Flex ScriptingLanguage
status open
\begin_layout Plain Layout
Perl
\end_layout
\end_inset
's
\begin_inset Flex Perlcode
status open
\begin_layout Plain Layout
chomp
\end_layout
\end_inset
).
\end_layout
\begin_layout Subsubsection
supernovae
\end_layout
\begin_layout Standard
Functions which deal with supernovae, e.g.
\begin_inset space ~
\end_inset
kicks, NS/BH mass as a function of progentior, etc.
Note that supernovae are dealt with at the end of a timestep as an event
(see section
\begin_inset space ~
\end_inset
\begin_inset CommandInset ref
LatexCommand ref
reference "subsec:Events"
plural "false"
caps "false"
noprefix "false"
\end_inset
).
\end_layout
\begin_layout Subsubsection
tables
\end_layout
\begin_layout Standard
Various tables of data, used by
\begin_inset Flex Software
status open
\begin_layout Plain Layout
librinterpolate
\end_layout
\end_inset
, are included in
\begin_inset Formula $\binaryc$
\end_inset
.
This directory contains the data for them and the various setup functions.
In future, this data may be held elsewhere and its location accessed through
an environment variable.
\begin_inset Newline newline
\end_inset
Note:
\series bold
as of
\begin_inset Formula $\binarygrid2$
\end_inset
v2.17 you
\emph on
require
\emph default
\begin_inset Flex Software
status open
\begin_layout Plain Layout
\series bold
librinterpolate
\end_layout
\end_inset
for the
\begin_inset Flex Perlmodule
status open
\begin_layout Plain Layout
\series bold
distribution_functions
\end_layout
\end_inset
module and hence for
\begin_inset Formula $\binarygrid2$
\end_inset
to work.
\end_layout
\begin_layout Subsubsection
timers
\end_layout
\begin_layout Standard
These are functions which start and stop the ticks counters.
They are used to measure CPU time use, i.e.\begin_inset space ~
\end_inset
profiling of the code.
Note that there are many ways to profile (including e.g.
\begin_inset space ~
\end_inset
\begin_inset Flex Software
status open
\begin_layout Plain Layout
cachegrind
\end_layout
\end_inset
and
\begin_inset Flex Software
status open
\begin_layout Plain Layout
callgrind
\end_layout
\end_inset
, functions of
\begin_inset Flex Software
status open
\begin_layout Plain Layout
valgrind
\end_layout
\end_inset
, and the ever reliable
\begin_inset Flex Software
status open
\begin_layout Plain Layout
gprof
\end_layout
\end_inset
).
\end_layout
\begin_layout Subsubsection
timestep
\end_layout
\begin_layout Standard
Routines for calculating the stellar timestep, see the function
\begin_inset Flex CFunction
status open
\begin_layout Plain Layout
stellar_timestep
\end_layout
\end_inset
for details.
\end_layout
\begin_layout Subsubsectiontriple_star_functions
\end_layout
\begin_layout Standard
Experimental! As the name suggests, these are functions to calculate the
various physics in triple stars.
\end_layout
\begin_layout Subsubsection
wind
\end_layout
\begin_layout Standard
Routines for calculating the stellar wind loss rate.
Note that the main function that calculates the wind mass-loss rate is
actually in
\begin_inset Flex File
status open
\begin_layout Plain Layout
src/single_star_functions/calc_stellar_wind_mass_loss.c
\end_layout
\end_inset
but that just calls
\begin_inset Flex CFunction
status open
\begin_layout Plain Layout
wind_mass_loss_rate
\end_layout
\end_inset
which is in this directory.
\end_layout
\begin_layout Subsubsection
zfuncs
\end_layout
\begin_layout Standard
\begin_inset CommandInset label
LatexCommand label
name "subsec:zfuncs"
\end_inset
The so called
\begin_inset Quotes eld
\end_inset
metallicity functions
\begin_inset Quotes erd
\end_inset
of
\begin_inset Flex Software
status open
\begin_layout Plain Layout
BSE
\end_layout
\end_inset
i.e.
\begin_inset space ~
\end_inset
the many fits to
\begin_inset Formula $L$
\end_inset
,
\begin_inset Formula $R$
\end_inset
,
\begin_inset Formula $M_{\textrm{c}}$
\end_inset
etc.
\begin_inset space ~
\end_inset
as a function of
\begin_inset Formula $M$
\end_inset
and
\begin_inset Formula $Z$
\end_inset
(and perhaps other parameters).
These are lots of tiny functions which contain fitting formulae.
\end_layout
\begin_layout Standard
Lately I have added some new functions, such as
\begin_inset Flex CFunction
status open
\begin_layout Plain Layout
mc_1DUP
\end_layout
\end_inset
(the core mass at which first dredge up occurs),
\begin_inset Flex CFunction
status open
\begin_layout Plain Layout
fphase
\end_layout
\end_inset
(the fractional age in a given stellar evolution phase),
\begin_inset Flex CFunction
status open
\begin_layout Plain Layout
rwd
\end_layout
\end_inset
and
\begin_inset Flex CFunction
status open
\begin_layout Plain Layout
lwd
\end_layout
\end_inset
(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 because they
are called very often.
\end_layout
\begin_layout Subsection
nucsyn
\end_layout
\begin_layout Standard
\begin_inset CommandInset label
LatexCommand label
name "subsec: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
\begin_inset Flex Software
status open
\begin_layout Plain Layout
SSE/BSE
\end_layout
\end_inset
.
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
\begin_inset listings
lstparams "language=C"
inline false
status open
\begin_layout Plain Layout
#define NUCSYN
\end_layout
\end_inset
\end_layout
\begin_layout Standard
somewhere, usually in
\begin_inset Flex HeaderFile
status open
\begin_layout Plain Layout
binary_c_parameters.h
\end_layout
\end_inset
(which gets included in
\begin_inset Flex HeaderFile
status open
\begin_layout Plain Layout
binary_c_macros.h
\end_layout
\end_inset
so
\begin_inset Flex HeaderFile
status open
\begin_layout Plain Layout
nucsyn.h
\end_layout
\end_inset
– you should include
\begin_inset Flex HeaderFile
status open
\begin_layout Plain Layout
nucsyn.h
\end_layout
\end_inset
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
\begin_inset listings
lstparams "language=C"
inline false
status open
\begin_layout Plain Layout
#ifdef NUCSYN
\end_layout
\begin_layout Plain Layout
...
\end_layout
\begin_layout Plain Layout
#endif /* NUCSYN */
\end_layout
\end_inset
\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
\begin_inset Flex HeaderFile
status open
\begin_layout Plain Layout
nucsyn_parameters.h
\end_layout
\end_inset
(see section
\begin_inset CommandInset ref
LatexCommand ref
reference "subsec:Advanced-Configuration"
\end_inset
).
\end_layout
\begin_layout Standard
NOTE!
\emph on
Every function in the nucsyn library has
\emph default
\begin_inset Flex CFunction
status open
\begin_layout Plain Layout
nucsyn
\end_layout
\end_inset
\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 "subsec: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
\begin_inset Flex CMacro
status open
\begin_layout Plain Layout
ISOTOPE_ARRAY_SIZE
\end_layout
\end_inset
which is defined in
\begin_inset Flex HeaderFile
status open
\begin_layout Plain Layout
nucsyn_isotopes.h
\end_layout
\end_inset
however you should
\emph on
NEVER
\emph default
manually access the array by number, e.g.
\family typewriter
\begin_inset space ~
\end_inset
\begin_inset listings
inline false
status open
\begin_layout Plain Layout
X[0]=0.5;
\end_layout
\end_inset
\family default
you should use the predefined macros referring to each isotope in
\begin_inset Flex HeaderFile
status open
\begin_layout Plain Layout
nucsyn_isotopes.h
\end_layout
\end_inset
and
\begin_inset Flex HeaderFile
status open
\begin_layout Plain Layout
nucsyn_isotope_list.h
\end_layout
\end_inset
.
For example,
\begin_inset Flex CMacro
status open
\begin_layout Plain Layout
XC12
\end_layout
\end_inset
is defined like this
\begin_inset Foot
status collapsed
\begin_layout Plain Layout
Actually, in a modern
\begin_inset Formula $\binaryc$
\end_inset
, it is defined to be one more than the previous isotope.
This is just an integer, of course, and you don't care what that integer
is.
\end_layout
\end_inset
,
\end_layout
\begin_layout Standard
\family typewriter
\begin_inset listings
inline false
status open
\begin_layout Plain Layout
#define XC12 2
\end_layout
\end_inset
\family default
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
\begin_inset listings
inline false
status open
\begin_layout Plain Layout
X[XC12]=0.5;
\end_layout
\begin_layout Plain Layout
/* or, similarly */
\end_layout
\begin_layout Plain Layout
N[XC12]=1e-8;
\end_layout
\end_inset
Perhaps also useful for you is \begin_inset Flex CMacro
status open
\begin_layout Plain Layout
ISOTOPE_MEMSIZE
\end_layout
\end_inset
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 "subsec: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 "subsec:Setup-functions"
\end_inset
\begin_inset Flex CFunction
status open
\begin_layout Plain Layout
nucsyn_set_nuc_masses
\end_layout
\end_inset
sets the nuclear masses (in grams) and atomic numbers.
If you add an isotope to
\begin_inset Flex HeaderFile
status open
\begin_layout Plain Layout
nucsyn_isotopes.h
\end_layout
\end_inset
(see section
\begin_inset CommandInset ref
LatexCommand ref
reference "subsec: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 (and
\begin_inset Flex Software
status open
\begin_layout Plain Layout
valgrind
\end_layout
\end_inset
will immediately fail because you'll be reading from undefined memory).
\end_layout
\begin_layout Standard
\begin_inset Flex CFunction
status open
\begin_layout Plain Layout
nucsyn_initial_abundances
\end_layout
\end_inset
is obviously important because it defines your initial abundance mix, usually
as a function of the metallicity.
\end_layout
\begin_layout Subsubsection
First and Second Dredge-up
\end_layout
\begin_layout Standard
\begin_inset CommandInset label
LatexCommand label
name "subsec:First-and-Second-DUP"
\end_inset
First and second dredge-up are handled by the functions
\begin_inset Flex CFunction
status open
\begin_layout Plain Layout
nucsyn_set_1st_dup_abunds
\end_layout
\end_inset
and
\begin_inset Flex CFunction
status open
\begin_layout Plain Layout
nucsyn_set_2nd_dup_abunds
\end_layout
\end_inset
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 "subsec: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"
literal "true"
\end_inset
).
This is controlled by the function
\family typewriter
\begin_inset Flex CFunction
status open
\begin_layout Plain Layout
\family typewriter
nucsyn_tpagb
\end_layout
\end_inset
\family default
.
The function 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 [HBB]).
\end_layout
\begin_layout Standard
On the first pulse (when the function is first called for the star, actually
if
\begin_inset listings
lstparams "language=C"
inline true
status open
\begin_layout Plain Layout
num_thermal_pulses < 0
\end_layout
\end_inset
, which is the case for any stellar type other than TPAGB) the function
\begin_inset Flex CFunction
status open
\begin_layout Plain Layout
nucsyn_init_first_pulse
\end_layout
\end_inset
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
\begin_inset Flex CFunction
status open
\begin_layout Plain Layout
nucsyn_tpagb function
\end_layout
\end_inset
calls
\begin_inset Flex CFunction
status open
\begin_layout Plain Layout
nucsyn_tpagb_H_shell_burn
\end_layout
\end_inset
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
\begin_inset Flex CFunction
status open
\begin_layout Plain Layout
nucsyn_set_hbb_conditions
\end_layout
\end_inset
,
\begin_inset Flex CFunction
status open
\begin_layout Plain Layout
nucsyn_hbbtmax
\end_layout
\end_inset
and \begin_inset Flex CFunction
status open
\begin_layout Plain Layout
nucsyn_tpagb_rhomax
\end_layout
\end_inset
) to mass and metallicity.
If so the
\begin_inset Flex CFunction
status open
\begin_layout Plain Layout
nucsyn_hbb
\end_layout
\end_inset
function is called.
The free parameters associated with HBB
\begin_inset CommandInset citation
LatexCommand citep
key "Izzard_et_al_2003b_AGBs"
literal "true"
\end_inset
are set in
\begin_inset Flex CFunction
status open
\begin_layout Plain Layout
nucsyn_set_tpagb_free_parameters
\end_layout
\end_inset
(these are the burn times, mixing fractions etc.).
\end_layout
\begin_layout Standard
If the next pulse is reached then
\begin_inset Flex CFunction
status open
\begin_layout Plain Layout
nucsyn_third_dredge_up
\end_layout
\end_inset
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
\begin_inset Flex CFunction
status open
\begin_layout Plain Layout
nucsyn_set_third_dredgeup_abunds
\end_layout
\end_inset
(and \begin_inset Flex CFunction
status open
\begin_layout Plain Layout
nucsyn_s_process for s-process
\end_layout
\end_inset
elements).
\end_layout
\begin_layout Standard
Version 1.2 of
\begin_inset Formula $\binaryc$
\end_inset
included an option to evolve
\begin_inset Quotes eld
\end_inset
super AGB
\begin_inset Quotes erd
\end_inset
(STPAGB) stars but this has since been deprecated.
\end_layout
\begin_layout Subsubsection
Hot-Bottom Burning
\end_layout
\begin_layout Standard
\begin_inset CommandInset label
LatexCommand label
name "subsec: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 "subsec: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.
Thanks Richard!
\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 "subsec:The-r-process"
\end_inset
I have included some yields from
\begin_inset CommandInset citation
LatexCommand citet
key "1999ApJ...525..886A"
literal "true"
\end_inset
and \begin_inset CommandInset citation
LatexCommand citet
key "2004ApJ...617.1091S"
literal "true"
\end_inset
which you can activate with the appropriate define in
\begin_inset Flex HeaderFile
status open
\begin_layout Plain Layout
nucsyn_parameters.h
\end_layout
\end_inset
.
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 "subsec:Winds-and-Mixing"
\end_inset
Colliding winds and the like are a complicated business!
\begin_inset Flex CFunction
status open
\begin_layout Plain Layout
nucsyn_update_abundances
\end_layout
\end_inset
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, determines whether the accreted matter should reach the
surface (by the factor set in
\begin_inset Flex CFunction
status open
\begin_layout Plain Layout
nucsyn_choose_wind_mixing_factor
\end_layout
\end_inset
) 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
\begin_inset Flex CFunction
status open
\begin_layout Plain Layout
nucsyn_calc_yields
\end_layout
\end_inset
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
\begin_inset Flex CFunction
status open
\begin_layout Plain Layout
nucsyn_remove_dm_from_surface
\end_layout
\end_inset
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
\begin_inset Flex CFunction
status open
\begin_layout Plain Layout
nucsyn_mix_accretion_layer_and_envelope
\end_layout
\end_inset
soon removes it.
\end_layout
\begin_layout Subsubsection
Explosions (supernovae and novae)
\end_layout
\begin_layout Standard
\begin_inset CommandInset label
LatexCommand label
name "subsec:Explosions"
\end_inset
Supernova yields are looked up in tables and yielded in
\begin_inset Flex CFunction
status open
\begin_layout Plain Layout
nucsyn_sn_yield
\end_layout
\end_inset
.
Nova ejecta are calculated in
\begin_inset Flex CFunction
status open
\begin_layout Plain Layout
nucsyn_set_nova_abunds
\end_layout
\end_inset
.
\end_layout
\begin_layout Subsubsection
Yield calculations
\end_layout
\begin_layout Standard
\begin_inset CommandInset label
LatexCommand label
name "subsec:Yield-calculations"
\end_inset
The calls to
\begin_inset Flex CFunction
status open
\begin_layout Plain Layout
nucsyn_calc_yields
\end_layout
\end_inset
modify the arrays
\begin_inset Flex CVar
status open
\begin_layout Plain Layout
Xyield
\end_layout
\end_inset
in the star structures.
These contain the mass of material of each isotope lost by the star, so
if
\begin_inset Flex CFunction
status open
\begin_layout Plain Layout
nucsyn_calc_yields
\end_layout
\end_inset
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
\begin_inset Flex CVar
status open
\begin_layout Plain Layout
Xyield
\end_layout
\end_inset
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
\begin_inset Flex CFunctionstatus open
\begin_layout Plain Layout
nucsyn_calc_yields
\end_layout
\end_inset
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
\begin_inset Flex CVar
status open
\begin_layout Plain Layout
Xyield
\end_layout
\end_inset
for both stars.
\end_layout
\begin_layout Standard
The array
\begin_inset Flex CVar
status open
\begin_layout Plain Layout
mpyield
\end_layout
\end_inset
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
\begin_inset Flex CVar
status open
\begin_layout Plain Layout
pms_mass
\end_layout
\end_inset
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
\begin_inset Flex CFunction
status open
\begin_layout Plain Layout
nucsyn_binary_yield
\end_layout
\end_inset
.
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 "subsec:Logging-and-minor-functions"
\end_inset
There are numerous logging functions for debugging and general pretty-picture-ma
nufacture, e.g.
\begin_inset Flex CFunction
status open
\begin_layout Plain Layout
\family typewriter
nucsyn_log
\end_layout
\end_inset
,
\begin_inset Flex CFunction
status open
\begin_layout Plain Layout
\family typewriter
nucsyn_long_log
\end_layout
\end_inset
,
\family typewriter
\begin_inset Flex CFunction
status open
\begin_layout Plain Layout
\family typewriternucsyn_short_log
\end_layout
\end_inset
\family default
,
\begin_inset Flex CFunction
status open
\begin_layout Plain Layout
\family typewriter
nucsyn_j_log
\end_layout
\end_inset
.
Most of these are activated or deactivated in
\begin_inset Flex HeaderFile
status open
\begin_layout Plain Layout
nucsyn_log.h
\end_layout
\end_inset
.
Other minor functions:
\family typewriter
\begin_inset Flex CFunction
status open
\begin_layout Plain Layout
\family typewriter
nucsyn_totalX
\end_layout
\end_inset
\family default
calculates the total mass fraction (or actually the total sum of array
elements),
\family typewriter
\begin_inset Flex CFunction
status open
\begin_layout Plain Layout
\family typewriter
nucsyn_square_bracket
\end_layout
\end_inset
\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
\begin_inset Flex CFunction
status open
\begin_layout Plain Layout
\family typewriter
nucsyn_mix_shells
\end_layout
\end_inset
\family default
mixes two isotope arrays together (very useful!) there are the other mixing
functions
\family typewriter
\begin_inset Flex CFunction
status open
\begin_layout Plain Layout
\family typewriter
nucsyn_dilute_shell
\end_layout
\end_inset
\family default
and
\family typewriter
\begin_inset Flex CFunction
status open
\begin_layout Plain Layout
\family typewriter
nucsyn_dilulte_shell_to
\end_layout
\end_inset
\family default
which are similarly useful;
\family typewriter
\begin_inset Flex CFunction
status open
\begin_layout Plain Layout
\family typewriter
nucsyn_radioactive_decay
\end_layout
\end_inset
\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
\begin_inset Flex CFunction
status open
\begin_layout Plain Layout
\family typewriter
nucsyn_mole_fraction
\end_layout
\end_inset
\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 "subsec: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:
\begin_inset Flex CMacro
status open
\begin_layout Plain Layout
HeWD
\end_layout
\end_inset
100%
\begin_inset Formula $^{4}\textrm{He}$
\end_inset
,
\begin_inset Flex CFunction
status open
\begin_layout Plain Layout
COWD
\end_layout
\end_inset
80%
\begin_inset Formula $^{12}\textrm{C}$
\end_inset
and 20%
\begin_inset Formula $^{16}\textrm{O}$
\end_inset
while
\begin_inset Flex CMacro
status open
\begin_layout Plain Layout
ONeWD
\end_layout
\end_inset
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 very complicated indeed.
\end_layout
\begin_layout Standard
NSs and BHs are remnants with their abundances set in
\family typewriter
\begin_inset Flex CFunction
status open
\begin_layout Plain Layout
\family typewriter
nucsyn_set_remnant_abunds
\end_layout
\end_inset
\family default
are assumed to be all neutrons with
\family typewriter
\begin_inset listings
lstparams "language=C"
inline false
status open
\begin_layout Plain Layout
Xsurf[Xn]=1.0;
\end_layout
\end_inset
\end_layout
\begin_layout Subsection
Coding style
\end_layout
\begin_layout Standard
\begin_inset Formula $\binaryc$
\end_inset
C code follows a particular style to which you should adhere.
More reading at
\begin_inset Flex URL
status collapsed
\begin_layout Plain Layout
https://gcc.gnu.org/onlinedocs/gcc/Standards.html
\end_layout
\end_inset
.
\end_layout
\begin_layout Itemize
We require that the compiler supports C11 constructs with GNU extensions.
This means GCC 4.9 or later.
Our standard is equivalent to the
\begin_inset Flex Software
status open
\begin_layout Plain Layout
GCC
\end_layout
\end_inset
compiler flag
\begin_inset Flex Args
status open
\begin_layout Plain Layout
c_std=gnu11
\end_layout
\end_inset
.
\end_layout
\begin_layout Itemize
The
\begin_inset Formula $\binaryc$
\end_inset
style is based on the
\begin_inset CommandInset href
LatexCommand href
name "Allman style"
target "https://en.wikipedia.org/wiki/Indentation_style#Allman_style"
literal "false"
\end_inset
with a few minor changes.
\end_layout
\begin_deeper
\begin_layout Itemize
This means
\begin_inset Flex CFunction
status open
\begin_layout Plain Layout
for
\end_layout
\end_inset
and
\begin_inset Flex CFunction
status open
\begin_layout Plain Layoutwhile
\end_layout
\end_inset
loops are like this
\begin_inset listings
lstparams "language=C"
inline false
status open
\begin_layout Plain Layout
for(i=0; i<10; i++)
\end_layout
\begin_layout Plain Layout
{
\end_layout
\begin_layout Plain Layout
...
\end_layout
\begin_layout Plain Layout
}
\end_layout
\end_inset
\end_layout
\begin_layout Itemize
\begin_inset Flex CFunction
status open
\begin_layout Plain Layout
If
\end_layout
\end_inset
statements are like this
\begin_inset listings
lstparams "language=C"
inline false
status open
\begin_layout Plain Layout
if(x == TRUE)
\end_layout
\begin_layout Plain Layout
{
\end_layout
\begin_layout Plain Layout
...
\end_layout
\begin_layout Plain Layout
}\end_layout
\end_inset
please be explicit: do not just use
\begin_inset listings
lstparams "language=C"
inline true
status open
\begin_layout Plain Layout
if(x)
\end_layout
\end_inset
except in testing.
Please use spaces around operators, so
\begin_inset listings
lstparams "language=C"
inline false
status open
\begin_layout Plain Layout
if(x == TRUE) // good
\end_layout
\begin_layout Plain Layout
if(x==TRUE) // bad
\end_layout
\end_inset
\end_layout
\begin_layout Itemize
Note that there is
\series bold
\emph on
no space after the constructor
\series default
\emph default
(
\begin_inset Flex CFunction
status open
\begin_layout Plain Layout
\emph off
for
\end_layout
\end_inset
,
\begin_inset Flex CFunction
status open
\begin_layout Plain Layout
\emph off
if
\end_layout
\end_inset
, \SpecialChar ldots
)\SpecialChar endofsentence
\begin_inset listings
lstparams "language=C"
inline false
status open
\begin_layout Plain Layout
for (i=0; i<10; i++) // wrong!
\end_layout
\begin_layout Plain Layout
{
\end_layout
\begin_layout Plain Layout
...
\end_layout
\begin_layout Plain Layout
}
\end_layout
\end_inset
\end_layout
\begin_layout Itemize
Try to keep lines short, shorter than 80 characters if possible.
\begin_inset listings
lstparams "language=C"
inline false
status open
\begin_layout Plain Layout
/* this is good */
\end_layout
\begin_layout Plain Layout
printf("got nstrings = %ld : %s, %s, %s...
\backslash
n",
\end_layout
\begin_layout Plain Layout
nstrings,
\end_layout
\begin_layout Plain Layout
nstrings >= 1 ? strings[0] : "",
\end_layout
\begin_layout Plain Layout
nstrings >= 2 ? strings[1] : "",
\end_layout
\begin_layout Plain Layout
nstrings >= 3 ? strings[2] : "");\end_layout
\begin_layout Plain Layout
/* this is bad */
\end_layout
\begin_layout Plain Layout
printf("got nstrings = %ld : %s, %s, %s...
\backslash
n",nstrings,nstrings >= 1 ? strings[0] : "",nstrings >= 2 ? strings[1] :
"",nstrings >= 3 ? strings[2] : "");
\end_layout
\end_inset
\end_layout
\begin_layout Itemize
All warnings from the compiler are considered to be bugs.
We build with
\begin_inset Flex CFlags
status open
\begin_layout Plain Layout
-Wpedantic
\end_layout
\end_inset
for a reason.
\end_layout
\end_deeper
\begin_layout Itemize
Indent with four spaces (
\begin_inset CommandInset href
LatexCommand href
name "emacs"
target "https://www.gnu.org/software/emacs/"
literal "false"
\end_inset
indents
\begin_inset Flex ProgrammingLanguage
status open
\begin_layout Plain Layout
C
\end_layout
\end_inset
like this automatically)
\begin_inset listings
lstparams "language=C"
inline false
status open
\begin_layout Plain Layout
{
\end_layout
\begin_layout Plain Layout
bad\end_layout
\begin_layout Plain Layout
bad
\end_layout
\begin_layout Plain Layout
bad
\end_layout
\begin_layout Plain Layout
good
\end_layout
\begin_layout Plain Layout
}
\end_layout
\end_inset
\end_layout
\begin_layout Itemize
Comments should be multi-lined for enhanced legibility
\begin_inset listings
lstparams "language=C"
inline false
status open
\begin_layout Plain Layout
/*
\end_layout
\begin_layout Plain Layout
* This is a good comment
\end_layout
\begin_layout Plain Layout
*/
\end_layout
\begin_layout Plain Layout
\end_layout
\begin_layout Plain Layout
/* This is an ugly comment, ok for temporary work */
\end_layout
\begin_layout Plain Layout
\end_layout
\begin_layout Plain Layout
// This is a bad comment
\end_layout
\end_inset
the exception is after \begin_inset listings
lstparams "language=C"
inline true
status open
\begin_layout Plain Layout
#endif
\end_layout
\end_inset
e.g.,
\begin_inset listings
lstparams "language=C"
inline false
status open
\begin_layout Plain Layout
#endif // This is a good comment
\end_layout
\end_inset
\end_layout
\begin_layout Subsubsection
Macros
\end_layout
\begin_layout Standard
C preprocessor macros are a very powerful way to make code more readable,
or less, depending on their use, hence
\begin_inset Formula $\binaryc$
\end_inset
has strict rules for their use.
\end_layout
\begin_layout Itemize
Macros used as flags should use
\begin_inset Flex CMacro
status open
\begin_layout Plain Layout
CAPTIALS
\end_layout
\end_inset
and, when used in
\begin_inset Flex CMacro
status open
\begin_layout Plain Layout
#ifdef \SpecialChar ldots
#endif
\end_layout
\end_inset
pairs, you should include a comment at the end of the pair to say specify
the opening macro, for example.
\begin_inset listings
inline false
status open
\begin_layout Plain Layout
#define FLAG_MACRO
\end_layout
\begin_layout Plain Layout
\end_layout
\begin_layout Plain Layout
\end_layout
\begin_layout Plain Layout
#ifdef FLAG_MACRO
\end_layout
\begin_layout Plain Layout
\end_layout
\begin_layout Plain Layout
...
do stuff
\end_layout
\begin_layout Plain Layout
\end_layout
\begin_layout Plain Layout
#endif // FLAG_MACRO
\end_layout
\end_inset
\end_layout
\begin_layout Itemize
Constant macros should use upper case, e.g.,
\begin_inset listings
inline false
status open
\begin_layout Plain Layout
#define CONSTANT_MACRO 3
\end_layout
\end_inset
\end_layout
\begin_layout Itemize
Function macros should be named with the first character in upper case,
the rest in lower case, and when you address arguments remember to wrap
them in parentheses, e.g.,
\begin_inset listings
lstparams "language=C"
inline false
status open
\begin_layout Plain Layout
#define Pow2(X) ((X)*(X))\end_layout
\begin_layout Plain Layout
#define Other_star(K) ((K)==0 ? 1 : 0)
\end_layout
\end_inset
exceptions to this are the macros used for stellar types,
\begin_inset Flex CMacro
status open
\begin_layout Plain Layout
PRINTF
\end_layout
\end_inset
which is just mapped to
\begin_inset Flex CMacro
status open
\begin_layout Plain Layout
Printf
\end_layout
\end_inset
for backward compatibility, and macros such as
\begin_inset Flex CMacro
status open
\begin_layout Plain Layout
likley
\end_layout
\end_inset
and
\begin_inset Flex CMacro
status open
\begin_layout Plain Layout
unlikley
\end_layout
\end_inset
which are kept in lower case to match external code (in this case the
\begin_inset Flex OS
status open
\begin_layout Plain Layout
Linux
\end_layout
\end_inset
kernel).
\begin_inset Newline newline
\end_inset
Most function macros are in
\begin_inset Flex File
status open
\begin_layout Plain Layout
binary_c_function_macros.h
\end_layout
\end_inset
.
\end_layout
\begin_layout Itemize
You should
\series bold
\emph on
NOT
\series default
\emph default
use
\begin_inset Flex CMacro
status open
\begin_layout Plain Layout
X
\end_layout
\end_inset
as a function macro name.
\begin_inset Formula $\binaryc$
\end_inset
uses X-macros
\begin_inset Foot
status collapsed
\begin_layout Plain Layout
\begin_inset Flex URL
status collapsed
\begin_layout Plain Layout
https://en.wikipedia.org/wiki/X_Macro
\end_layout
\end_inset
\end_layout
\end_inset
, so requires
\begin_inset Flex CMacro
status open
\begin_layout Plain Layout
X
\end_layout
\end_inset
to be free for those, not for your work.
If you do use
\begin_inset Flex CMacro
status open
\begin_layout Plain Layout
X
\end_layout
\end_inset
as a function macro, expect it to be destroyed randomly.\end_layout
\begin_layout Itemize
Macros which are used only locally, and variables used in macro expressions,
should be prefixed with two underscores, as is standard in
\begin_inset Flex ProgrammingLanguage
status open
\begin_layout Plain Layout
C
\end_layout
\end_inset
.
\begin_inset listings
lstparams "language=C"
inline false
status open
\begin_layout Plain Layout
#define __LOCAL_MACRO 1
\end_layout
\end_inset
\end_layout
\begin_layout Itemize
When comparing to
\begin_inset Flex CMacro
status open
\begin_layout Plain Layout
TRUE
\end_layout
\end_inset
and
\begin_inset Flex CMacro
status open
\begin_layout Plain Layout
FALSE
\end_layout
\end_inset
, please be explicit, i.e.
\begin_inset space ~
\end_inset
\begin_inset listings
lstparams "language=C"
inline true
status open
\begin_layout Plain Layout
== TRUE
\end_layout
\end_inset
or
\begin_inset listingslstparams "language=C"
inline true
status open
\begin_layout Plain Layout
== FALSE
\end_layout
\end_inset
, e.g.,
\begin_inset listings
lstparams "language=C"
inline false
status open
\begin_layout Plain Layout
if(vb == TRUE)
\end_layout
\begin_layout Plain Layout
{
\end_layout
\begin_layout Plain Layout
/* ...
do something ...
*/
\end_layout
\begin_layout Plain Layout
}
\end_layout
\end_inset
\end_layout
\begin_layout Itemize
You are free to use
\begin_inset Flex Software
status open
\begin_layout Plain Layout
GCC
\end_layout
\end_inset
's statement expressions (
\begin_inset Flex URL
status open
\begin_layout Plain Layout
https://gcc.gnu.org/onlinedocs/gcc/Statement-Exprs.html
\end_layout
\end_inset
) but please prefix them with
\begin_inset listings
lstparams "language=C"
inline truestatus open
\begin_layout Plain Layout
__extension__
\end_layout
\end_inset
and wrap them in
\begin_inset listings
lstparams "language=C"
inline false
status open
\begin_layout Plain Layout
#ifdef USE_GCC_EXTENSIONS
\end_layout
\begin_layout Plain Layout
...
/* the macro you want to use */
\end_layout
\begin_layout Plain Layout
#else
\end_layout
\begin_layout Plain Layout
...
/* fallback code */
\end_layout
\begin_layout Plain Layout
#endif // USE_GCC_EXTENSIONS
\end_layout
\end_inset
The macro
\begin_inset Flex CMacro
status open
\begin_layout Plain Layout
USE_GCC_EXTENSIONS
\end_layout
\end_inset
may, or may not, be defined, depending on your compiler.
With a modern
\begin_inset Flex Software
status open
\begin_layout Plain Layout
GCC
\end_layout
\end_inset
or
\begin_inset Flex Software
status open
\begin_layout Plain LayoutClang
\end_layout
\end_inset
, it is, but please do not rely on this.
\begin_inset Newline newline
\end_inset
Note that some software used by
\begin_inset Formula $\binaryc$
\end_inset
now
\emph on
requires
\emph default
\begin_inset Flex Software
status open
\begin_layout Plain Layout
GCC
\end_layout
\end_inset
extensions, such as
\begin_inset Flex Software
status open
\begin_layout Plain Layout
librchash
\end_layout
\end_inset
.
\end_layout
\begin_layout Itemize
Please use a macro that calls a macro should you require a temporary variable.
In the example below,
\begin_inset Flex CMacro
status open
\begin_layout Plain Layout
Max(A,B)
\end_layout
\end_inset
is the macro that the use calls.
This then calls another
\emph on
implementation
\emph default
macro passing, along with
\begin_inset Flex CVar
status open
\begin_layout Plain Layout
A
\end_layout
\end_inset
and
\begin_inset Flex CVar
status open
\begin_layout Plain Layout
B
\end_layout
\end_inset
, a unique
\begin_inset Flex CMacro
status open
\begin_layout Plain Layout
LABEL
\end_layout
\end_inset
string and the
\begin_inset Flex CMacro
status open
\begin_layout Plain Layout
COUNTER
\end_layout
\end_inset
(usually
\begin_inset Flex CMacro
status open
\begin_layout Plain Layout
__COUNTER__
\end_layout
\end_inset
as provided by the compiler) which is a unique number.
The implementation macro then does the work, constructing unique variable
names from
\begin_inset Flex CMacro
status open
\begin_layout Plain Layout
LABEL
\end_layout
\end_inset
and
\begin_inset Flex CMacro
status open
\begin_layout Plain Layout
COUNTER
\end_layout
\end_inset
using
\begin_inset Flex CMacro
status open
\begin_layout Plain Layout
__typeof__
\end_layout
\end_inset
.\end_layout
\begin_layout Itemize
\begin_inset listings
lstparams "language=C"
inline false
status open
\begin_layout Plain Layout
/*
\end_layout
\begin_layout Plain Layout
* this macro does the work but calculates (A) twice, so might
\end_layout
\begin_layout Plain Layout
* be inefficient if (A) is a function call.
\end_layout
\begin_layout Plain Layout
*/
\end_layout
\begin_layout Plain Layout
#define Max_macro(A,B) ((A)>(B) ? (A) : (B))
\end_layout
\begin_layout Plain Layout
\end_layout
\begin_layout Plain Layout
#ifdef USE_GCC_EXTENSIONS
\end_layout
\begin_layout Plain Layout
/*
\end_layout
\begin_layout Plain Layout
* An implementation statement expression that sets (A)
\end_layout
\begin_layout Plain Layout
* and (B) into temporary variabless so they are calculated
\end_layout
\begin_layout Plain Layout
* only once.
\end_layout
\begin_layout Plain Layout
*/
\end_layout
\begin_layout Plain Layout
#define Max_implementation(A,B,LABEL,COUNTER) \backslash
\end_layout
\begin_layout Plain Layout
__extension__
\backslash
\end_layout
\begin_layout Plain Layout
({
\backslash
\end_layout
\begin_layout Plain Layout
__typeof__(A) Concat3(__a,LABEL,COUNTER) = (A);
\backslash
\end_layout
\begin_layout Plain Layout
__typeof__(B) Concat3(__b,LABEL,COUNTER) = (B);
\backslash
\end_layout
\begin_layout Plain Layout
Max_macro(Concat3(__a,LABEL,COUNTER),
\backslash
\end_layout
\begin_layout Plain Layout
Concat3(__b,LABEL,COUNTER));
\backslash
\end_layout
\begin_layout Plain Layout
})
\end_layout
\begin_layout Plain Layout
/*
\end_layout
\begin_layout Plain Layout
* The macro called by the user, sends the unique string
\begin_inset Quotes eld
\end_inset
Max
\begin_inset Quotes erd
\end_inset
\end_layout
\begin_layout Plain Layout
* and __COUNTER__ to the implementation along with (unevaluated,
\end_layout
\begin_layout Plain Layout
* at this stage) A and B.
\end_layout
\begin_layout Plain Layout
*/
\end_layout
\begin_layout Plain Layout
#define Max(A,B) Max_implementation((A),(B),Max,__COUNTER__)
\end_layout
\begin_layout Plain Layout
\end_layout
\begin_layout Plain Layout
#else
\end_layout
\begin_layout Plain Layout
/*
\end_layout
\begin_layout Plain Layout
* Fallback if GCC extensions are not available.
\end_layout
\begin_layout Plain Layout
*/
\end_layout
\begin_layout Plain Layout
#define Max(A,B) Max_macro((A),(B))
\end_layout
\begin_layout Plain Layout
\end_layout
\begin_layout Plain Layout
#endif // USE_GCC_EXTENSIONS
\end_layout
\begin_layout Plain Layout
\end_layout
\end_inset
\end_layout
\begin_layout Subsection
Control scripts
\end_layout
\begin_layout Standard
\begin_inset CommandInset label
LatexCommand label
name "subsec:Control-scripts"
\end_inset
I have a number of control scripts written in
\begin_inset Flex ScriptingLanguage
status open
\begin_layout Plain Layout
Perl
\end_layout
\end_inset
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 Flex bashscript
status open
\begin_layout Plain Layout
zipup
\end_layout
\end_inset
which makes a file
\begin_inset Flex File
status open
\begin_layout Plain Layout
binary_c.zip
\end_layout
\end_inset
containing this manual and all the source code.
See also
\begin_inset Flex Perlscript
status open
\begin_layout Plain Layout
grid.pl
\end_layout
\end_inset
.
\end_layout
\begin_layout Standard
\begin_inset Newpage pagebreak
\end_inset
\end_layout
\begin_layout SectionAdvanced Configuration
\end_layout
\begin_layout Standard
\begin_inset CommandInset label
LatexCommand label
name "subsec:Advanced-Configuration"
\end_inset
\end_layout
\begin_layout Standard
There are three main C header files which affect how the
\begin_inset Formula $\binaryc$
\end_inset
code is built:
\begin_inset Flex HeaderFile
status open
\begin_layout Plain Layout
binary_c_code_options.h
\end_layout
\end_inset
,
\begin_inset Flex HeaderFile
status open
\begin_layout Plain Layout
binary_c_parameters.h
\end_layout
\end_inset
and
\begin_inset Flex HeaderFile
status open
\begin_layout Plain Layout
nucsyn/nucsyn_parameters.h
\end_layout
\end_inset
.
Some low-level configuration is also performed by the
\begin_inset Flex Software
status open
\begin_layout Plain Layout
Meson
\end_layout
\end_inset
build process.
\end_layout
\begin_layout Subsection
Meson configuation
\end_layout
\begin_layout Standard
When you change something in
\begin_inset Flex HeaderFile
status open
\begin_layout Plain Layout
binary_structures.h
\end_layout
\end_inset
, or one of the other header files, you may have to reconfigure
\begin_inset Flex Software
status open
\begin_layout Plain Layout
Meson
\end_layout
\end_inset
because this in turn reruns
\begin_inset Flex Perlscript
status open
\begin_layout Plain Layout
make_showstruct.pl
\end_layout
\end_inset
which builds code to show the contents of
\begin_inset Flex CStruct
status open
\begin_layout Plain Layout
stardata_t
\end_layout
\end_inset
structures.
\end_layout
\begin_layout Subsection
binary_c-config
\begin_inset CommandInset label
LatexCommand label
name "subsec:binary_c-config"
\end_inset
\end_layout
\begin_layout Standard
Many
\emph on
\begin_inset Flex OS
status open
\begin_layout Plain Layout
\emph on
Unix
\end_layout
\end_inset
-
\emph default
type commands have an associated
\begin_inset Flex Commandstatus open
\begin_layout Plain Layout
*-config
\end_layout
\end_inset
command which gives details of their build flags, version, build date etc.
As of recently, so does
\begin_inset Formula $\binaryc$
\end_inset
, so you can run,
\end_layout
\begin_layout Standard
\begin_inset listings
lstparams "language=bash"
inline false
status open
\begin_layout Plain Layout
binary_c-config help
\end_layout
\end_inset
to see the available flags, which at the time of writing are
\begin_inset listings
inline false
status open
\begin_layout Plain Layout
--cflags Show the flags which were used to build binary_c (same as
--flags)
\end_layout
\begin_layout Plain Layout
--libs Show library linking information
\end_layout
\begin_layout Plain Layout
--libs_list Show library linking information as a space-separated list
without -l
\end_layout
\begin_layout Plain Layout
--help Show this help and exit
\end_layout
\begin_layout Plain Layout
--version Show binary_c's version string.
\end_layout
\begin_layout Plain Layout
--cc Show the C compiler used to build binary_c
\end_layout
\begin_layout Plain Layout
--cc_version Show the version of the C compiler used to build binary_c
\end_layout
\begin_layout Plain Layout
--ld Show the linker used to build binary_c
\end_layout
\begin_layout Plain Layout
--ldd Show binary_c's dependencies
\end_layout
\begin_layout Plain Layout
--incdirs Show binary_c's include dirs (for header files)
\end_layout
\begin_layout Plain Layout
--incdirs_list Show binary_c's include dirs (for header files) as a space-separ
ated list without -I
\end_layout
\begin_layout Plain Layout
--libdirs Show binary_c's library search directories during build
\end_layout
\begin_layout Plain Layout
--libdirs_list Show binary_c's library search directories during build
as a space separated list without -L
\end_layout
\begin_layout Plain Layout
--git_url Show the URL of binary_c's git source (if available)
\end_layout
\begin_layout Plain Layout
--git_branch Show the git branch being used (if available)
\end_layout
\begin_layout Plain Layout
--git_revision Show the revision of binary_c's git source (if available)
\end_layout
\begin_layout Plain Layout
--svn_url Show the URL of binary_c's svn source (if available)
\end_layout
\begin_layout Plain Layout
--svn_revision Show the revision of binary_c's svn source (if available)
\end_layout
\begin_layout Plain Layout
--build_date Show the date and time of binary_c's build
\end_layout
\begin_layout Plain Layout
--define_macros Show macros defined by -D...
in the compiler flags
\end_layout
\begin_layout Plain Layout
--undef_macros Show macros undefined by -U...
in the compiler flags
\end_layout
\end_inset
\end_layout
\begin_layout Standard
note that the double minus sign is optional (it can be one minus, or none).
For example,
\begin_inset listings
inline false
status open
\begin_layout Plain Layout
$ binary_c-config define_macros
\end_layout
\begin_layout Plain Layout
-DALIGNSIZE=16 -DCPUFREQ=3500 -DLINUX -D_LARGEFILE_SOURCE -D_FILE_OFFSET_BITS=64
-DGIT_REVISION=4132:20190711:e754a8a7 -DGIT_URL=gitlab@gitlab.eps.surrey.ac.uk:ri00
05/binary_c.git -DGIT_BRANCH=izzard-discs -D__HAVE_AVX__ -D__HAVE_DRAND48__
-D__HAVE_GSL__ -DUSE_GSL -D__HAVE_LIBBACKTRACE__ -D__HAVE_LIBBFD__ -D__HAVE_LIB
BSD__ -D__HAVE_LIBIBERTY__ -D__HAVE_LIBMEMOIZE__ -D__HAVE_MALLOC_H__ -D__HAVE_PK
G_CONFIG__ -D__HAVE_VALGRIND__ -D__SHOW_STARDATA__
\end_layout
\begin_layout Plain Layout
\end_layout
\begin_layout Plain Layout
$ binary_c-config version
\end_layout
\begin_layout Plain Layout
2.0pre32
\end_layout
\begin_layout Plain Layout
\end_layout
\begin_layout Plain Layout
$ binary_c-config cflags
\end_layout
\begin_layout Plain Layout
-DALIGNSIZE=16 -fPIC -Wall -Wstrict-prototypes -O3 -mtune=native -march=nati
ve -DCPUFREQ=3500 -DLINUX -D_LARGEFILE_SOURCE -D_FILE_OFFSET_BITS=64
-frounding-math -fsignaling-nans -fno-finite-math-only -fno-stack-protector
-ffloat-store -fno-fast-math -DGIT_REVISION=4132:20190711:e754a8a7 -DGIT_URL=g
itlab@gitlab.eps.surrey.ac.uk:ri0005/binary_c.git -DGIT_BRANCH=izzard-discs
-D__HAVE_AVX__ -mavx -D__HAVE_DRAND48__ -D__HAVE_GSL__ -DUSE_GSL -I/home/i
zzard/include -D__HAVE_LIBBACKTRACE__ -D__HAVE_LIBBFD__ -D__HAVE_LIBBSD__
-D__HAVE_LIBIBERTY__ -D__HAVE_LIBMEMOIZE__ -D__HAVE_MALLOC_H__ -D__HAVE_PKG
_CONFIG__ -D__HAVE_VALGRIND__ -D__SHOW_STARDATA__ -mtune=native -ffunctio
n-sections -mtune=native -march=native -fsignaling-nans -fno-finite-math-only
-fsignaling-nans -fno-finite-math-only
\end_layout
\end_inset
\end_layout
\begin_layout Standard
The
\begin_inset Formula $\binarygrid$
\end_inset
\begin_inset Flex ScriptingLanguage
status open
\begin_layout Plain Layout
Perl
\end_layout
\end_inset
module makes extensive use of
\begin_inset Flex bashscript
status open
\begin_layout Plain Layout
binary_c-config
\end_layout
\end_inset
to determine which flags it should use to build its
\begin_inset Flex ProgrammingLanguage
status open
\begin_layout Plain Layout
C
\end_layout
\end_inset
interface to
\begin_inset Formula $\libbinaryc$
\end_inset
.
\end_layout
\begin_layout Standard
Note that the
\begin_inset Flex Command
status open
\begin_layout Plain Layout
binary_c-config
\end_layout
\end_inset
tool is actually a
\begin_inset Flex ScriptingLanguage
status open
\begin_layout Plain Layout
bash
\end_layout
\end_inset
script that requires
\begin_inset Formula $\binaryc$\end_inset
to be built, and working tools such as
\begin_inset Flex Command
status open
\begin_layout Plain Layout
\emph off
grep
\end_layout
\end_inset
,
\begin_inset Flex Command
status open
\begin_layout Plain Layout
\emph off
tr
\end_layout
\end_inset
,
\begin_inset Flex Command
status open
\begin_layout Plain Layout
\emph off
sed
\end_layout
\end_inset
and
\begin_inset Flex Command
status open
\begin_layout Plain Layout
\emph off
ldd
\end_layout
\end_inset
.
These are standard tools on most
\begin_inset Flex OS
status open
\begin_layout Plain Layout
Unix
\end_layout
\end_inset
systems.
\end_layout
\begin_layout Subsection
Makefile -D\SpecialChar ldots
\end_layout
\begin_layout StandardSome options are set up by
\begin_inset Flex Software
status open
\begin_layout Plain Layout
Meson
\end_layout
\end_inset
\emph on
\emph default
and passed
\emph on
\emph default
as
\begin_inset Flex Args
status open
\begin_layout Plain Layout
-D\SpecialChar ldots
\end_layout
\end_inset
arguments to the compiler:
\end_layout
\begin_layout Itemize
\family typewriter
LINUX
\family default
is defined if you're running
\begin_inset Flex OS
status open
\begin_layout Plain Layout
Linux
\end_layout
\end_inset
.
This is useful for some timers and segfault catchers which only work with
the
\begin_inset Flex OS
status open
\begin_layout Plain Layout
Linux
\end_layout
\end_inset
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
\begin_inset Flex File
status open
\begin_layout Plain Layout
/proc/cpuinfo
\end_layout
\end_inset
if available,
\begin_inset Flex Command
status open
\begin_layout Plain Layout
sysctl -a
\end_layout
\end_inset
on MacOSX.)
\end_layout
\begin_layout Itemize
\family typewriter
GIT_REVISION
\family default
and
\family typewriter
GIT_URL
\family default
provide
\emph on
\begin_inset Formula $\binaryc$
\end_inset
\emph default
with information about the version of the code you are using.
This can prove essential when debugging.
See section
\begin_inset space ~
\end_inset
\begin_inset CommandInset ref
LatexCommand ref
reference "subsec:git-revision"
\end_inset
for more details.
\end_layout
\begin_layout Subsectionbinary_c_code_options.h
\end_layout
\begin_layout Standard
\begin_inset CommandInset label
LatexCommand label
name "subsec:binary_c_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.
Note: this has not been tested for a long time.
\end_layout
\begin_layout Itemize
\family typewriter
DUMA
\family default
should be set if you wish to use the DUMA memory checking library.
Note: this has not been tested for a long time.
\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 NUMBER_OF_INTERPOLATION_TABLES.
\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 typewriterSAVE_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.
\series bold
Note: this option is deprecated.
\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.
\begin_inset Flex CMacro
status open
\begin_layout Plain Layout
STATIC_ARRAYS
\end_layout
\end_inset
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
\begin_inset Flex Args
status open
\begin_layout Plain Layout
--repeat <n>
\end_layout
\end_inset
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 typewriterrandom_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
binary_c_parameters.h
\end_layout
\begin_layout Standard
\begin_inset CommandInset label
LatexCommand label
name "subsec:binary_c_parameters.h"
\end_inset
The options in this file are non-nucleosynthesis, (single or) binary stellar
evolution options.
This file also automatically includes many other header files, e.g.
\begin_inset space ~
\end_inset
\begin_inset Flex HeaderFile
status open
\begin_layout Plain Layout
binary_c_code_options.h
\end_layout
\end_inset
and
\begin_inset Flex HeaderFile
status open
\begin_layout Plain Layout
nucsyn_parameters.h
\end_layout
\end_inset
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 Standard
You can activate the
\begin_inset Formula $\MINT$
\end_inset
library from in here by uncommenting,\begin_inset listings
lstparams "language=C"
inline false
status open
\begin_layout Plain Layout
//#define MINT
\end_layout
\end_inset
\end_layout
\begin_layout Subsection
nucsyn/nucsyn_parameters.h
\end_layout
\begin_layout Standard
\begin_inset CommandInset label
LatexCommand label
name "subsec: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
\begin_inset Flex HeaderFile
status open
\begin_layout Plain Layout
nucsyn/nucsyn_parameters.h
\end_layout
\end_inset
.
More detailed descriptions of the variables used in the code are given
in section
\begin_inset CommandInset ref
LatexCommand ref
reference "sec:Code-description"
\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.
\begin_inset Separator latexpar
\end_inset
\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.
\begin_inset Separator latexpar
\end_inset
\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 typewriterNUCSYN_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"
literal "true"
\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.
\begin_inset Separator latexpar
\end_inset
\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
\begin_inset Newline newline
\end_inset
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.
\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 citationLatexCommand citealp
key "1998ApJ...497..388G"
literal "true"
\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
.
\begin_inset Separator latexpar
\end_inset
\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"
literal "true"
\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 typewriternucsyn.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
\begin_inset Flex Args
status open
\begin_layout Plain Layout
--no_thermohaline_mixing 1
\end_layout
\end_inset
\family typewriter
\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
\family typewriter
NUCSYN_MU_FUZZ
\family default
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.
\end_layout
\begin_layout Standard
There are further options in the file
\begin_inset Flex File
status open
\begin_layout Plain Layout
binary_c_parameters.h
\end_layout
\end_inset
(details below) although it's unlikely you'll want to change any of them.
\end_layout
\begin_layout Subsection
Colours in
\begin_inset Formula $\binaryc$
\end_inset
output
\end_layout
\begin_layout Standard
\begin_inset CommandInset label
LatexCommand label
name "subsec:Colours-in-binaryc"
\end_inset
The output from
\begin_inset Formula $\binaryc$
\end_inset
, especially the standard log file and debugging output, by default makes
use of
\begin_inset Flex Software
status open
\begin_layout Plain Layout
ANSI
\end_layout
\end_inset
terminal colours. From version 2.2 you can change these colours to whatever you wish which
is especially handy if you are colourblind.
You can list the colours available with,
\begin_inset listings
lstparams "language=bash"
inline false
status open
\begin_layout Plain Layout
./binary_c version | grep ANSI
\end_layout
\end_inset
which shows something like,
\begin_inset listings
lstparams "language=bash"
inline false
status open
\begin_layout Plain Layout
ANSI colour 0 BLACK : Default is [0;30m, we are using [0;30m.
\end_layout
\begin_layout Plain Layout
ANSI colour 1 RED : Default is [0;31m, we are using [0;31m.
\end_layout
\begin_layout Plain Layout
ANSI colour 2 GREEN : Default is [0;32m, we are using [0;32m.
\end_layout
\begin_layout Plain Layout
...
\end_layout
\end_inset
The colours are referred to internally by macros
\begin_inset Flex CMacro
status open
\begin_layout Plain Layout
BLACK
\end_layout
\end_inset
,
\begin_inset Flex CMacro
status open
\begin_layout Plain Layout
RED
\end_layout
\end_inset
, etc.
\begin_inset space ~
\end_inset
and the colour strings are stored in
\begin_inset Flex CVar
status open
\begin_layout Plain Layout
stardata->store->colours[n]
\end_layout
\end_inset
where
\begin_inset Flex CVar
status open
\begin_layout Plain Layout
n
\end_layout
\end_inset
is replaced by one of the macros of the number they represent (
\begin_inset Flex CMacro
status open
\begin_layout Plain Layout
BLACK
\end_layout
\end_inset
is
\begin_inset Flex CVar
status open
\begin_layout Plain Layout
0
\end_layout
\end_inset
,
\begin_inset Flex CMacro
status open
\begin_layout Plain Layout
RED
\end_layout
\end_inset
is
\begin_inset Flex CVar
status open
\begin_layout Plain Layout
1
\end_layout
\end_inset
etc.).
\end_layout
\begin_layout Standard
You can change these on the command line, e.g.,
\begin_inset listings
lstparams "language=bash"
inline false
status open
\begin_layout Plain Layout
./binary_c colour2 12\end_layout
\end_inset
where
\begin_inset Flex Args
status open
\begin_layout Plain Layout
colour2
\end_layout
\end_inset
means
\begin_inset Flex CMacro
status open
\begin_layout Plain Layout
GREEN
\end_layout
\end_inset
(see above) and
\begin_inset Flex Args
status open
\begin_layout Plain Layout
12
\end_layout
\end_inset
is the colour's new
\begin_inset Flex Software
status open
\begin_layout Plain Layout
ANSI
\end_layout
\end_inset
8-bit code (in the range 0 to 255).
The
\begin_inset Flex Software
status open
\begin_layout Plain Layout
ANSI
\end_layout
\end_inset
colours are defined at
\begin_inset Flex URL
status open
\begin_layout Plain Layout
https://en.wikipedia.org/wiki/ANSI_escape_code#8-bit
\end_layout
\end_inset
.
\end_layout
\begin_layout StandardIf a colourblind user would like to set up a palette that works for them,
I would be very happy to program this in for you.
\end_layout
\begin_layout Standard
\begin_inset Newpage pagebreak
\end_inset
\end_layout
\begin_layout Section
\emph on
\begin_inset Formula $\binaryc$
\end_inset
\emph default
software development cycle
\end_layout
\begin_layout Standard
\begin_inset CommandInset include
LatexCommand input
filename "binary_c-software.lyx"
\end_inset
\end_layout
\begin_layout Standard
\begin_inset Newpage pagebreak
\end_inset
\end_layout
\begin_layout Section
Cookbook
\end_layout
\begin_layout Standard
This section provides ideas for common obvious problems.
\end_layout
\begin_layout Subsection
How to log output
\end_layout
\begin_layout Standard
Put your logging statement into
\begin_inset Flex File
status open
\begin_layout Plain Layout
log_every_timestep.c
\end_layout
\end_inset
using the
\begin_inset Flex CMacro
status open
\begin_layout Plain Layout
Printf
\end_layout
\end_inset
macro, e.g.,
\begin_inset listings
lstparams "language=C"
inline false
status open
\begin_layout Plain Layout
Printf();
\end_layout
\end_inset
\end_layout
\begin_layout Subsection
How to find which source files contain a string
\end_layout
\begin_layout Standard
Run
\end_layout
\begin_layout Standard
\begin_inset listings
lstparams "language=bash"
inline false
status open
\begin_layout Plain Layout
./rgrep <string> {opts}
\end_layout
\end_inset
The options (
\begin_inset Flex Args
status open
\begin_layout Plain Layout
{opts}
\end_layout
\end_inset
) are passed to
\begin_inset Flex Command
status open
\begin_layout Plain Layout
grep -r
\end_layout
\end_inset
, see
\begin_inset Flex Command
status open
\begin_layout Plain Layout
man grep
\end_layout
\end_inset
for details, and these are not required. Binary (object, executable, shared library) files are automatically skipped.
Most often you will want to ignore case, e.g.,
\end_layout
\begin_layout Standard
\family typewriter
\series bold
\begin_inset listings
lstparams "language=bash"
inline false
status open
\begin_layout Plain Layout
./rgrep <string> -i
\end_layout
\end_inset
\end_layout
\begin_layout Subsection
How to build with debugging output
\end_layout
\begin_layout Standard
\emph on
\begin_inset Formula $\Binaryc$
\end_inset
\emph default
provides the
\family typewriter
\begin_inset listings
lstparams "language=C"
inline false
status open
\begin_layout Plain Layout
Dprint(...)
\end_layout
\end_inset
\family default
macro to allow you to output what is going on to the screen (
\family typewriter
stdout
\family default
).
To turn this on, change the line in
\emph on
binary_c_code_options.h
\emph default
to
\end_layout
\begin_layout Standard
\begin_inset listings
lstparams "language=C"
inline false
status open
\begin_layout Plain Layout
#define DEBUG 1
\end_layout
\end_inset
Then rebuild with debugging enabled,
\begin_inset listings
lstparams "language=bash"
inline false
status open
\begin_layout Plain Layout
cd builddir
\end_layout
\begin_layout Plain Layout
meson --reconfigure --buildtype=debug
\end_layout
\begin_layout Plain Layout
ninja
\end_layout
\end_inset
You can provide an expression which must return true for debugging to be
output.
This is
\begin_inset Flex CMacro
status open
\begin_layout Plain Layout
DEBUG_EXP
\end_layout
\end_inset
in
\begin_inset Flex HeaderFile
status open
\begin_layout Plain Layout
binary_c_debug.h
\end_layout
\end_inset
.
E.g.
\begin_inset space ~
\end_inset
to only have output after 10Myr, use:
\end_layout
\begin_layout Standard
\family typewriter
\series bold
\begin_inset listings
lstparams "language=C"
inline false
status open
\begin_layout Plain Layout
#define DEBUG_EXP (stardata->model.time > 10.0)
\end_layout
\end_inset
\family default
\series default
Again, you will need to do a complete rebuild to make this work.
You can use
\family typewriter
\family default
\begin_inset Flex CMacro
status open
\begin_layout Plain Layout
Dprint_no_newline()
\end_layout
\end_inset
\family typewriter
\family default
macro to prevent the newline after a debugging statement.
\end_layout
\begin_layout Subsection
How to check for NaNs (not a numbers)
\end_layout
\begin_layout Standard
If
\begin_inset Flex CMacro
status open
\begin_layout Plain Layout
NANCHECKS
\end_layout
\end_inset
is enabled in
\family typewriter
\family default
\begin_inset Flex HeaderFile
status open
\begin_layout Plain Layout
binary_c_code_options.h
\end_layout
\end_inset
you can use the
\begin_inset Flex CMacro
status open
\begin_layout Plain Layout
NANCHECK(A)
\end_layout
\end_inset
macro, which checks whether
\begin_inset Flex CMacro
status open
\begin_layout Plain Layout
A
\end_layout
\end_inset
is not a number, exiting with an error if this is the case.
This is rather compiler dependent but should work fine with
\begin_inset Flex Software
status open
\begin_layout Plain Layout
gcc
\end_layout
\end_inset
.
\end_layout
\begin_layout Subsection
How to exit
\emph on
\begin_inset Formula $\binaryc$
\end_inset
\end_layout
\begin_layout Standard
Do
\emph on
not
\emph default
use
\begin_inset Flex ProgrammingLanguage
status open
\begin_layout Plain Layout
C
\end_layout
\end_inset
's
\begin_inset Flex CFunction
status open
\begin_layout Plain Layout
exit
\end_layout
\end_inset
function.
Instead use the
\begin_inset Flex CMacro
status open
\begin_layout Plain Layout
Exit_binary_c(\SpecialChar ldots
)
\end_layout
\end_inset
macro, with an error code from
\begin_inset Flex HeaderFile
status open
\begin_layout Plain Layout
binary_c_error_codes.h
\end_layout
\end_inset
, e.g.
\end_layout
\begin_layout Standard
\family typewriter
\begin_inset listings
lstparams "language=C"
inline false
status open
\begin_layout Plain Layout
Exit_binary_c(PIPE_FAILURE,
\begin_inset Quotes eld
\end_inset
My pipe failed! ARGH!
\begin_inset Quotes erd
\end_inset
);
\end_layout
\end_inset
\end_layout
\begin_layout Subsection
How to debug segfaults
\end_layout
\begin_layout Standard
Install
\begin_inset Flex Software
status open
\begin_layout Plain Layout
gdb
\end_layout
\end_inset
.
Build
\begin_inset Formula $\binaryc$
\end_inset
with debugging:
\begin_inset Newline newline
\end_inset
\family typewriter
\series bold
\begin_inset listings
lstparams "language=bash"inline false
status open
\begin_layout Plain Layout
cd builddir
\end_layout
\begin_layout Plain Layout
meson --reconfigure --buildtype=debug
\end_layout
\begin_layout Plain Layout
ninja
\end_layout
\begin_layout Plain Layout
cd ..
\end_layout
\end_inset
\end_layout
\begin_layout Standard
Then run your test star with
\begin_inset Newline newline
\end_inset
\family typewriter
\series bold
\begin_inset listings
lstparams "language=bash"
inline false
status open
\begin_layout Plain Layout
tbse debug
\end_layout
\end_inset
\end_layout
\begin_layout Standard
which will run
\begin_inset Flex Software
status open
\begin_layout Plain Layout
gdb
\end_layout
\end_inset
for you with the appropriate arguments to run the star.
To find out where the bug is, use
\begin_inset Quotes eld
\end_inset
\begin_inset Flex Argsstatus open
\begin_layout Plain Layout
bt
\end_layout
\end_inset
\begin_inset Quotes erd
\end_inset
(backtrace) in
\begin_inset Flex Software
status open
\begin_layout Plain Layout
gdb
\end_layout
\end_inset
.
\end_layout
\begin_layout Standard
See also
\begin_inset Flex URL
status open
\begin_layout Plain Layout
https://en.wikipedia.org/wiki/GNU_Debugger
\end_layout
\end_inset
\end_layout
\begin_layout Standard
You may find that
\begin_inset Flex Software
status open
\begin_layout Plain Layout
valgrind
\end_layout
\end_inset
provides more information, especially when your segfault is caused by a
memory leak.
\end_layout
\begin_layout Subsection
How to debug memory leaks
\end_layout
\begin_layout Standard
Build with debugging:
\begin_inset Newline newline
\end_inset
\family typewriter
\series bold
\begin_inset listings
lstparams "language=bash"inline false
status open
\begin_layout Plain Layout
cd builddir
\end_layout
\begin_layout Plain Layout
meson --reconfigure --buildtype=debug -Dvalgrind=true
\end_layout
\begin_layout Plain Layout
ninja
\end_layout
\begin_layout Plain Layout
cd ..
\end_layout
\end_inset
\family default
\series default
Then run
\begin_inset Newline newline
\end_inset
\family typewriter
\series bold
\begin_inset listings
lstparams "language=bash"
inline false
status open
\begin_layout Plain Layout
tbse valgrind
\end_layout
\end_inset
\family default
\series default
Find out how to use
\emph on
\begin_inset Flex Software
status open
\begin_layout Plain Layout
\emph on
valgrind
\end_layout
\end_inset
\emph default
at
\begin_inset Flex URL
status open
\begin_layout Plain Layout
http://valgrind.org/
\end_layout
\end_inset
\begin_inset Newline newline
\end_inset
You can also run
\begin_inset listings
lstparams "language=bash"
inline false
status open
\begin_layout Plain Layout
tbse callgrind
\end_layout
\end_inset
\begin_inset listings
lstparams "language=bash"
inline false
status open
\begin_layout Plain Layout
tbse cachegrind
\end_layout
\end_inset
\begin_inset listings
lstparams "language=bash"
inline false
status open
\begin_layout Plain Layout
tbse ptrcheck
\end_layout
\end_inset
\begin_inset listings
lstparams "language=bash"
inline false
status open
\begin_layout Plain Layout
tbse sgcheck
\end_layout
\end_inset
\end_layout
\begin_layout Subsection
How to show the arguments that
\emph ontbse
\emph default
would use, but do not evolve a star
\end_layout
\begin_layout Standard
Run
\begin_inset Newline newline
\end_inset
\family typewriter
\series bold
\begin_inset listings
lstparams "language=bash"
inline false
status open
\begin_layout Plain Layout
tbse echo
\end_layout
\end_inset
\end_layout
\begin_layout Subsection
How to run a star which has the arguments in a file
\end_layout
\begin_layout Standard
This is handy when you have a fail case (e.g.
from a population synthesis run).
Just run
\begin_inset Newline newline
\end_inset
\family typewriter
\series bold
\begin_inset listings
lstparams "language=bash"
inline false
status open
\begin_layout Plain Layout
tbse <filename>
\end_layout
\end_inset
\end_layout
\begin_layout Subsection
How to use profile-guided optimization (PGO)
\end_layout
\begin_layout Standard
\begin_inset CommandInset label
LatexCommand label
name "subsec:How-to-use-PGO"
\end_inset
\begin_inset Flex Software
status open
\begin_layout Plain Layout
Meson
\end_layout
\end_inset
supports profile-guided optimization (PGO), and this has been written into
the
\begin_inset Flex File
status open
\begin_layout Plain Layout
meson/pgo.sh
\end_layout
\end_inset
script which you can use to test it.
You should just run this, with an optional argument that is the number
of test systems (this defaults to 1000), e.g.
\begin_inset space ~
\end_inset
from the
\begin_inset Formula $\binaryc$
\end_inset
root directory:
\begin_inset listings
inline false
status open
\begin_layout Plain Layout
./meson/pgo.sh 1000
\end_layout
\end_inset
\end_layout
\begin_layout Standard
For details about profile-guided optimization, please see
\begin_inset Flex URL
status open
\begin_layout Plain Layout
https://en.wikipedia.org/wiki/Profile-guided_optimization
\end_layout
\end_inset
or your compiler's documentation.
\end_layout
\begin_layout Subsection
How to get help
\end_layout
\begin_layout Subsubsection
How to know what a parameter does
\end_layout
\begin_layout StandardRun
\begin_inset Newline newline
\end_inset
\family typewriter
\series bold
\begin_inset listings
lstparams "language=bash"
inline false
status open
\begin_layout Plain Layout
binary_c help <parameter_name>
\end_layout
\end_inset
\end_layout
\begin_layout Standard
or
\begin_inset Newline newline
\end_inset
\family typewriter
\series bold
\begin_inset listings
lstparams "language=bash"
inline false
status open
\begin_layout Plain Layout
binary_c help_all
\end_layout
\end_inset
\end_layout
\begin_layout Standard
You can even just give
\emph on
\begin_inset Formula $\binaryc$
\end_inset
\emph default
part of a parameter name and it will try to find the best match.
\end_layout
\begin_layout Subsubsection
The mailing lists
\end_layout
\begin_layout Standard
There is a development mailing list for
\begin_inset Formula $\binaryc$
\end_inset
, for details see section
\begin_inset space ~\end_inset
\begin_inset CommandInset ref
LatexCommand ref
reference "subsec:mailing-lists"
\end_inset
.
\end_layout
\begin_layout Subsection
How to add a parameter to
\begin_inset Formula $\binaryc$
\end_inset
\end_layout
\begin_layout Standard
Look at
\begin_inset Flex HeaderFile
status open
\begin_layout Plain Layout
src/setup/cmd_line_args_list.h
\end_layout
\end_inset
.
Please read the comments in that file for instructions.
It's best to copy-paste a parameter that does something similar, then edit
that.
If your parameter depends on build flags, you will want to define it as
a macro (see
\begin_inset Flex HeaderFile
status open
\begin_layout Plain Layout
src/setup/cmd_line_macros.h
\end_layout
\end_inset
).
\end_layout
\begin_layout Standard
The storage space for the new parameter usually goes in the
\begin_inset Flex CStruct
status open
\begin_layout Plain Layout
preferences_t
\end_layout
\end_inset
structure (see
\begin_inset Flex HeaderFile
status open
\begin_layout Plain Layout
binary_c_structures.h
\end_layout
\end_inset
).
\end_layout
\begin_layout Subsection
How to build on a Mac
\end_layout
\begin_layout Standard
I hear it is possible! Please ask the mailing list.
\end_layout
\begin_layout Subsection
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
status open
\begin_layout Plain Layout
./make libbinary_c.so
\end_layout
\end_inset
\family default
\series default
The API uses this shared library.
\end_layout
\begin_layout Subsection
How to calculate stellar yields or population statistics
\end_layout
\begin_layout Enumerate
You have to build
\emph on
\begin_inset Formula $\binaryc$
\end_inset
\emph default
with
\begin_inset Flex CMacro
status open
\begin_layout Plain Layout
NUCSYN
\end_layout
\end_inset
and
\begin_inset Flex CMacro
status open
\begin_layout Plain Layout
NUCSYN_GCE
\end_layout
\end_inset
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
status open
\begin_layout Plain Layout
binary_grid
\end_layout
\end_inset
\begin_inset Flex ScriptingLanguage
status open
\begin_layout Plain Layout
Perl
\end_layout
\end_inset
module (which must build
\begin_inset Flex Perlmodule
status open
\begin_layout Plain Layout
binary_grid2
\end_layout
\end_inset
correctly).
\end_layout
\begin_layout Enumerate
Edit the
\begin_inset Flex Perlscript
status open
\begin_layout Plain Layout
src/perl/yield_vs_time.pl
\end_layout
\end_inset
script to set paths and the output directory, and the various parameters.
\end_layout
\begin_layout Enumerate
Now run the
\begin_inset Flex Perlscript
status open
\begin_layout Plain Layout
src/perl/yield_vs_time.pl
\end_layout
\end_inset
script.
Likely you will have to edit this script to make sure the output directory
is correct, and read its comments to make sure you set the timestep, choose
between single/binary/mixed populations, etc.
Run it with e.g.
\family typewriter
\series bold
\begin_inset listings
lstparams "language=bash"
inline false
status open
\begin_layout Plain Layout
./src/perl/scripts2/yield_vs_time.pl dt=10 max_evolution_time=13700 vb=1
\end_layout
\end_inset
\family default
\series default
Note that, depending on the options you choose in
\begin_inset Flex Perlscript
status open
\begin_layout Plain Layout
yield_vs_time.pl
\end_layout
\end_inset
, this may take a long time!
\end_layout
\begin_layout Subsection
\emph on
bash
\emph default
autocompletion of
\begin_inset Formula $\binaryc$
\end_inset
arguments
\end_layout
\begin_layout Standard
You can make
\begin_inset Flex Software
status open
\begin_layout Plain Layout
bash\end_layout
\end_inset
autocomplete arguments to
\begin_inset Formula $\binaryc$
\end_inset
by putting the following in your
\begin_inset Flex File
status open
\begin_layout Plain Layout
.bashrc
\end_layout
\end_inset
file (assuming you have
\emph on
\begin_inset Formula $\binaryc$
\end_inset
\emph default
in the directory specified by the environment variable
\begin_inset Flex Envvar
status open
\begin_layout Plain Layout
BINARY_C
\end_layout
\end_inset
) and restart
\emph on
bash
\emph default
.
\begin_inset listings
lstparams "language=Perl,numbers=left"
inline false
status open
\begin_layout Plain Layout
# completion of binary_c arguments
\end_layout
\begin_layout Plain Layout
_binary_c()
\end_layout
\begin_layout Plain Layout
{
\end_layout
\begin_layout Plain Layout
COMPREPLY=()
\end_layout
\begin_layout Plain Layout
cmd="${COMP_WORDS[0]}"
\end_layout
\begin_layout Plain Layout
cur="${COMP_WORDS[COMP_CWORD]}"
\end_layout
\begin_layout Plain Layout
prev="${COMP_WORDS[COMP_CWORD-1]}"
\end_layout
\begin_layout Plain Layout
binaryc_opts=$($BINARY_C_ROOT/binary_c help |/bin/grep -A2 "where the
arguments are a selection of :"|tail -1|tr " " "
\backslash
n")
\end_layout
\begin_layout Plain Layout
# check if we match a binary_c argument
\end_layout
\begin_layout Plain Layout
subcmd=( $(compgen -W "$binaryc_opts" "$prev") )
\end_layout
\begin_layout Plain Layout
if [[ $subcmd ]] ; then
\end_layout
\begin_layout Plain Layout
# we do match an argument : try to get sub options
\end_layout
\begin_layout Plain Layout
subopts=$($BINARY_C_ROOT/binary_c argopts $subcmd)
\end_layout
\begin_layout Plain Layout
COMPREPLY=( $(compgen -W "$subopts" -- ${cur}) )
\end_layout
\begin_layout Plain Layout
else
\end_layout
\begin_layout Plain Layout
# we don't, so list the arguments
\end_layout
\begin_layout Plain Layout
COMPREPLY=( $(compgen -W "$binaryc_opts" -- ${cur}) )
\end_layout
\begin_layout Plain Layout
fi
\end_layout
\begin_layout Plain Layout
return 0
\end_layout
\begin_layout Plain Layout
}
\end_layout
\begin_layout Plain Layout
complete -F _binary_c binary_c
\end_layout
\begin_layout Plain Layout
complete -F _binary_c tbse
\end_layout
\begin_layout Plain Layout
\end_layout
\end_inset
\end_layout
\begin_layout Subsection
\begin_inset CommandInset label
LatexCommand label
name "subsec:git-revision"
\end_inset
How to find the
\emph on
git
\emph default
revision and
\emph on
git
\emph default
URL
\end_layout
\begin_layout Standard
Put the following into your
\begin_inset Flex bashscript
status open
\begin_layout Plain Layout
.bashrc
\end_layout
\end_inset
file, restart
\emph on
bash
\emph default
and use the command
\begin_inset Flex Command
status open
\begin_layout Plain Layout
git_rev
\end_layout
\end_inset
to find a suitable
\begin_inset Flex Software
status open
\begin_layout Plain Layout
git
\end_layout
\end_inset
revision string and
\begin_inset Flex Command
status open
\begin_layout Plain Layout
git_url
\end_layout
\end_inset
to find the repository URL.
\begin_inset listings
inline false
status open
\begin_layout Plain Layout
# git function for review number
\end_layout
\begin_layout Plain Layout
git_rev ()
\end_layout
\begin_layout Plain Layout
{
\end_layout
\begin_layout Plain Layout
d=`date +%Y%m%d`
\end_layout
\begin_layout Plain Layout
c=`git rev-list --full-history --all --abbrev-commit | wc -l | sed -e
's/^ *//'`
\end_layout
\begin_layout Plain Layout
h=`git rev-list --full-history --all --abbrev-commit | head -1`
\end_layout
\begin_layout Plain Layout
echo ${c}:${d}:${h}
\end_layout
\begin_layout Plain Layout
}
\end_layout
\begin_layout Plain Layout
\end_layout
\begin_layout Plain Layout
# git function to find the repository url
\end_layout
\begin_layout Plain Layout
git_url ()
\end_layout
\begin_layout Plain Layout
{
\end_layout
\begin_layout Plain Layout
git config --get remote.origin.url
\end_layout
\begin_layout Plain Layout
}
\end_layout
\begin_layout Plain Layout
\end_layout
\end_inset
\end_layout
\begin_layout Subsection
Ninja autocompletion
\end_layout
\begin_layout Standard
\begin_inset CommandInset label
LatexCommand label
name "subsec:Ninja-autocompletion"
\end_inset
Copy the file
\begin_inset Flex File
status open
\begin_layout Plain Layout
meson/bash_ninja_autocomplete.sh
\end_layout
\end_inset
(in the
\begin_inset Formula $\binaryc$
\end_inset
root directory) to wherever you keep your
\begin_inset Flex Software
status open
\begin_layout Plain Layout
bash
\end_layout
\end_inset
autocompletion scripts.
Make it executable with
\begin_inset listings
inline false
status open
\begin_layout Plain Layout
chmod +x bash_ninja_autocomplete.sh
\end_layout
\end_inset
and add the following to your
\begin_inset Flex File
status open
\begin_layout Plain Layout
.bashrc
\end_layout
\end_inset
file:
\begin_inset listings
inline false
status open
\begin_layout Plain Layout
# autocomplete for ninja source
\end_layout
\begin_layout Plain Layout
<path to file>/bash_ninja_autocomplete.sh
\end_layout
\end_inset
\end_layout
\begin_layout Standard
The autocompletion script is based on an original from
\begin_inset Flex URL
status open
\begin_layout Plain Layout
https://github.com/ninja-build/ninja/blob/master/misc/bash-completion
\end_layout
\end_inset
, distributed under an Apache 2.0 licence.
\end_layout
\begin_layout Subsection
Meson autocompletion
\end_layout
\begin_layout Standard
\begin_inset CommandInset label
LatexCommand label
name "subsec:Meson-autocompletion"
\end_inset
You can find a script for \begin_inset Flex Software
status open
\begin_layout Plain Layout
meson
\end_layout
\end_inset
autocompletion at
\begin_inset Flex File
status open
\begin_layout Plain Layout
meson/bash_meson_autocomplete.sh
\end_layout
\end_inset
(which was downloaded from
\begin_inset Flex URL
status collapsed
\begin_layout Plain Layout
https://raw.githubusercontent.com/mesonbuild/meson/master/data/shell-completions/b
ash/meson
\end_layout
\end_inset
).
Do similarly to the
\begin_inset Flex Software
status open
\begin_layout Plain Layout
ninja
\end_layout
\end_inset
autocompletion script describe in section
\begin_inset space ~
\end_inset
\begin_inset CommandInset ref
LatexCommand ref
reference "subsec:Ninja-autocompletion"
plural "false"
caps "false"
noprefix "false"
\end_inset
.
\end_layout
\begin_layout Standard
If you get errors like
\begin_inset listings
inline true
status open
\begin_layout Plain Layout
_filedir: command not found
\end_layout
\end_inset
put the following into your
\begin_inset Flex File
status open
\begin_layout Plain Layout
.bashrc
\end_layout
\end_inset
before sourcing the above file,
\end_layout
\begin_layout Standard
\begin_inset listings
inline false
status open
\begin_layout Plain Layout
if [ -n "$BASH_VERSION" ]; then
\end_layout
\begin_layout Plain Layout
[ -f /etc/bash_completion ] && .
/etc/bash_completion
\end_layout
\begin_layout Plain Layout
fi
\end_layout
\end_inset
which assumes your
\begin_inset Flex Software
status open
\begin_layout Plain Layout
bash_completion
\end_layout
\end_inset
directory is
\begin_inset Flex File
status open
\begin_layout Plain Layout
/etc/bash_completion
\end_layout
\end_inset
(this is where it is on Ubuntu 18.04) and that you have installed the relevant
\begin_inset Flex Software
status open
\begin_layout Plain Layout
bash_completion
\end_layout
\end_inset
package.\end_layout
\begin_layout Subsection
Clang static analyzer (scan-build)
\end_layout
\begin_layout Standard
\begin_inset CommandInset label
LatexCommand label
name "subsec:Clang-static-analyzer"
\end_inset
You can use
\begin_inset Flex Software
status open
\begin_layout Plain Layout
Clang
\end_layout
\end_inset
's static analyzer, the command
\begin_inset Flex Command
status open
\begin_layout Plain Layout
scan-build
\end_layout
\end_inset
, by doing the following
\begin_inset listings
inline false
status open
\begin_layout Plain Layout
rm -r builddir # may not be necessary
\end_layout
\begin_layout Plain Layout
mkdir scan_build_results_ninja scan_build_results_meson
\end_layout
\begin_layout Plain Layout
scan-build -o scan_build_results_meson -v meson builddir -Dusepch=false
2>&1 > scan.meson
\end_layout
\begin_layout Plain Layout
cd builddir
\end_layout
\begin_layout Plain Layout
scan-build -o ../scan_build_results_ninja ninja -v 2>&1 > ../scan.ninja
\end_layout
\end_inset
this leaves the
\begin_inset Flex Software
status open
\begin_layout Plain Layout
meson
\end_layout
\end_inset
and
\begin_inset Flex Software
status open
\begin_layout Plain Layout
ninja
\end_layout
\end_inset
output in the files
\begin_inset Flex File
status open
\begin_layout Plain Layout
scan.meson
\end_layout
\end_inset
and
\begin_inset Flex File
status open
\begin_layout Plain Layout
scan.ninja
\end_layout
\end_inset
, and the results in the directories
\begin_inset Flex File
status open
\begin_layout Plain Layout
scan_build_results_ninja
\end_layout
\end_inset
and
\begin_inset Flex File
status open
\begin_layout Plain Layout
scan_build_results_meson
\end_layout
\end_inset
.
Note that the
\begin_inset Flex Args
status open
\begin_layout Plain Layout
-Dusepch=false
\end_layout
\end_inset
flag is required to disable pre-compiled headers because the static analyzer
does not understand the concept.
Please use the \begin_inset Flex Args
status open
\begin_layout Plain Layout
-o
\end_layout
\end_inset
option to redirect output to a more suitable location (or see
\begin_inset Flex URL
status open
\begin_layout Plain Layout
https://clang-analyzer.llvm.org/scan-build.html#scanbuild_output
\end_layout
\end_inset
).
\end_layout
\begin_layout Subsection
Memory leak or memory bloat?
\end_layout
\begin_layout Standard
\begin_inset CommandInset label
LatexCommand label
name "subsec:Memory-leak-or-memory-bloat"
\end_inset
All software is liable to memory leaks, that is when memory is allocated
but not freed.
When running a grid of stars using
\begin_inset Formula $\binarygrid$
\end_inset
this is particularly problematic: if
\begin_inset Formula $\binaryc$
\end_inset
leaks
\begin_inset Formula $1\mathrm{MB}$
\end_inset
per star – not much in the modern world! – and you are running
\begin_inset Formula $10^{6}$
\end_inset
stars this is
\begin_inset Formula $10^{9}\mathrm{B}\sim1\,\mathrm{GB}$
\end_inset
of memory, which may slow your system or even cause it to crash if you
are running many threads (each of which suddenly wants the memory).
\end_layout
\begin_layout Standard
However, not all memory
\begin_inset Quotes eld
\end_inset
leaks
\begin_inset Quotes erd
\end_inset
are as they seem, they may just be \begin_inset Quotes eld
\end_inset
bloat
\begin_inset Quotes erd
\end_inset
.
The way
\begin_inset Formula $\binarygrid$
\end_inset
works is to run a star using
\begin_inset Formula $\binaryc$
\end_inset
which collects its output in a buffer.
This buffer is then passed from
\begin_inset Formula $\binaryc$
\end_inset
to
\begin_inset Formula $\binarygrid$
\end_inset
which splits it into lines that are processed by your grid script.
This works, provided the buffer is not too large
\begin_inset Foot
status collapsed
\begin_layout Plain Layout
The maximum buffer size is set by
\begin_inset Flex CMacro
status open
\begin_layout Plain Layout
BUFFERED_PRINTF_MAX_BUFFER_SIZE
\end_layout
\end_inset
which you can find by running
\begin_inset listings
lstparams "language=bash"
inline true
status open
\begin_layout Plain Layout
./binary_c version |grep BUFFERED_PRINTF_MAX_BUFFER_SIZE
\end_layout
\end_inset
.
\end_layout
\end_inset
.
You might argue it is inefficient: and you would be right! In terms of
memory, it is wasteful.
But in terms of
\emph on
speed
\emph default
, which is usually more important, it is not: it is
\emph on
quick
\emph default and what's more it is
\emph on
simple
\emph default
.
\end_layout
\begin_layout Standard
The problem is that the way memory is allocated in operating systems is
typically that it goes up, not down, so once the buffer is allocated it
stays that way (even if
\begin_inset Formula $\binaryc$
\end_inset
frees the memory, the operating system keeps it assigned to the process).
The trick then is to
\emph on
not use the buffer much in the first place!
\emph default
This means you should only output when you need to.
Outputting every timestep is likely to get you into such trouble: you have
\emph on
no idea
\emph default
a priori how many timesteps there may be: it could be tens, could be thousands.
\end_layout
\begin_layout Standard
How can we mitigate this problem? The most obvious way is to output only
when something interesting is happening for you.
Check the example code in
\begin_inset Flex File
status open
\begin_layout Plain Layout
src/logging/log_every_timestep.c
\end_layout
\end_inset
.
You can also set up
\emph on
timestep triggers
\emph default
as described in Sec.
\begin_inset space ~
\end_inset
\begin_inset CommandInset ref
LatexCommand ref
reference "subsec:timestep-triggers"
plural "false"
caps "false"
noprefix "false"
\end_inset
so that output is only at certain times (in linear or logarithmic time).
For example, if you output every
\begin_inset Formula $1\,\mathrm{Myr}$
\end_inset
and have a maximum evolution time of
\begin_inset Formula $100\,\mathrm{Myr}$
\end_inset
, you know you will have
\begin_inset Formula $100$
\end_inset
lines of output, no more
\begin_inset Foot
status collapsed
\begin_layout Plain Layout
You may have more if you are using evolution splitting, but most simulations
do not use this feature.
\end_layout
\end_inset
.
\end_layout
\begin_layout Standard
The other option is to buy more RAM.
It's cheap, but not free.
Remember though, moving memory around also costs you CPU cycles.
Indeed, much of
\begin_inset Formula $\binaryc$
\end_inset
's time is spent doing
\begin_inset Flex CFunction
status open
\begin_layout Plain Layout
memcpy
\end_layout
\end_inset
s: you want to avoid this if you can, just learn to be efficient.
\end_layout
\begin_layout Section
Changelog
\end_layout
\begin_layout Standard
Note this is always an incomplete list!
\end_layout
\begin_layout Description
Version
\begin_inset space ~
\end_inset
2.1 Time integration is now forward-Euler, RK2 or RK4, rationalised the time
evolution loop, events subsystem introduced, fixed timesteps now standard,
command line macros, update mass transfer rates, many bug fixes.
\end_layout
\begin_layout Description
Version
\begin_inset space ~
\end_inset
2.0 Finally, RGI had some time to sit down and redesign the guts of
\emph on
\begin_inset Formula $\binaryc$
\end_inset
\emph default.
Version 2.0 is a cleaned up, sensible version of the old code.
It has better logic, naming, time resolution, setup, etc.
\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
\begin_inset space ~
\end_inset
\family default
\begin_inset Flex CFunction
status open
\begin_layout Plain Layout
nucsyn_WR
\end_layout
\end_inset
), interaction with
\family typewriter
\begin_inset Formula $\binarygrid$
\end_inset
\family default
\begin_inset Flex ScriptingLanguage
status open
\begin_layout Plain Layout
Perl
\end_layout
\end_inset
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
\begin_inset Flex Perlscript
status open
\begin_layout Plain Layout
grid.pl
\end_layout
\end_inset
references,
\begin_inset Flex CFunction
status open
\begin_layout Plain Layoutspiky_luminosity
\end_layout
\end_inset
, removal of the adaptive grid.
Also mention
\begin_inset Flex Perlcode
status open
\begin_layout Plain Layout
gce.pl
\end_layout
\end_inset
.
\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 Section
Acknowledgements
\end_layout
\begin_layout Standard
This document was prepared using the wonderful
\begin_inset CommandInset href
LatexCommand href
name "LyX"
target "https://www.lyx.org/"
literal "false"
\end_inset
.
\end_layout
\begin_layout Standard
\begin_inset Newpage pagebreak
\end_inset
\end_layout
\begin_layout Standard
\paragraph_spacing other 0.0
\begin_inset CommandInset bibtex
LatexCommand bibtex
bibfiles "references"
options "apalike"
\end_inset
\end_layout
\begin_layout Standard
\begin_inset Newpage pagebreak
\end_inset
\end_layout
\begin_layout Standard
\begin_inset CommandInset include
LatexCommand input
filename "binary_grid2_appendix.lyx"
\end_inset
\end_layout
\end_body
\end_document