The main purpose of the COCOA code is to be able to simulate observations of star cluster simulations. The code has been designed to take as an input, the simulation snapshot from the MOCCA code. The simulation snapshot from MOCCA is projected by COCOA and a project snapshot with 3 dimensional positions and velocities of the cluster is created by the main function of the code. Once a projected snapshot is available, observations can be simulated by specifying instrument specifications and distance to the cluster model. FITS files are automatically generated for the projected data. From the projected snapshot, the x position, y position and magnitude of each star is required by the observation module to create synthetic images. The code also includes a PSF photometry pipeline to work out the simulated observational data.

The module for generating synthetic observations in COCOA can also use the snapshot output by NBODY codes as an input for the observation and photometry modules. This snapshot must contain positions and magnitudes of each star in the cluster model in order to simulate observations and the module to carry out PSF photometry can be utilized for the NBODY snapshot with COCOA.

If you utilize COCOA or any of its sub-programs or routines then kindly acknowledge the COCOA paper by Askar et al. 2018. The bibtex-style reference to the code has been provided at the end of this README file.

The COCOA has been primarily developed in python. There are essentially 3 important modules in the code:

1. Projection Module (projection.py): This module requires the extended snapshot from MOCCA as an input. The projection module has an input file (input_projection.py) that needs to be setup. There are different functionalities in the input projection file that can be enabled or disabled. By default, the projection module outputs a single detailed projected snapshot for each star in the system. Binary systems are decomposed to provide positions of individual stars with respect to the center of the cluster. The projection module can be used to generate multiple snapshots over short time intervals and the movement of stars in binaries can be tracked through these multiple snapshots (the time of these multiple snapshots can be provided by the user). There are also options to generate projections with different random number seeds and options to be able to rotate the final projection. There also options to output either the center of mass velocities for binaries or velocities of individual stars in binary systems.

The projection module can also be used to generate surface brightness profiles, velocity dispersion files and King model fits from the projected snapshot using external Fortran routines that are called by the python code.

2. Observation Simulation Module (observation.py): This module generates the simulated observations of the cluster model. This module uses the sim2obs code developed in C (by Wojtek Pych) to create FITS file from projected snapshot data. The input file for the observation.py models can be modified to change the parameters of the instrument which will be observing the simulated telescope (input_observation.py). The observation.py module will require the column numbers for the projected x,y positions (in units of parsec) of stars and magnitudes of the star (from the projected snapshot). The observation.py code will automatically determine the number of frames required to image the cluster model depending on the projected distance to the cluster and the specifications of the instrument with which the synthetic observations will be done. A set of parameter files required by sim2obs will be generated by observation.py (in a sub-directory param-files). The code will then call the sim2obs code using the parameter file and the projected snapshot. Output FITS images will be generated in a sub-directory (fits-files). The output files are numbered using the following convention: x.y.fits where x and y are position coordinates of the frame with respect to the center of the cluster. So the central frame will be named 0.0.fits. The frame to the right of the central frame will be named 1.0.fits. The frame directly above the central frame will 0.1.fits. The frame to the left of the center most frame will be named -1.0.fits. The frame directly below the central frame will be named 0.-1.fits.

3. PSF Photometry Module (photometry.py): This module will carry out PSF photometry on the generated fits image and will output a single catalogue at the end providing positions of stars with respect to the center of cluster (in units of arcsecond), the mangitudes and magnitude error. This module requires the stand-alone versions for daophot and allstar to work. The parameters for daophot and allstar are automatically generated based on the FWHM of the frame. There is an input for the photometry module called input_photometry.py. In this input file one can select whether to determine the FWHM of the provided frame using a code provided with COCOA or whether to use the actual FWHM value of the synthetic observations that are determined at the time of the generation of the fits file with second module (this FWHM value is equal to the entered seeing value divided by the pixel scale of the simulated instrument). Using the photometry.py module, each frame is first analyzed by daophot to do aperture photometry, identify stars for the PSF model and then using those stars create the model for the PSF. Once the PSF model has been generated then allstar is used to carry out PSF photometry. The module automatically uses the output from allstar to correct the position of stars with respect to the center of cluster and to produce a catalogue with the positions and the magnitude and error in magnitude obtained from the photometry of the simulated images.

COCOA was designed primarily to be used on UNIX machines with bash shell. To run the code, the user will need Python 2.7. Most of the python routines are standard and require NumPy and SciPy. The Makefile provided with the code will compile the C and Fortran routines required by COCOA. The makefile can be run from the terminal of the working directory using the make command: $make

There are 2 input files that can be adjusted for the 2 main modules of the code.

1. input_projection.py

2. input_observation.py

3. The input_projection routine contains the following the fields:

-snapshot_name:, in this field one is required to give the path to the input snapshot file. In case, the snapshot file is in the same folder as the COCOA code then the name of the input snapshot file will be sufficient. By default the code has been designed to work with MOCCA snapshot. There is an option to use N-body snapshots to simulate observations as well (for this purpose one needs a snapshot file with 2 position values for each star along with their magnitude). The MOCCA snapshot contains only one dimensional position of the object. The input format of the MOCCA Snapshot is given in the Appendix section of this README file.

-seed: in this field you can enter the random number seed. Altering this can provide you different projections for the snapshot.

-binary_velocities: this field can take values of 0 and 1. The projected snapshot produced by projection.py resolves the positions of binaries with respect to the center of cluster and prints the information of the binary component in 2 different lines. If binary_velocities=0 then the projected center of mass values for the binary velocities are output. If this value is set to 1 then the individual velocities of the binary component with respect to the center of cluster are produced in the output file.

-intimes: The input paramter intimes can have three values 0,1 and 2. This parameter can be used to generate multiple projection files in which the position of the binaries change over short observation times. If the value of this parameter is 0 then only one projected snapshot is generated. If the value is 1 then the user can define a final observation time in days and the interval in days after which each projected snapshot is generated. The value can be set to 2 if the user wants to provide custom time input time (in days) to generate projected snapshots via an input file called time.dat (where each row contains the time in days).

-rotation: This parameter can take the values 0 and 1. This parameter allows the user to rotate the projected snapshot. If value is set to 0 then only one non-rotated projected snapshot is generated. If this value is 1 then the user can provide 3 rotation angles to rotate the projection of the cluster.

In the input file there are also options to generate the surface brightness and velocity dispersion profile from the snapshot data.

-sbpvdp: This parameter can take the value of either 0 or 1. If the value is 0 then no surface brightness or velocity dispersion profile is created. If the value is 1, then a surface brightness and velocity dispersion profile for the cluster model will be generated. If the sbpvdp value is 1 then other parameters need to be entered like: distance to the cluster, reddening and the limiting magnitude of the stars in the cluster (for velocity dispersion profile).

The generated surface brightness and velocity dispersion profile can also be fit to the king model using the routine. There is the possibility to fit both the surface brightness profiles together or only fit the surface brightness profile.

-kingmodel- This parameter can take the value 0 or 1. If it is 0 then the created profiles are not fit to any model. If it is 1 then both the surface brightness and velocity dispersion profiles are fit together. The fitting routines require initial parameters that can be altered (they are found just below the kingmodel input variable). Please note that this routine which does the fitting makes use of numerical recipe functions and may not always be accurate when fitting snapshots from particular cluster models.

Once the input_projection.py has been set up. One can execute the module by entering in the terminal: $python projection.py

The code will then produce a projected snapshot, the name of the default projected snapshot will be: projection0_seed.dat (where seed is the seed value entered in the input file), the output format of this projected snapshot is provided in the section below).

2. To use the second module of the code (simulating observations), The input_observation.py file needs to be setup. In this file the parameters that define the properties of the synthetic observations need to be setup. These parameters are required by the sim2obs code to generate the FITS image from the projected snapshot. These parameters are as follows:

-NAXIS1 (valx) - Image/CCD size in x (units of pixel, typical values ~ 2048, 4096).

-NAXIS2 (valy) - Image/CCD size in y (units of pixel,typical values ~ 2048, 4096).

-DB-NX (posx) - x-coordinate column in projected snapshot file (value of x position should be in pc).

-DB-NY (posy) - y-coordinate column in projected snapshot file (value of y position should be in pc).

-DB-NMAG (dmag) - Magnitude column in projected snapshot file (absolute magnitude).

-OBJECT (obje) - Object name for the simulated observation (any string value may be entered).

-DISTANCE (dist) - Distance to the cluster in units of parsecs.

-FILTER (filt) - Filter name for which the simulation is being generated. Any string can be entered.

-PIXSCALE (pixs)- Gives the pixel scale of the instrument in units of arcseconds/pixel. This defines the spatial resolution -of the telescope.

-GAIN (gain) - Instrument gain in units of photons/ADU.

-SATLEVEL (satl) - Saturation level of the detector in counts.

-EXPOSURE (expo) - Exposure for the observation as a multiple of a direct counts.

-SEEING (seei) - Seeing value for the observation in units of arcseconds

-BACKGROUND (back)- Background level of the simulated observation. Typical values between 1 and 10.

-PSF (psff) - Point spread function (PSF) model for the simulated observation. Either string values 'G' or 'M' can be entered for this parameter. G for Gaussian profile and M for Moffat profile. There are no variations in the PSF produced by sim2obs.

-M_BETA (mbeta) - In the case a Moffat PSF is used, this defines the beta parameter for the Moffat distribution.

-NOISE (noise) - If set to 1 then this parameter introduces a Poisson noise to the observed FITS image. This parameter can take either the value 0 (no noise) or 1 (Poisson noise).

-RA_OFFSET (raof) - Defines the offset value from the center of the cluster in the x direction. This parameter is useful in imaging different field of the cluster model. Units for offset are in arcseconds.

-DEC_OFFSET (deco) - Defines the offset value from the center of the cluster in the y direction. Units for offset are in arcseconds.

-OVERLAP_FACTOR - This parameter defines the overlapping factor between adjoining frames when multiple images need to be made to image the entire cluster model. The value must always be less than 1.0. The default value for this parameter is set to 0.97, this means that there is a 3% overlap between neighboring frames.

There are also two parameters in the param_rtt.py (this file is created after the projection module is run). It will have to edited if the observation module is to be used by itself. The two parameters in this file are:

-rtt - This defines the radial extent of the cluster till which the simulated observations will be calculated. If you would only like to image the cluster up to a certain radius then you can enter that value for this parameter in units of parsec.

-snapname - This variable should contain the name of the projected snapshot file in which you have the three columns that were specified in the input_observation.py file.

Once the input files for the observation module are setup, one can run the module using the following command:

$python observation.py

The code will then compute the number of fields required to image the entire cluster and create a grid of images in a subdirectory within the working directory with the name 'fits-files'. The central most part of the cluster will have the name 0.0.fits. The naming convention for this file is x.y.fits, where x and y indicate the position of the frame from the central most frame. For example, the frame to the right of the center most frame is 1.0.fits. The frame to the left of the central most image is -1.0.fits. The frame above the center most image is 0.1.fits and the image directly below the center most frame is 0.-1.fits.

Once all the images have been generated, the photometry module can be used to carry out PSF photometry on the images in order to get one combined catalogue in which positions of stars from the center of the cluster are given in arcseconds along with the magnitude and the error in the magnitude. In order to run the photometry module, one needs to have stand-alone versions of DAOPHOT and ALLSTAR present in their working directory. The photometry module can be run with the following command:

$python photometry.py

In order to familiarize the user with COCOA, we have provided an example of how to run the different modules of the code for a 12 Gyr snapshot from a MOCCA simulation. The cluster has 4800 objects at 12 Gyrs. The file name for this snapshot is example_snap.dat. The format of the file is given in the beginning of the appendix of this README. The input_projection.py has been setup to read this file as an input and make a projected snapshot. When the user will run projection.py, a projected snapshot with the filename projection0_10.dat will be generated.

After the projected snapshot is generated (for the format of the output file, see the description given in the appendix), the user can then simulate observations of the cluster. The input_observation.py file has default values to mimic a 2.5 meter telescope, the V-band magnitude is used for the simulated observations and the cluster has been placed at a distance of 5 kpc. When the user will run the observation.py file, the code will call the sim2obs routine to generate 9 FITS images to the cluster up to a limiting radius of around 14 pc. The 9 images will be generated in the fits-files folder.

The photometry module can then be used to automatically carry out PSF photometry on the simulated images. A final file called clean_catalogue.dat is generated by the code. This first 2 columns in this file provide the x and y position of the star in arcseconds with respect to the cluster center and the third columns gives the instrumental V-band magnitude and the fourth columns gives the error in magnitude.

If one has a file in which there are 2 dimensional positions and magnitudes for stars, then the sim2obs tool in COCOA can be used as a stand-alone tool to generate synthetic observations in the form of fits files. The executable for sim2obs code can be found in the subdirectory called sim2obs (the executable is generated after running the main makefile). In order to use sim2obs a parameter file needs to be provided. An example of the parameter file is given in the sim2obs subdirectory (sim2obs.par). The format is as follows:

NAXIS1 = 2048 // image size

NAXIS2 = 2048 // image size

DB-NX = 2 // x-coordinate column in database

DB-NY = 3 // y-coordinate column in database

DB-NMAG = 24 // magnitude column in database

OBJECT = M22a // object name

DISTANCE = 3.3e3 // distance [parsecs]

FILTER = V

PIXSCALE = 0.4 // pixel scale [arcseconds]

GAIN = 1.0 // [photons/ADU]

SATLEVEL = 32000.0 // detector saturation level

EXPOSURE = 0.5 // fraction of a direct counts

SEEING = 1.2 // [arcseconds]

BACKGROUND = 10.0 // background level

PSF = M // G-Gaussian, M-Moffat

M_BETA = 1.8 // beta parameter for Moffat

NOISE = 1 // 0: no noise, 1: Poisson noise

RA_OFFSET = 0.0 // RA offset from the center [arcseconds]

DEC_OFFSET = 0.0 // DEC offset from the center [arcseconds]

VERBOSE = 1

END

The parameters in the sim2obs files at the same as for the observation module. After the parameter file is setup, then sim2obs can be executed using the following command:

$./sim2obs 'path-to-parameter-file' 'path-to-input-data-file' 'outputfile-name'

The output file produced by sim2obs will be a FITS image that can be viewed with a tool like ds9 and can be used to visualize simulation results.

COCOA can also be used with snapshots from N-body codes. In those cases one can skip the use of the projection module and directly use the observation and then the photometry modules. Essentially, the observation.py needs the parameters defined in input_observation.py and param_rtt.py. If the user has a snapshot with 2 position components and the magnitude of the object for which they wish to simulate observations then they can directly use the observation module as explain in the section on 'running the code'. Once the simulated images have been generated then the photometry module can be used to get the observed catalogue of stars.

A tool like GALEVNB (see Pang et al. 2016 https://adsabs.harvard.edu/abs/2016RAA....16...37P) can be used to generate magnitude in different filters using the properties of the star.

In case of any errors or problems in running the code, please contact: [email protected]

Input format for MOCCA Snapshot (required by projection.py module):

• 1 - im - star/binary name (inames/inameb)
• 2 - r - position in the cluster in pc
• 3 - vr - radial velocity in km/s
• 4 - vt - tangential velocity in km/s
• 5 - idd1 - star/binary id
• 6 - idd2 - star/binary id
• 7 - ikb - binary type
• 8 - ik1 - star type of the first component
• 9 - ik2 - star type of the second component
• 10 - sm1 - mass of the first component in Msun
• 11 - sm2 - mass of the second component in Msun
• 12 - lum1 - luminosity of the first component
• 13 - lum2 - luminosity of the second component
• 14 - rad1 - radius of the first component
• 15 - rad2 - radius of the second component
• 16 - spin1 -
• 17 - spin2 -
• 18 - iinter1 -
• 19 - iinter2 -
• 20 - a - semi-major axis of a binary in Ro
• 21 - e - eccentricity of the binary
• 22 - mv - magntiude of the object
• 23 - mbmv - B-V colour of the object
• 24 - mi - I band magnitude of the object
• 25 - mv1 - V band magnitude of the first component of the binary
• 26 - mb1mv1 - B-V colour of the first component of the binary
• 27 - mi1 - I band mangitude of the first component of the binary
• 28 - mv2 - V band magnitude of the second component of the binary
• 29 - mb2mv2 - B-V colour of the second component of the binary
• 30 - mi2 - I band magnitude of the second component of the binary

Output format for the Projected Snapshot Generated by COCOA:

• 1 - indb - Binary Indicator (0 indicates that line has data for a single star 1 - indicates that line has data for a binary star)
• 2 - im - MOCCA object identity im
• 3 - rpx - projected x-position in the cluster in pc
• 4 - rpy - projected y-position in the cluster in pc
• 5 - rpz - projected z-position in the cluster in pc
• 6 - vrp - projected line of sight velocity (z-direction) in km/s
• 7 - vtx - projected tangential velocity in x-direction in km/s
• 8 - vty - projected tangential velocity in u-direction in km/s
• 9 - idd1 - MOCCA Star ID for Star 1
• 10 - idd2 - MOCCA Star ID for Star 2
• 11 - ikb - Binary Type
• 12 - ik1 - Star 1 Type
• 13 - ik2 - Star 2 Type
• 14 - sm1 - star/binary mass of the first component in Msun
• 15 - sm2 - binary second component mass in Msun
• 16 - slum1 - luminosity of the first component in Lsun
• 17 - slum2 - binary second component luminosity in Lsun
• 18 - rad1 - star radius of the first component in Rsun
• 19 - rad2 - binary second component radius in Rsun
• 20 - spin1
• 21 - spin2
• 22 - iinter1
• 23 - iinter2
• 24 - a - semi-major axis of a binary in Rsun
• 25 - ecc - eccentricity of a binary
• 26 - mv - V-band magnitude of Star
• 27 - mbv1 - B-V colour of the Star
• 28 - mi1 - I-band Magnitude of Star
• 29 - mb1 - B-band Magnitude of Star
• 30 - mv1
• 31 - mbv1
• 32 - mi1
• 33 - mv2
• 34 - mbv2
• 35 - mi2
• 36 - r - pre-projection radial distance of object from center of cluster in pc
• 37 - vr - pre-projection radial velocity in km/s
• 38 - vt - pre-projection tangential velocity in km/s
• 39 - irc
• 40 - costheta - costheta value for projection
• 41 - phi - phi value for projection
• 42 - eta - eta value for projection
• 43 - periodday - period of the binary
• 44 - t0day - t0 for position and velocity calculation of binary components
• 45 - per0 - periastron angle for the binary
• 46 - long_an - longitude of the ascending node for the binary
• 47 - incl - inclination of the binary system

Output format for the clean_catalogue.dat file produced by the photometry module:

• 1 - X position from the center of cluster in arcseconds
• 2 - Y position from the center of cluster in arcseconds
• 3 - Magnitude of the star
• 4 - Error in magnitude
• 5 - Star ID (generated by DAOPHOT/ALLSTAR for each field)

Bibtex reference to the code:

@ARTICLE{2018MNRAS.475.4170A, author = {{Askar}, A. and {Giersz}, M. and {Pych}, W. and {Dalessandro}, E. }, title = "{COCOA code for creating mock observations of star cluster models}", journal = {\mnras}, archivePrefix = "arXiv", eprint = {1703.09160}, keywords = {methods: numerical, methods: observational, techniques: photometric, globular clusters: general, galaxies: star clusters: general}, year = 2018, month = apr, volume = 475, pages = {4170-4185}, doi = {10.1093/mnras/sty101}, adsurl = {https://adsabs.harvard.edu/abs/2018MNRAS.475.4170A}, adsnote = {Provided by the SAO/NASA Astrophysics Data System} }