##### Introduction

There are several program versions. The main ones are **SOC**/**SOCI** for pure scattering calculations and **SOCAM**/**SOCAMI** for dust emission calculations. The programs **SOC** and **SOCAM** work with regular 3d grids, the programs **SOCI** and **SOCAMI** with 3D grids that have been discretised using arbitrary boundary positions along the three coordinate axes. Each program is run from the command line, e.g., "SOC my.ini 0". The command line parameters are the initialisation file (see below) and one numeric flag, 0 for CPU calculation and 1 for GPU calculation. In general, with **SOC**/**SOCI** GPU will be faster, for **SOCAM**/**SOCAMI** CPU should be used.

##### File formats: cloud and dust

For **SOC** and **SOCAM**, the cloud file is identical to that used by **CRT**. The binary file begins with the cloud dimensions (three 4 byte integers) followed by density values (4 byte floats). In the case of **SOCI** and **SOCAMI** the cloud starts at coordinates (0,0,0) and one adds in the file vectors of x, y, and z upper boundary values (4 byte floats × three directions × cloud dimension in that direction) after the cloud dimensions.

The dust is specified with a text file that has the same format as equilibrium temperature grain models in **CRT** (see key word *optical* below). First line has text "eqdust", second and third line have both a single floating point value.The are grain number density *rho* (relative to H) and the grain size *a* (cm). In case of dust models with a size distribution, these are just scaling factors that are used to scale the cross sections. The fourth line contains the number of frequencies. The remaining lines have each four numbers: frequency, asymmetry parameter *g*, absorption efficiency Qabs, and scattering efficiency Qsca. Thus for example optical depth for absorption should be rho pi a^2 Qabs, using the above notation. The calculations use directly the list of frequencies given in this file.

The dust scattering function is stored in a separate file. This is a binary file containing two vectors. The first is the discretised scattering function, the probability per scattering angle (*not* per solid angle) as the function of scattering angle theta. The second vector is the corresponding inverse cumulative probability distribution and thus a list of theta angles, mapping a probability 0...1 into a scattering angle. Both vectors have BINS elements (a value that is told via the keyword *dsc*). For the first one the grid is unitform in cos(theta), for the latter it is uniform in probability.

##### Initialisation file

This is a text file, each line consisting of a keywords and possibly one or more parameters. The keywords are:

absorbed absorbed.data

- Specifies a file to save the number of absorbed photons (the number of photons per unit density, scaled with 1e20). The format is the same that is used by
**CRT**(and**A2E**).

- Specifies a file to save the number of absorbed photons (the number of photons per unit density, scaled with 1e20). The format is the same that is used by

background background.bin

- Specifies the intensity for an isotropic background radiation.

bgpackets 2621440

- Number of photon packages sent from the isotropic background (per frequency and iteration).

cellpackets 1000000

- Number of photon packages sent from the medium (per frequency and iteration).

cloud test.cloud

- Specifies the name of the model cloud (the density distribution).

density 1.0

- Scaling of the density values read from cloud file (optional).

directions 90.0 90.0

- The direction of the observer. The arguments are angles from the position z axis and the rotation around the z axis.

dsc scattering_function.dsc 2500

- Specifies the name of the file containing a discretised representation of the scattering function. The second parameter is the number of direction bins (in cos(theta)).

emitted emitted.data

- Specifies a file to save the number of absorbed photons (the number of photons per unit density, scaled with 1e20). The format is the same that is used by
**CRT**(and**A2E**).

- Specifies a file to save the number of absorbed photons (the number of photons per unit density, scaled with 1e20). The format is the same that is used by

gridlength 4.8828e-01

- Specifies tha cell size. For
**SOC**and**SOCAM**have regular cubic cells where the "grid unit" is always one. In that case this is directly the cell size in parsecs. In**SOCI**and**SOCAMI**the cells have variable sizes but the grid is defined in the cloud file (the three vectors of cell boundary positions) using a certain unit length. For those programs,*gridlength*specifies the length of that unit in parsecs.

- Specifies tha cell size. For

iterations 1

- The number of iterations consisting of the simulation of the radiation field and the recomputation of dust temperatures. If no iterations are needed, set the value to one. If you want only to write out spectra (using previously computed solution), set the number of iterations to 0.

mapping 512 1.00

- Specifies the dimensions of the output maps. The parameters are the number of pixels (the map is always square, # × #) and the pixel size. The size is again in "grid units" so that for
**SOC**and**SOCAM**the value 1.0 gives pixels whose size is the same as the projected size of the cells.

- Specifies the dimensions of the output maps. The parameters are the number of pixels (the map is always square, # × #) and the pixel size. The size is again in "grid units" so that for

noabsorbed

- For
**SOCAMI**only. If calculations do not involve stochastically heated grains, the dust temperatures are solved within**SOCAMI**and the absorbed energy can be integrated on-the-fly, without storing this information for each frequency separately. With the keyword noabsorbed, the absorptions are not saved to a file (see keyword*absorbed*) and the internal storage requirements are reduced.

- For

omp 0

- Specify whether to use or not to use OpenMP parallelisation on the host (values 1/0).

optical mwd_R31.nH2.socdust

- Specifies the name for the file containing dust data.

pspackets 1000000

- Number of photon packages sent from a point source (per frequency and iteration).

remit 849.0 850.0

- For
**SOCAMI**only. If calculations do not involve stochastically heated grains, one can use*remit*to limit the frequencies for which emitted photons are stored (see keyword*emitted*) and the frequency maps that are saved. The arguments are the lower and upper limits of wavelength in units of micrometer. The parameter cannot be used if dust reemission is to be calculated (keyword*cellpackets*).

- For

seed 1.49823

- Seed value for the random number generator.