## 1 INTRODUCTION

Numerical simulations are the ‘third pillar’ of astrophysics, standing alongside observations and analytic theory. Since it is difficult to perform laboratory experiments in the relevant physical regimes and over the correct range of length and timescales involved in most astrophysical problems, we turn instead to ‘numerical experiments’ in the computer for understanding and insight. As algorithms and simulation codes become ever more sophisticated, the public availability of simulation codes has become crucial to ensure that these experiments can be both verified and reproduced.

Phantom is a smoothed particle hydrodynamics (SPH) code developed over the last decade. It has been used widely for studies of turbulence (e.g. Kitsionas et al. Reference Kitsionas2009; Price & Federrath Reference Price and Federrath2010; Price, Federrath, & Brunt Reference Price, Federrath and Brunt2011), accretion (e.g. Lodato & Price Reference Lodato and Price2010; Nixon, King, & Price Reference Nixon, King and Price2012a; Rosotti, Lodato, & Price Reference Rosotti, Lodato and Price2012), star formation including non-ideal magnetohydrodynamics (MHD) (e.g. Wurster et al. Reference Wurster, Price and Bate2016, Wurster, Price, & Bate Reference Wurster, Price and Bate2017), star cluster formation (Liptai et al. Reference Liptai, Price, Wurster and Bate2017), and for studies of the Galaxy (Pettitt et al. Reference Pettitt, Dobbs, Acreman and Price2014; Dobbs et al. Reference Dobbs, Price, Pettitt, Bate and Tricco2016), as well as for simulating dust–gas mixtures (e.g. Dipierro et al. Reference Dipierro, Price, Laibe, Hirsh and Cerioli2015; Ragusa et al. Reference Ragusa, Dipierro, Lodato, Laibe and Price2017; Tricco, Price, & Laibe Reference Tricco, Price and Laibe2017). Although the initial applications and some details of the basic algorithm were described in Price & Federrath (Reference Price and Federrath2010), Lodato & Price (Reference Lodato and Price2010), and Price (Reference Price2012a), the code itself has never been described in detail and, until now, has remained closed source.

One of the initial design goals of Phantom was to have a low memory footprint. A secondary motivation was the need for a public SPH code that is not primarily focused on cosmology, as in the highly successful Gadget code (Springel, Yoshida, & White Reference Springel, Yoshida and White2001; Springel Reference Springel2005). The needs of different communities produce rather different outcomes in the code. For cosmology, the main focus is on simulating the gravitational collapse of dark matter in large volumes of the universe, with gas having only a secondary effect. This is reflected in the ability of the public Gadget-2 code to scale to exceedingly large numbers of dark matter particles, yet neglecting elements of the core SPH algorithm that are essential for stellar and planetary problems, such as the Morris & Monaghan (Reference Morris and Monaghan1997) artificial viscosity switch [c.f. the debate between Bauer & Springel (Reference Bauer and Springel2012) and Price (Reference Price2012b)], the ability to use a spatially variable gravitational force softening (Bate & Burkert Reference Bate and Burkert1997; Price & Monaghan Reference Price and Monaghan2007) or any kind of artificial conductivity, necessary for the correct treatment of contact discontinuities (Chow & Monaghan Reference Chow and Monaghan1997; Price & Monaghan Reference Price and Monaghan2005; Rosswog & Price Reference Rosswog and Price2007; Price Reference Price2008). Almost all of these have since been implemented in development versions of Gadget-3 (e.g. Iannuzzi & Dolag Reference Iannuzzi and Dolag2011; Beck et al. Reference Beck2016; see recent comparison project by Sembolini et al. Reference Sembolini2016) but remain unavailable or unused in the public version. Likewise, the implementation of dust, non-ideal MHD, and other physics relevant to star and planet formation is unlikely to be high priority in a code designed for studying cosmology or galaxy formation.

Similarly, the sphng code (Benz et al. Reference Benz, Cameron, Press and Bowers1990; Bate Reference Bate1995) has been a workhorse for our group for simulations of star formation (e.g. Price & Bate Reference Price and Bate2007, Reference Price and Bate2009; Price, Tricco, & Bate Reference Price, Tricco and Bate2012; Lewis, Bate, & Price Reference Lewis, Bate and Price2015) and accretion discs (e.g. Lodato & Rice Reference Lodato and Rice2004; Cossins, Lodato, & Clarke Reference Cossins, Lodato and Clarke2009), contains a rich array of physics necessary for star and planet formation including all of the above algorithms, but the legacy nature of the code makes it difficult to modify or debug and there are no plans to make it public.

Gasoline (Wadsley, Stadel, & Quinn Reference Wadsley, Stadel and Quinn2004) is another code that has been widely and successfully used for galaxy formation simulations, with its successor, Gasoline 2 (Wadsley et al. Reference Wadsley, Keller and Quinn2017), recently publicly released. Hubber et al. (Reference Hubber, Batty, McLeod and Whitworth2011) have developed Seren with similar goals to Phantom, focused on star cluster simulations. Seren thus presents more advanced *N*-body algorithms compared to what is in Phantom but does not yet include magnetic fields, dust, or H_{2} chemistry.

A third motivation was the need to distinguish between the ‘high performance’ code used for 3D simulations from simpler codes used to develop and test algorithms, such as our already-public ndspmhd code (Price Reference Price2012a). Phantom is designed to ‘take what works and make it fast’, rather than containing options for every possible variation on the SPH algorithm. Obsolete options are actively deleted.

The initial release of Phantom has been developed with a focus on stellar, planetary, and Galactic astrophysics, as well as accretion discs. In this first paper, coinciding with the first stable public release, we describe and validate the core algorithms as well as some example applications. Various novel aspects and optimisation strategies are also presented. This paper is an attempt to document in detail what is currently available in the code, which include modules for MHD, dust–gas mixtures, self-gravity, and a range of other physics. The paper is also designed to serve as guide to the correct use of the various algorithms. Stable releases of Phantom are posted on the webFootnote ^{1}, while the development version and wiki documentation are available on the Bitbucket platformFootnote ^{2}.

The paper is organised as follows: We describe the numerical methods in Section 2 with corresponding numerical tests in Section 5. We cover SPH basics (Section 2.1), our implementation of hydrodynamics (Sections 2.2 and 5.1), the timestepping algorithm (Section 2.3), external forces (Sections 2.4 and 5.2), turbulent forcing (Sections 2.5 and 6.1), accretion disc viscosity (Sections 2.6 and 5.3), Navier–Stokes viscosity (Sections 2.7 and 5.4), sink particles (Sections 2.8 and 5.5), stellar physics (Section 2.9), MHD (Sections 2.10 and 5.6), non-ideal MHD (Sections 2.11 and 5.7), self-gravity (Sections 2.12 and 5.8), dust–gas mixtures (Sections 2.13 and 5.9), ISM chemistry and cooling (Sections 2.14 and 5.10), and particle injection (Section 2.15). We present the algorithms for generating initial conditions in Section 3. Our approach to software engineering is described in Section 4. We give five examples of recent applications highlighting different aspects of Phantom in Section 6. We summarise in Section 7.

## 2 NUMERICAL METHOD

Phantom is based on the SPH technique, invented by Lucy (Reference Lucy1977) and Gingold & Monaghan (Reference Gingold and Monaghan1977) and the subject of numerous reviews (Benz Reference Benz and Buchler1990; Monaghan Reference Monaghan1992, Reference Monaghan2005, Reference Monaghan2012; Rosswog Reference Rosswog2009; Springel Reference Springel2010; Price Reference Price2012a).

In the following, we adopt the convention that *a*, *b*, and *c* refer to particle indices; *i*, *j*, and *k* refer to vector or tensor indices; and *n* and *m* refer to indexing of nodes in the treecode.

### 2.1. Fundamentals

#### 2.1.1. Lagrangian hydrodynamics

SPH solves the equations of hydrodynamics in Lagrangian form. The fluid is discretised onto a set of ‘particles’ of mass *m* that are moved with the local fluid velocity ${\bm v}$. Hence, the two basic equations common to all physics in Phantom are

where ${\bm r}$ is the particle position and ρ is the density. These equations use the Lagrangian time derivative, ${\rm d}/{\rm d}t \equiv \partial / \partial t + {\bm v} \cdot \nabla$, and are the Lagrangian update of the particle position and the continuity equation (expressing the conservation of mass), respectively.

#### 2.1.2. Conservation of mass in SPH

The density is computed in Phantom using the usual SPH density sum

where *a* and *b* are particle labels, *m* is the mass of the particle, *W* is the smoothing kernel, *h* is the smoothing length, and the sum is over neighbouring particles (i.e. those within *R* _{kern}*h*, where *R* _{kern} is the dimensionless cut-off radius of the smoothing kernel). Taking the Lagrangian time derivative of (3), one obtains the discrete form of (2) in SPH

where $W_{ab}(h_{a})\equiv W(\vert {\bm r}_{a} - {\bm r}_{b}\vert , h_{a})$ and Ω_{a} is a term related to the gradient of the smoothing length (Springel & Hernquist Reference Springel and Hernquist2002; Monaghan Reference Monaghan2002) given by

Equation (4) is not used directly to compute the density in Phantom, since evaluating (3) provides a time-independent solution to (2) (see e.g. Monaghan Reference Monaghan1992; Price Reference Price2012a for details). The time-dependent version (4) is equivalent to (3) up to a boundary term (see Price Reference Price2008) but is only used in Phantom to predict the smoothing length at the next timestep in order to reduce the number of iterations required to evaluate the density (see below).

Since (3)–(5) all depend on the kernel evaluated on neighbours within *R* _{kern} times *h* _{a}, all three of these summations may be computed simultaneously using a single loop over the same set of neighbours. Details of the neighbour finding procedure are given in Section 2.1.7.

#### 2.1.3. Setting the smoothing length

The smoothing length itself is specified as a function of the particle number density, *n*, via

where *h* _{fact} is the proportionality factor specifying the smoothing length in terms of the mean local particle spacing and the second equality holds only for equal mass particles, which are enforced in Phantom. The restriction to equal mass particles means that the resolution strictly follows mass, which may be restrictive for problems involving large density contrasts (e.g. Hutchison et al. Reference Hutchison, Price, Laibe and Maddison2016). However, our view is that the potential pitfalls of unequal mass particles (see e.g. Monaghan & Price Reference Monaghan and Price2006) are currently too great to allow for a robust implementation in a public code.

As described in Price (Reference Price2012a), the proportionality constant *h* _{fact} can be related to the mean neighbour number according to

however, this is only equal to the *actual* neighbour number for particles in a uniform density distribution (more specifically, for a density distribution with no second derivative), meaning that the actual neighbour number varies. The default setting for *h* _{fact} is 1.2, corresponding to an average of 57.9 neighbours for a kernel truncated at 2*h* (i.e. for *R* _{kern} = 2) in three dimensions. Table 1 lists the settings recommended for different choices of kernel. The derivative required in (5) is given by

#### 2.1.4. Iterations for h and ρ

The mutual dependence of ρ and *h* means that a rootfinding procedure is necessary to solve both (3) and (6) simultaneously. The procedure implemented in Phantom follows Price & Monaghan (Reference Price and Monaghan2004b, Reference Price and Monaghan2007), solving, for each particle, the equation

where ρ_{sum} is the density computed from (3) and

from (6). Equation (9) is solved with Newton–Raphson iterations:

where the derivative is given by

The iterations proceed until |*h* _{a, new} − *h* _{a}|/*h* _{a, 0} < ε_{h}, where *h* _{a, 0} is the smoothing length of particle *a* at the start of the iteration procedure and ε_{h} is the tolerance. The convergence with Newton–Raphson is fast, with a quadratic reduction in the error at each iteration, meaning that no more than 2–3 iterations are required even with a rapidly changing density field. We avoid further iterations by predicting the smoothing length from the previous timestep according to

where dρ_{a}/d*t* is evaluated from (4).

Since *h* and ρ are mutually dependent, we store only the smoothing length, from which the density can be obtained at any time via a function call evaluating ρ(*h*). The default value of ε_{h} is 10^{−4} so that *h* and ρ can be used interchangeably. Setting a small tolerance does not significantly change the computational cost, as the iterations quickly fall below a tolerance of ‘one neighbour’ according to (7), so any iterations beyond this refer to loops over the same set of neighbours which can be efficiently cached. However, it is important that the tolerance may be enforced to arbitrary precision rather than being an integer as implemented in the public version of Gadget, since (9) expresses a mathematical relationship between *h* and ρ that is assumed throughout the derivation of the SPH algorithm (see discussion in Price Reference Price2012a). The precision to which this is enforced places a lower limit on the total energy conservation. Fortunately, floating point neighbour numbers are now default in most Gadget-3 variants also.

#### 2.1.5. Kernel functions

We write the kernel function in the form

where *C* _{norm} is a normalisation constant, the factor of *h* ^{3} gives the dimensions of inverse volume, and *f*(*q*) is a dimensionless function of $q \equiv \vert {\bm r}_{a} - {\bm r}_{b} \vert / h$. Various relations for kernels in this form are given in Morris (Reference Morris1996a) and in Appendix B of Price (Reference Price2010). Those used in Phantom are the kernel gradient

and the derivative of the kernel with respect to *h*,

Notice that the ∂*W*/∂*h* term in particular can be evaluated simply from the functions needed to compute the density and kernel gradient and hence does not need to be derived separately if a different kernel is used.

#### 2.1.6. Choice of smoothing kernel

The default kernel function in SPH for the last 30 yr (since Monaghan & Lattanzio Reference Monaghan and Lattanzio1985) has been the *M* _{4} cubic spline from the Schoenberg (Reference Schoenberg1946) B-spline family, given by

where the normalisation constant *C* _{norm} = 1/π in 3D and the compact support of the function implies that *R* _{kern} = 2. While the cubic spline kernel is satisfactory for many applications, it is not always the best choice. Most SPH kernels are based on approximating the Gaussian, but with compact support to avoid the $\mathcal {O}(N^{2})$ computational cost. Convergence in SPH is guaranteed to be second order (∝*h* ^{2}) to the degree that the finite summations over neighbouring particles approximate integrals (e.g. Monaghan Reference Monaghan1992, Reference Monaghan2005; Price Reference Price2012a). Hence, the choice of kernel and the effect that a given kernel has on the particle distribution are important considerations.

In general, more accurate results will be obtained with a kernel with a larger compact support radius, since it will better approximate the Gaussian which has excellent convergence and stability properties (Morris Reference Morris1996a; Price Reference Price2012a; Dehnen & Aly Reference Dehnen and Aly2012). However, care is required. One should not simply increase *h* _{fact} for the cubic spline kernel because even though this implies more neighbours [via (7)], it increases the resolution length. For the B-splines, it also leads to the onset of the ‘pairing instability’ where the particle distribution becomes unstable to transverse modes, leading to particles forming close pairs (Thomas & Couchman Reference Thomas and Couchman1992; Morris Reference Morris1996a, Reference Morris1996b; Børve, Omang, & Trulsen Reference Børve, Omang and Trulsen2004; Price Reference Price2012a; Dehnen & Aly Reference Dehnen and Aly2012). This is the motivation of our default choice of *h* _{fact} = 1.2 for the cubic spline kernel, since it is just short of the maximum neighbour number that can be used while remaining stable to the pairing instability.

A better approach to reducing kernel bias is to keep the same resolution lengthFootnote ^{3} but to use a kernel that has a larger compact support radius. The traditional approach (e.g. Morris Reference Morris1996a, Reference Morris1996b; Børve et al. Reference Børve, Omang and Trulsen2004; Price Reference Price2012a) has been to use the higher kernels in the B-spline series, i.e. the *M* _{5} quartic which extends to 2.5*h*

where *C* _{norm} = 1/(20π), and the *M* _{6} quintic extending to 3*h*,

where *C* _{norm} = 1/(120π) in 3D. The quintic in particular gives results virtually indistinguishable from the Gaussian for most problems.

Recently, there has been tremendous interest in the use of the Wendland (Reference Wendland1995) kernels, particularly since Dehnen & Aly (Reference Dehnen and Aly2012) showed that they are stable to the pairing instability at all neighbour numbers despite having a Gaussian-like shape and compact support. These functions are constructed as the unique polynomial functions with compact support but with a positive Fourier transform, which turns out to be a necessary condition for stability against the pairing instability (Dehnen & Aly Reference Dehnen and Aly2012). The 3D Wendland kernels scaled to a radius of 2*h* are given by *C* ^{2}:

where *C* _{norm} = 21/(16π), the *C* ^{4} kernel

where *C* _{norm} = 495/(256π), and the *C* ^{6} kernel

where *C* _{norm} = 1365/(512π). Figure 1 graphs *f*(*q*) and its first and second derivative for each of the kernels available in Phantom.

Several authors have argued for use of the Wendland kernels by default. For example, Rosswog (Reference Rosswog2015) found best results on simple test problems using the *C* ^{6} Wendland kernel. However, ‘best’ in that case implied using an average of 356 neighbours in 3D (i.e. *h* _{fact} = 2.2 with *R* _{kern} = 2.0) which is a factor of 6 more expensive than the standard approach. Similarly, Hu et al. (Reference Hu, Naab, Walch, Moster and Oser2014) recommend the *C* ^{4} kernel with 200 neighbours which is 3.5 times more expensive. The large number of neighbours are needed because the Wendland kernels are always worse than the B-splines for a given number of neighbours due to the positive Fourier transform, meaning that the kernel bias (related to the Fourier transform) is always positive where the B-spline errors oscillate around zero (Dehnen & Aly Reference Dehnen and Aly2012). Hence, whether or not this additional cost is worthwhile depends on the application. A more comprehensive analysis would be valuable here, as the ‘best’ choice of kernel remains an open question (see also the kernels proposed by Cabezón, García-Senz, & Relaño Reference Cabezón, García-Senz and Relaño2008; García-Senz et al. Reference García-Senz, Cabezón, Escartín and Ebinger2014). An even broader question regards the kernel used for dissipation terms, for gravitational force softening and for drag in two-fluid applications (discussed further in Section 2.13). For example, Laibe & Price (Reference Laibe and Price2012a) found that double-hump-shaped kernels led to more than an order of magnitude improvement in accuracy when used for drag terms.

A simple and practical approach to checking that kernel bias does not affect the solution that we have used and advocate when using Phantom is to first attempt a simulation with the cubic spline, but then to check the results with a low resolution calculation using the quintic kernel. If the results are identical, then it indicates that the kernel bias is not important, but if not, then use of smoother but costlier kernels such as *M* _{6} or *C* ^{6} may be warranted. Wendland kernels are mainly useful for preventing the pairing instability and are necessary if one desires to employ a large number of neighbours.

#### 2.1.7. Neighbour finding

Finding neighbours is the main computational expense to any SPH code. Earlier versions of Phantom contained three different options for neighbour-finding: a Cartesian grid, a cylindrical grid, and a *k*d-tree. This was because we wrote the code originally with non-self-gravitating problems in mind, for which the overhead associated with a treecode is unnecessary. Since the implementation of self-gravity in Phantom the *k*d-tree has become the default, and is now sufficiently well optimised that the fixed-grid modules are more efficient only for simulations that do not employ either self-gravity or individual particle timesteps, which are rare in astrophysics.

A key optimisation strategy employed in Phantom is to perform the neighbour search for groups of particles. The results of this search (i.e. positions of all trial neighbours) are then cached and used to check for neighbours for individual particles in the group. Our *k*d-tree algorithm closely follows Gafton & Rosswog (Reference Gafton and Rosswog2011), splitting the particles recursively based on the centre of mass and bisecting the longest axis at each level (Figure 2). The tree build is refined until a cell contains less than *N* _{min} particles, which is then referred to as a ‘leaf node’. By default, *N* _{min} = 10. The neighbour search is then performed once for each leaf node. Further details are given in Appendix A.3.1.

### 2.2. Hydrodynamics

#### 2.2.1. Compressible hydrodynamics

The equations of compressible hydrodynamics are solved in the form

where *P* is the pressure, *u* is the specific internal energy, ${\bm a}_{\rm ext}$, ${\bm a}_{\rm sink-gas}$ and ${\bm a}_{\rm selfgrav}$ refer to (optional) accelerations from ‘external’ or ‘body’ forces (Section 2.4), sink particles (Section 2.8), and self-gravity (Section 2.12), respectively. Π_{shock} and Λ_{shock} are dissipation terms required to give the correct entropy increase at a shock front, and Λ_{cool} is a cooling term.

#### 2.2.2. Equation of state

The equation set is closed by an equation of state (EOS) relating the pressure to the density and/or internal energy. For an ideal gas, this is given by

where γ is the adiabatic index and the sound speed *c* _{s} is given by

The internal energy, *u*, can be related to the gas temperature, *T*, using

giving

where *k* _{B} is Boltzmann’s constant, μ is the mean molecular weight, and *m* _{H} is the mass of a hydrogen atom. Thus, to infer the temperature, one needs to specify a composition, but only the internal energy affects the gas dynamics. Equation (25) with γ = 5/3 is the default EOS in Phantom.

In the case where shocks are assumed to radiate away all of the heat generated at the shock front (i.e. Λ_{shock} = 0) and there is no cooling (Λ_{cool} = 0), (24) becomes simply, using (2)

which, using (25) can be integrated to give

where *K* is the polytropic constant. Even more simply, in the case where the temperature is assumed constant, or prescribed as a function of position, the EOS is simply

In both of these cases, (30) and (31), the internal energy does not need to be stored. In this case, the temperature is effectively set by the value of *K* (and the density if γ ≠ 1). Specifically,

#### 2.2.3. Code units

For pure hydrodynamics, physical units are irrelevant to the numerical results since (1)–(2) and (23)–(24) are scale free to all but the Mach number. Hence, setting physical units is only useful when comparing simulations with Nature, when physical heating or cooling rates are applied via (24), or when one wishes to interpret the results in terms of temperature using (28) or (32).

In the case where gravitational forces are applied, either using an external force (Section 2.4) or using self-gravity (Section 2.12), we adopt the standard procedure of transforming units such that *G* = 1 in code units, i.e.

where *u* _{time}, *u* _{dist}, and *u* _{mass} are the units of time, length, and mass, respectively. Additional constraints apply when using relativistic terms (Section 2.4.5) or magnetic fields (Section 2.10.3).

#### 2.2.4. Equation of motion in SPH

We follow the variable smoothing length formulation described by Price (Reference Price2012a), Price & Federrath (Reference Price and Federrath2010), and Lodato & Price (Reference Lodato and Price2010). We discretise (23) using

where the *q ^{a}_{ab}* and

*q*terms represent the artificial viscosity (discussed in Section 2.2.7).

^{b}_{ab}#### 2.2.5. Internal energy equation

The internal energy equation (24) is discretised using the time derivative of the density sum (c.f. 29), which from (4) gives

where ${\bm v}_{ab} \equiv {\bm v}_a - {\bm v}_b$. In the variational formulation of SPH (e.g. Price Reference Price2012a), this expression is used as a constraint to derive (34), which guarantees both the conservation of energy and entropy (the latter in the absence of dissipation terms). The shock capturing terms in the internal energy equation are discussed below.

By default, we assume an adiabatic gas, meaning that *P*d*V* work and shock heating terms contribute to the thermal energy of the gas, no energy is radiated to the environment, and total energy is conserved. To approximate a radiative gas, one may set one or both of these terms to zero. Neglecting the shock heating term, Λ_{shock}, gives an approximation equivalent to a polytropic EOS (30), as described in Section 2.2.2. Setting both shock and work contributions to zero implies that d*u*/d*t* = 0, meaning that each particle will simply retain its initial temperature.

#### 2.2.6. Conservation of energy in SPH

Does evolving the internal energy equation imply that total energy is not conserved? Wrong! Total energy in SPH, for the case of hydrodynamics, is given by

Taking the (Lagrangian) time derivative, we find that conservation of energy corresponds to

Inserting our expressions (34) and (35), and neglecting for the moment dissipative terms and external forces, we find

The double summation on the right-hand side equals zero because the kernel gradient, and hence the overall sum, is antisymmetric. That is, ∇_{a}*W* _{ab} = −∇_{b}*W* _{ba}. This means one can relabel the summation indices arbitrarily in one half of the sum, and add it to one half of the original sum to give zero. One may straightforwardly verify that this remains true when one includes the dissipative terms (see below).

This means that even though we employ the internal energy equation, total energy remains conserved to machine precision in the spatial discretisation. That is, energy is conserved irrespective of the number of particles, the number of neighbours or the choice of smoothing kernel. The only non-conservation of energy arises from the ordinary differential equation solver one employs to solve the left-hand side of the equations. We thus employ a symplectic time integration scheme in order to preserve the conservation properties as accurately as possible (Section 2.3.1).

#### 2.2.7. Shock capturing: momentum equation

The shock capturing dissipation terms are implemented following Monaghan (Reference Monaghan1997), derived by analogy with Riemann solvers from the special relativistic dissipation terms proposed by Chow & Monaghan (Reference Chow and Monaghan1997). These were extended by Price & Monaghan (Reference Price and Monaghan2004b, Reference Price and Monaghan2005) to MHD and recently to dust–gas mixtures by Laibe & Price (Reference Laibe and Price2014b). In a recent paper, Puri & Ramachandran (Reference Puri and Ramachandran2014) found this approach, along with the Morris & Monaghan (Reference Morris and Monaghan1997) switch (which they referred to as the ‘Monaghan–Price–Morris’ formulation) to be the most accurate and robust method for shock capturing in SPH when compared to several other approaches, including Godunov SPH (e.g. Inutsuka Reference Inutsuka2002; Cha & Whitworth Reference Cha and Whitworth2003).

The formulation in Phantom differs from that given in Price (Reference Price2012a) only by the way that the density and signal speed in the *q* terms are averaged, as described in Price & Federrath (Reference Price and Federrath2010) and Lodato & Price (Reference Lodato and Price2010). That is, we use

where

where ${\bm v}_{ab} \equiv {\bm v}_{a} - {\bm v}_{b}$, $\hat{\bm r}_{ab} \equiv ({\bm r}_{a} - {\bm r}_{b})/\vert {\bm r}_{a} - {\bm r}_{b} \vert$ is the unit vector along the line of sight between the particles, and *v* _{sig} is the maximum signal speed, which depends on the physics implemented. For hydrodynamics, this is given by

where in general α^{AV}_{a} ∈ [0, 1] is controlled by a switch (see Section 2.2.9), while β^{AV} = 2 by default.

Importantly, α does *not* multiply the β^{AV} term. The β^{AV} term provides a second-order Von Neumann & Richtmyer-like term that prevents particle interpenetration (e.g. Lattanzio et al. Reference Lattanzio, Monaghan, Pongracic and Schwarz1986; Monaghan Reference Monaghan1989), and thus β^{AV} ⩾ 2 is needed wherever particle penetration may occur. This is important in accretion disc simulations where use of a low α may be acceptable in the absence of strong shocks, but a low β will lead to particle penetration of the disc midplane, which is the cause of a number of convergence issues (Meru & Bate Reference Meru and Bate2011, Reference Meru and Bate2012). Price & Federrath (Reference Price and Federrath2010) found that β^{AV} = 4 was necessary at high Mach number (*M* ≳ 5) to maintain a sharp shock structure, which despite nominally increasing the viscosity was found to give less dissipation overall because particle penetration no longer occurred at shock fronts.

#### 2.2.8. Shock capturing: internal energy equation

The key insight from Chow & Monaghan (Reference Chow and Monaghan1997) was that shock capturing not only involves a viscosity term but involves dissipating the jump in each component of the energy, implying a conductivity term in hydrodynamics and resistive dissipation in MHD (see Section 2.10.5). The resulting contribution to the internal energy equation is given by (e.g. Price Reference Price2012a)

where the first term provides the viscous shock heating, the second term provides an artificial thermal conductivity, *F* _{ab} is defined as in (15), and Λ_{artres} is the heating due to artificial resistivity [Equation (182)]. The signal speed we use for conductivity term differs from the one used for viscosity, as discussed by Price (Reference Price2008, Reference Price2012a). In Phantom, we use

for simulations that do not involve self-gravity or external body forces (Price Reference Price2008), and

for simulations that do (Wadsley, Veeravalli, & Couchman Reference Wadsley, Veeravalli and Couchman2008). The importance of the conductivity term for treating contact discontinuities was highlighted by Price (Reference Price2008), explaining the poor results found by Agertz et al. (Reference Agertz2007) in SPH simulations of Kelvin–Helmholtz instabilities run across contact discontinuities (discussed further in Section 5.1.4). With (44), we have found there is no need for further switches to reduce conductivity (e.g. Price Reference Price2004; Price & Monaghan Reference Price and Monaghan2005; Valdarnini Reference Valdarnini2016), since the effective thermal conductivity κ is second order in the smoothing length (∝*h* ^{2}). Phantom therefore uses α_{u} = 1 by default in (42) and we have not yet found a situation where this leads to excess smoothing.

It may be readily shown that the total energy remains conserved in the presence of dissipation by combining (42) with the corresponding dissipative terms in (34). The contribution to the entropy from both viscosity and conductivity is also positive definite (see the appendix in Price & Monaghan Reference Price and Monaghan2004b for the mathematical proof in the case of conductivity).

#### 2.2.9. Shock detection

The standard approach to reducing dissipation in SPH away from shocks for the last 15 yr has been the switch proposed by Morris & Monaghan (Reference Morris and Monaghan1997), where the dimensionless viscosity parameter α is evolved for each particle *a* according to

where τ ≡ *h*/(σ_{decay}*v* _{sig}) and σ_{decay} = 0.1 by default. We set *v* _{sig} in the decay time equal to the sound speed to avoid the need to store dα/d*t*, since $\nabla \cdot {\bm v}$ is already stored in order to compute (4). This is the switch used for numerous turbulence applications with Phantom (e.g. Price & Federrath Reference Price and Federrath2010; Price et al. Reference Price, Federrath and Brunt2011; Tricco et al. Reference Tricco, Price and Federrath2016b) where it is important to minimise numerical dissipation in order to maximise the Reynolds number (e.g. Valdarnini Reference Valdarnini2011; Price Reference Price2012b).

More recently, Cullen & Dehnen (Reference Cullen and Dehnen2010) proposed a more advanced switch using the time derivative of the velocity divergence. A modified version based on the gradient of the velocity divergence was also proposed by Read & Hayfield (Reference Read and Hayfield2012). We implement a variation on the Cullen & Dehnen (Reference Cullen and Dehnen2010) switch, using a shock indicator of the form

where

is a modification of the Balsara (Reference Balsara1995) viscosity limiter for shear flows. We use this to set α according to

where *c* _{s} is the sound speed and α_{max} = 1. We use *c* _{s} in the expression for α_{loc} also for MHD (Section 2.10) since we found using the magnetosonic speed led to a poor treatment of MHD shocks. If α_{loc, a} > α_{a}, we set α_{a} = α_{loc, a}, otherwise we evolve α_{a} according to

where τ is defined as in the Morris & Monaghan (Reference Morris and Monaghan1997) version, above. We evolve α in the predictor part of the integrator only, i.e. with a first-order time integration, to avoid complications in the corrector step. However, we perform the predictor step implicitly using a backward Euler method, i.e.

which ensures that the decay is stable regardless of the timestep (we do this for the Morris & Monaghan method also).

We use the method outlined in Appendix B3 of Cullen & Dehnen (Reference Cullen and Dehnen2010) to compute ${\rm d}(\nabla \cdot {\bm v}_{a})/{{\rm d}t}$. That is, we first compute the gradient tensors of the velocity, ${\bm v}$, and acceleration, ${\bm a}$ (used from the previous timestep), during the density loop using an SPH derivative operator that is exact to linear order, that is, with the matrix correction outlined in Price (Reference Price2004, Reference Price2012a), namely

where

and repeated tensor indices imply summation. Finally, we construct the time derivative of the velocity divergence according to

where, as previously, repeated *i* and *j* indices imply summation. In Cartesian coordinates, the last term in (53) can be written out explicitly using

#### 2.2.10. Cooling

The cooling term Λ_{cool} can be set either from detailed chemical calculations (Section 2.14.1) or, for discs, by the simple ‘β-cooling’ prescription of Gammie (Reference Gammie2001), namely

where

with β_{cool} an input parameter to the code specifying the cooling timescale in terms of the local orbital time. We compute Ω in (56) using Ω ≡ 1/(*x* ^{2} + *y* ^{2} + *z* ^{2})^{3/2}, i.e. assuming Keplerian rotation around a central object with mass equal to unity, with *G* = 1 in code units.

#### 2.2.11. Conservation of linear and angular momentum

The total linear momentum is given by

such that conservation of momentum corresponds to

Inserting our discrete equation (34), we find

where, as for the total energy (Section 2.2.6), the double summation is zero because of the antisymmetry of the kernel gradient. The same argument applies to the conservation of angular momentum,

(see e.g. Price Reference Price2012a for a detailed proof). As with total energy, this means linear and angular momentum are exactly conserved by our SPH scheme to the accuracy with which they are conserved by the timestepping scheme.

In Phantom, linear and angular momentum are both conserved to round-off error (typically ~10^{−16} in double precision) with global timestepping, but exact conservation is violated when using individual particle timesteps or when using the *k*d-tree to compute gravitational forces. The magnitude of these quantities, as well as the total energy and the individual components of energy (kinetic, internal, potential, and magnetic), should thus be monitored by the user at runtime. Typically with individual timesteps, one should expect energy conservation to Δ*E*/*E* ~ 10^{−3} and linear and angular momentum conservation to ~10^{−6} with default code settings. The code execution is aborted if conservation errors exceed 10%.

### 2.3. Time integration

#### 2.3.1. Timestepping algorithm

We integrate the equations of motion using a generalisation of the Leapfrog integrator which is reversible in the case of both velocity dependent forces and derivatives which depend on the velocity field. The basic integrator is the Leapfrog method in ‘Kick–Drift–Kick’ or ‘Velocity Verlet’ form (Verlet Reference Verlet1967), where the positions and velocities of particles are updated from time *t* ^{n} to *t* ^{n + 1} according to

where Δ*t* ≡ *t* ^{n + 1} − *t* ^{n}. This is identical to the formulation of Leapfrog used in other astrophysical SPH codes (e.g. Springel Reference Springel2005; Wadsley et al. Reference Wadsley, Stadel and Quinn2004). The Verlet scheme, being both reversible and symplectic (e.g. Hairer, Lubich, & Wanner Reference Hairer, Lubich and Wanner2003), preserves the Hamiltonian nature of the SPH algorithm (e.g. Gingold & Monaghan Reference Gingold and Monaghan1982b; Monaghan & Price Reference Monaghan and Price2001). In particular, both linear and angular momentum are exactly conserved, there is no long-term energy drift, and phase space volume is conserved (e.g. for orbital dynamics). In SPH, this is complicated by velocity-dependent terms in the acceleration from the shock-capturing dissipation terms. In this case, the corrector step, (64), becomes implicit. The approach we take is to notice that these terms are not usually dominant over the position-dependent terms. Hence, we use a first-order prediction of the velocity, as follows:

At the end of the step, we then check if the error in the first-order prediction is less than some tolerance ε according to

where ${\bm v}^{\rm mag}$ is the mean velocity on all SPH particles (we set the error to zero if $\vert {\bm v}^{\rm mag}\vert = 0$) and by default ε_{v} = 10^{−2}. If this criterion is violated, then we recompute the accelerations by replacing ${\bm v}^{*}$ with ${\bm v}^{n+1}$ and iterating (68) and (69) until the criterion in (70) is satisfied. In practice, this happens rarely, but occurs for example in the first few steps of the Sedov problem where the initial conditions are discontinuous (Section 5.1.3). As each iteration is as expensive as halving the timestep, we also constrain the subsequent timestep such that iterations should not occur, i.e.

where *e* _{max} = max(*e*) over all particles. A caveat to the above is that velocity iterations are not currently implemented when using individual particle timesteps.

Additional variables such as the internal energy, *u*, and the magnetic field, ${\bm B}$, are timestepped with a predictor and trapezoidal corrector step in the same manner as the velocity, following (65), (67) and (69).

Velocity-dependent external forces are treated separately, as described in Section 2.4.

#### 2.3.2. Timestep constraints

The timestep itself is determined at the end of each step, and is constrained to be less than the maximum stable timestep. For a given particle, *a*, this is given by (e.g. Lattanzio et al. Reference Lattanzio, Monaghan, Pongracic and Schwarz1986; Monaghan Reference Monaghan1997)

where *C* _{cour} = 0.3 by default (Lattanzio et al. Reference Lattanzio, Monaghan, Pongracic and Schwarz1986) and *v* ^{dt}_{sig} is taken as the maximum of (41) over the particle’s neighbours assuming α^{AV} = max(α^{AV}, 1). The criterion above differs from the usual Courant–Friedrichs–Lewy condition used in Eulerian codes (Courant, Friedrichs, & Lewy Reference Courant, Friedrichs and Lewy1928) because it depends only on the difference in velocity between neighbouring particles, not the absolute value.

An additional constraint is applied from the accelerations (the ‘force condition’), where

where *C* _{force} = 0.25 by default. A separate timestep constraint is applied for external forces

and for accelerations to SPH particles to/from sink particles (Section 2.8)

For external forces with potentials defined such that Φ → 0 as *r* → ∞, an additional constraint is applied using (Dehnen & Read Reference Dehnen and Read2011)

where $\eta _\Phi = 0.05$ (see Section 2.8.5).

The timestep for particle *a* is then taken to be the minimum of all of the above constraints, i.e.

with possible other constraints arising from additional physics as described in their respective sections. With global timestepping, the resulting timestep is the minimum over all particles

#### 2.3.3. Substepping of external forces

In the case where the timestep is dominated by any of the external force timesteps, i.e. (74)–(76), we implement an operator splitting approach implemented according to the reversible reference system propagator algorithm (RESPA) derived by Tuckerman, Berne, & Martyna (Reference Tuckerman, Berne and Martyna1992) for molecular dynamics. RESPA splits the acceleration into ‘long-range’ and ‘short-range’ contributions, which in Phantom are defined to be the SPH and external/point-mass accelerations, respectively.

Our implementation follows Tuckerman et al. (Reference Tuckerman, Berne and Martyna1992) (see their Appendix B), where the velocity is first predicted to the half step using the ‘long-range’ forces, followed by an inner loop where the positions are updated with the current velocity and the velocities are updated with the ‘short-range’ accelerations. Thus, the timestepping proceeds according to

where ${\bm a}_{\rm sph}$ indicates the SPH acceleration evaluated from (34) and ${\bm a}_{\rm ext}$ indicates the external forces. The SPH and external accelerations are stored separately to enable this. Δ*t* _{ext} is the minimum of all timesteps relating to sink–gas and external forces [equations (74)–(76)], while Δ*t* _{sph} is the timestep relating to the SPH forces [equations (72), (73), and (288)]. Δ*t* _{ext} is allowed to vary on each substep, so we take as many steps as required such that ∑^{m − 1}_{j}Δ*t* _{ext, j} + Δ*t* _{ext, f} = Δ*t* _{sph}, where Δ*t* _{ext, f} < Δ*t* _{ext, j} is chosen so that the sum will identically equal Δ*t* _{sph}. The number of substeps is *m* ≈ int(Δ*t* _{ext, min}/Δ*t* _{sph, min}) + 1, where the minimum is taken over all particles.

#### 2.3.4. Individual particle timesteps

For simulations of stiff problems with a large range in timestep over the domain, it is more efficient to allow each particle to evolve on its own timestep independently (Bate Reference Bate1995; Springel Reference Springel2005; Saitoh & Makino Reference Saitoh and Makino2010). This violates all of the conservation properties of the Leapfrog integrator [see Makino et al. (Reference Makino, Hut, Kaplan and Saygın2006) for an attempt to solve this], but can speed up the calculation by an order of magnitude or more. We implement this in the usual blockstepped manner by assigning timesteps in factor-of-two decrements from some maximum timestep Δ*t* _{max}, which for convenience is set equal to the time between output files.

We implement a timestep limiter where the timestep for an active particle is constrained to be within a factor of 2 of its neighbours, similar to condition employed by Saitoh & Makino (Reference Saitoh and Makino2009). Additionally, inactive particles will be woken up as required to ensure that their timestep is within a factor of 2 of its neighbours.

The practical side of individual timestepping is described in Appendix A.6.

### 2.4. External forces

#### 2.4.1. Point-mass potential

The simplest external force describes a point mass, *M*, at the origin, which yields gravitational potential and acceleration:

where $r_{a} \equiv \vert {\bm r}_{a} \vert \equiv \sqrt{{\bm r}_{a}\cdot {\bm r}_{a}}$. When this potential is used, we allow for particles within a certain radius, *R* _{acc}, from the origin to be accreted. This allows for a simple treatment of accretion discs where the mass of the disc is assumed to be negligible compared to the mass of the central object. The accreted mass in this case is recorded but not added to the central mass. For more massive discs, or when the accreted mass is significant with respect to the central mass, it is better to model the central star using a sink particle (Section 2.8) where there are mutual gravitational forces between the star and the disc, and any mass accreted is added to the point mass (Section 2.8.2).

#### 2.4.2. Binary potential

We provide the option to model motion in binary systems where the mass of the disc is negligible. In this case, the binary motion is prescribed using

where *M* is the mass ratio in units of the total mass (which is therefore unity). For this potential, *G* and Ω are set to unity in computational units, where Ω is the angular velocity of the binary. Thus, only *M* needs to be specified to fix both *m* _{1} and *m* _{2}. Hence, the binary remains fixed on a circular orbit at *r* = 1. The binary potential is therefore

such that the external acceleration is given by

Again, there is an option to accrete particles that fall within a certain radius from either star (*R* _{acc, 1} or *R* _{acc, 2}, respectively). For most binary accretion disc simulations (e.g. planet migration), it is better to use ‘live’ sink particles to represent the binary so that there is feedback between the binary and the disc (we have used a live binary in all of our simulations to date, e.g. Nixon, King, & Price Reference Nixon, King and Price2013; Facchini, Lodato, & Price Reference Facchini, Lodato and Price2013; Martin et al. Reference Martin, Nixon, Armitage, Lubow and Price2014a, Reference Martin, Nixon, Lubow, Armitage, Price, Doğan and King2014b; Doğan et al. Reference Doğan, Nixon, King and Price2015; Ragusa, Lodato, & Price Reference Ragusa, Lodato and Price2016; Ragusa et al. Reference Ragusa, Dipierro, Lodato, Laibe and Price2017), but the binary potential remains useful under limited circumstances—in particular, when one wishes to turn off the feedback between the disc and the binary.

Given that the binary potential is time-dependent, for efficiency, we compute the position of the binary only once at the start of each timestep, and use these stored positions to compute the accelerations of the SPH particles via (90).

#### 2.4.3. Binary potential with gravitational wave decay

An alternative binary potential including the effects of gravitational wave decay was used by Cerioli, Lodato, & Price (Reference Cerioli, Lodato and Price2016) to study the squeezing of discs during the merger of supermassive black holes. Here the motion of the binary is prescribed according to

where the semi-major axis, *a*, decays according to

The initial separation is *a* _{0}, with τ defined as the time to merger, given by the usual expression (e.g. Lodato et al. Reference Lodato, Nayakshin, King and Pringle2009)

where

The angle θ is defined using

Inserting the expression for *a* and integrating gives (Cerioli et al. Reference Cerioli, Lodato and Price2016)

The positions of the binary, ${\bm r}_1$ and ${\bm r}_2$, can be inserted into (89) to obtain the binary potential, with the acceleration as given in (90). The above can be used as a simple example of a time-dependent external potential.

#### 2.4.4. Galactic potentials

We implement a range of external forces representing various galactic potentials, as used in Pettitt et al. (Reference Pettitt, Dobbs, Acreman and Price2014). These include arm, bar, halo, disc, and spheroidal components. We refer the reader to the paper above for the actual forms of the potentials.

For the non-axisymmetric potentials, a few important parameters that determine the morphology can be changed at run time rather than compile time. These include the pattern speed, arm number, arm pitch angle, and bar axis lengths (where applicable). In the case of non-axisymmetric components, the user should be aware that some will add mass to the system, whereas others simply perturb the galactic disc. These potentials can be used for any galactic system, but the various default scale lengths and masses are chosen to match the Milky Way’s rotation curve (Sofue Reference Sofue2012).

The most basic potential in Phantom is a simple logarithmic potential from Binney & Tremaine (Reference Binney and Tremaine1987), which allows for the reproduction of a purely flat rotation curve with steep decrease at the galactic centre, and approximates the halo, bulge, and disc contributions. Also included is the standard flattened disc potential of Miyamoto–Nagai (Miyamoto & Nagai Reference Miyamoto and Nagai1975) and an exponential profile disc, specifically the form from Khoperskov et al. (Reference Khoperskov, Vasiliev, Sobolev and Khoperskov2013). Several spheroidal components are available, including the potentials of Plummer (Reference Plummer1911), Hernquist (Reference Hernquist1990), and Hubble (Reference Hubble1930). These can be used generally for bulges and halos if given suitable mass and scale lengths. We also include a few halo-specific profiles; the NFW (Navarro, Frenk, & White Reference Navarro, Frenk and White1996), Begeman, Broeils, & Sanders (Reference Begeman, Broeils and Sanders1991), Caldwell & Ostriker (Reference Caldwell and Ostriker1981), and the Allen & Santillan (Reference Allen and Santillan1991) potentials.

The arm potentials include some of the more complicated profiles. The first is the potential of Cox & Gómez (Reference Cox and Gómez2002), which is a relatively straightforward superposition of three sinusoidal-based spiral components to damp the potential ‘troughs’ in the inter-arm minima. The other spiral potential is from Pichardo et al. (Reference Pichardo, Martos, Moreno and Espresate2003), and is more complicated. Here, the arms are constructed from a superposition of oblate spheroids whose loci are placed along a standard logarithmic spiral. As the force from this potential is computationally expensive it is prudent to pre-compute a grid of potential/force and read it at run time. The python code to generate the appropriate grid files is distributed with the code.

Finally, the bar components: We include the bar potentials of Dehnen (Reference Dehnen2000a), Wada & Koda (Reference Wada and Koda2001), the ‘S’ shaped bar of Vogt & Letelier (Reference Vogt and Letelier2011), both biaxial and triaxial versions provided in Long & Murali (Reference Long and Murali1992), and the boxy-bulge bar of Wang et al. (Reference Wang, Zhao, Mao and Rich2012). This final bar contains both a small inner non-axisymmetric bulge and longer bar component, with the forces calculated by use of Hernquist–Ostriker expansion coefficients of the bar density field. Phantom contains the coefficients for several different forms of this bar potential.

#### 2.4.5. Lense–Thirring precession

Lense–Thirring precession (Lense & Thirring Reference Lense and Thirring1918) from a spinning black hole is implemented in a post-Newtonian approximation following Nelson & Papaloizou (Reference Nelson and Papaloizou2000), which has been used in Nixon et al. (Reference Nixon, King, Price and Frank2012b), Nealon, Price, & Nixon (Reference Nealon, Price and Nixon2015), and Nealon et al. (Reference Nealon, Nixon, Price and King2016). In this case, the external acceleration consists of a point-mass potential (Section 2.4.1) and the Lense–Thirring term:

where Φ_{a} is given by (86) and ${\bm v}_a \times {\bm \Omega }_{p,a}$ is the gravitomagnetic acceleration. A dipole approximation is used, yielding

with ${\bm S} = a_{\rm spin} (GM)^{2} {\bm k}/c^{3}$, where ${\bm k}$ is a unit vector in the direction of the black hole spin. When using the Lense–Thirring force, geometric units are assumed such that *G* = *M* = *c* = 1, as described in Section 2.2.3, but with the additional constraints on the unit system from *M* and *c*.

Since in this case the external force depends on velocity, it cannot be implemented directly into Leapfrog. The method we employ to achieve this is simpler than those proposed elsewhere [c.f. attempts by Quinn et al. (Reference Quinn, Perrine, Richardson and Barnes2010) and Rein & Tremaine (Reference Rein and Tremaine2011) to adapt the Leapfrog integrator to Hill’s equations]. Our approach is to split the acceleration into position and velocity-dependent parts, i.e.

The position-dependent part [i.e. $-\nabla \Phi ({\bm r})$] is integrated as normal. The velocity-dependent Lense–Thirring term is added to the predictor step, (66)–(67), as usual, but the corrector step, (69), is written in the form

where ${\bm v}^{n + \frac{1}{2}} \equiv {\bm v}^{n} + \frac{1}{2} \Delta t {\bm a}^{n}$ as in (65). This equation is implicit but the trick is to notice that it can be solved analytically for simple forcesFootnote ^{4}. In the case of Lense–Thirring precession, we have

where $\tilde{\bm v} \equiv {\bm v}^{n + \frac{1}{2}} + \frac{1}{2} \Delta t ({\bm a}_{\rm sph}^{n+1} + {\bm a}_{\rm ext,x}^{n+1})$. We therefore have a matrix equation in the form

where ${\bm R}$ is the 3 × 3 matrix given by

Rearranging (102), ${\bm v}^{n+1}$ is obtained by using

where ${\bm R}^{-1}$ is the inverse of ${\bm R}$, which we invert using the analytic solution.

#### 2.4.6. Generalised Newtonian potential

The generalised Newtonian potential described by Tejeda & Rosswog (Reference Tejeda and Rosswog2013) is implemented, where the acceleration terms are given by

with *R* _{g} ≡ *GM*/*c* ^{3} and $f \equiv \left(1 - 2R_{\rm g}/\vert {\bm r}_a \vert \right)$. See Bonnerot et al. (Reference Bonnerot, Rossi, Lodato and Price2016) for a recent application. This potential reproduces several features of the Schwarzschild (Reference Schwarzschild1916) spacetime, in particular, reproducing the orbital and epicyclic frequencies to better than 7% (Tejeda & Rosswog Reference Tejeda and Rosswog2013). As the acceleration involves velocity-dependent terms, it requires a semi-implicit solution like Lense–Thirring precession. Since the matrix equation is rather involved for this case, the corrector step is iterated using fixed point iterations until the velocity of each particle is converged to a tolerance of 1%.

#### 2.4.7. Poynting–Robertson drag

The radiation drag from a central point-like, gravitating, radiating, and non-rotating object may be applied as an external force. The implementation is intended to be as general as possible. The acceleration of a particle subject to these external forces is

where *v* _{r} is the component of the velocity in the radial direction. The parameter β_{PR} is the ratio of radiation to gravitational forces, supplied by a separate user-written module. Relativistic effects are neglected because these are thought to be less important than radiation forces for low (β_{PR} < 0.01) luminosities, even in accreting neutron star systems where a strong gravitational field is present (e.g., Miller & Lamb Reference Miller and Lamb1993).

The three terms on the right side of (106) correspond, respectively, to gravity (reduced by outward radiation pressure), redshift-related modification to radiation pressure caused by radial motion, and Poynting–Robertson drag against the direction of motion. These three terms can be scaled independently by changing the three parameters *k* _{0}, *k* _{1}, and *k* _{2}, whose default values are unity. Rotation of the central object can be crudely emulated by changing *k* _{2}.

As for Lense–Thirring precession, the ${\bm a}^{n+1}$ term of the Leapfrog integration scheme can be expanded into velocity-dependent and non-velocity-dependent component. We obtain, after some algebra,

where

and

Equation (107) yields a set of simultaneous equations for the three vector components that can be solved analytically. A detailed derivation is given in Worpel (Reference Worpel2015).

#### 2.4.8. Coriolis and centrifugal forces

Under certain circumstances, it is useful to perform calculations in a co-rotating reference frame (e.g. for damping binary stars into equilibrium with each other). The resulting acceleration terms are given by

which are the centrifugal and Coriolis terms, respectively, with ${\bm \Omega }$ the angular rotation vector. The timestepping algorithm is as described above for Lense–Thirring precession, with the velocity-dependent term handled by solving the 3 × 3 matrix in the Leapfrog corrector step.

### 2.5. Driven turbulence

Phantom implements turbulence driving in periodic domains via an Ornstein–Uhlenbeck stochastic driving of the acceleration field, as first suggested by Eswaran & Pope (Reference Eswaran and Pope1988). This is an SPH adaptation of the module used in the grid-based simulations by Schmidt, Hillebrandt, & Niemeyer (Reference Schmidt, Hillebrandt and Niemeyer2006) and Federrath, Klessen, & Schmidt (Reference Federrath, Klessen and Schmidt2008) and many subsequent works. This module was first used in Phantom by Price & Federrath (Reference Price and Federrath2010) to compare the statistics of isothermal, supersonic turbulence between SPH, and grid methods. Subsequent applications have been to the density variance–Mach number relation (Price et al. Reference Price, Federrath and Brunt2011), subsonic turbulence (Price Reference Price2012b), supersonic MHD turbulence (Tricco et al. Reference Tricco, Price and Federrath2016b), and supersonic turbulence in a dust–gas mixture (Tricco et al. Reference Tricco, Price and Laibe2017). Adaptations of this module have also been incorporated into other SPH codes (Bauer & Springel Reference Bauer and Springel2012; Valdarnini Reference Valdarnini2016).

The amplitude and phase of each Fourier mode is initialised by creating a set of six random numbers, *z* _{n}, drawn from a random Gaussian distribution with unit variance. These are generated by the usual Box–Muller transformation (e.g. Press et al. Reference Press, Teukolsky, Vetterling and Flannery1992) by selecting two uniform random deviates *u* _{1}, *u* _{2} ∈ [0, 1] and constructing the amplitude according to

The six Gaussian random numbers are set up according to

where the standard deviation, σ, is set to the square root of the energy per mode divided by the correlation time, $\sigma = \sqrt{E_{\rm m}/t_{\rm decay}}$, where both *E* _{m} and *t* _{decay} are user-specified parameters.

The ‘red noise’ sequence (Uhlenbeck & Ornstein Reference Uhlenbeck and Ornstein1930) is generated for each mode at each timestep according to (Bartosch Reference Bartosch2001)

where *f* = exp(− Δ*t*/*t* _{decay}) is the damping factor. The resulting sequence has zero mean with root-mean-square equal to the variance. The power spectrum in the time domain can vary from white noise [*P*(*f*) constant] to ‘brown noise’ [*P*(*f*) = 1/*f* ^{2}].

The amplitudes and phases of each mode are constructed by splitting ${\bm x}_{n}$ into two vectors, ${\bm \Phi }_{a}$ and ${\bm \Phi }_{b}$ of length 3, employed to construct divergence- and curl-free fields according to

where ${\bm k} = [k_{x}, k_{y}, k_{z}]$ is the mode frequency. The parameter *w* ∈ [0, 1] is the ‘solenoidal weight’, specifying whether the driving should be purely solenoidal (*w* = 1) or purely compressive (*w* = 0) (see Federrath et al. Reference Federrath, Klessen and Schmidt2008, Reference Federrath, Roman-Duval, Klessen, Schmidt and Mac Low2010a).

The spectral form of the driving is defined in Fourier space, with options for three possible spectral forms

where $k = \sqrt{k_{x}^{2} + k_{y}^{2} + k_{z}^{2}}$ is the wavenumber, with non-zero amplitudes defined only for wavenumbers where *k* _{min} ⩽ *k* ⩽ *k* _{max}, and *a* _{min} is the amplitude of the modes at *k* _{min} and *k* _{max} in the parabolic case (we use *a* _{min} = 0 in the code). The frequency grid is defined using frequencies from *k* _{x} = *n* _{x}2π/*L* _{x} in the *x* direction, where *n* _{x} ∈ [0, 20] is an integer and *L* _{x} is the box size in the *x*-direction, while *k* _{y} = *n* _{y}2π/*L* _{y} and *k* _{z} = *n* _{z}2π/*L* _{z} with *n* _{y} ∈ [0, 8] and *n* _{z} ∈ [0, 8]. We then set up four modes for each combination of *n* _{x}, *n* _{y}, and *n* _{z}, corresponding to [*k* _{x}, *k* _{y}, *k* _{z}], [*k* _{x}, −*k* _{y}, *k* _{z}], [*k* _{x}, *k* _{y}, −*k* _{z}], and [*k* _{x}, −*k* _{y}, −*k* _{z}]. That is, we effectively sum from [− (*N* − 1)/2, (*N* − 1)/2] in the *k* _{y} and *k* _{z} directions in the discrete Fourier transform, where *N* = max(*n* _{x}) is the number of frequencies. The default values for *k* _{min} and *k* _{max} are 2π and 6π, respectively, corresponding to large-scale driving of only the first few Fourier modes, so with default settings there are 112 non-zero Fourier modes. The maximum number of modes, defining the array sizes needed to store the stirring information, is currently set to 1,000.

We apply the forcing to the particles by computing the discrete Fourier transform over the stirring modes directly, i.e.

where the factor *f* _{sol} is defined from the solenoidal weight, *w*, according to

such that the rms acceleration is the same irrespective of the value of *w*. We default to purely solenoidal forcing (*w* = 1), with the factor *f* _{sol} thus equal to $\sqrt{3/2}$ by default. For individual timesteps, we update the driving force only when a particle is active.

To aid reproducibility, it is often desirable to pre-generate the entire driving sequence prior to performing a calculation, which can then be written to a file and read back at runtime. This was the procedure used in Price & Federrath (Reference Price and Federrath2010), Tricco et al. (Reference Tricco, Price and Federrath2016b), and Tricco et al. (Reference Tricco, Price and Laibe2017).

### 2.6. Accretion disc viscosity

Accretion disc viscosity is implemented in Phantom via two different approaches, as described by Lodato & Price (Reference Lodato and Price2010).

#### 2.6.1. Disc viscosity using the shock viscosity term

The default approach is to adapt the shock viscosity term to represent a Shakura & Sunyaev (Reference Shakura and Sunyaev1973) α-viscosity, as originally proposed by Artymowicz & Lubow (Reference Artymowicz and Lubow1994) and Murray (Reference Murray1996). The key is to note that (39) and (40) represent a Navier–Stokes viscosity term with a fixed ratio between the bulk and shear viscosity terms (e.g. Murray Reference Murray1996; Jubelgas, Springel, & Dolag Reference Jubelgas, Springel and Dolag2004; Lodato & Price Reference Lodato and Price2010; Price Reference Price2012b; Meru & Bate Reference Meru and Bate2012). In particular, it can be shown (e.g. Español & Revenga Reference Español and Revenga2003) that

where $\overline{\rho }_{ab}$ is some appropriate average of the density. This enables the artificial viscosity term, (39), to be translated into the equivalent Navier–Stokes terms. In order for the artificial viscosity to represent a disc viscosity, we make the following modifications (Lodato & Price Reference Lodato and Price2010):

1. The viscosity term is applied for both approaching and receding particles.

2. The speed

*v*_{sig}is set equal to*c*_{s}.3. A constant α

^{AV}is adopted, turning off shock detection switches (Section 2.2.9).4. The viscosity term is multiplied by a factor

*h*/|*r*_{ab}|.

The net result is that (40) becomes

With the above modifications, the shear and bulk coefficients can be translated using (119) to give (e.g. Monaghan Reference Monaghan2005; Lodato & Price Reference Lodato and Price2010; Meru & Bate Reference Meru and Bate2012)

The Shakura–Sunyaev prescription is

where *H* is the scale height. This implies that α_{SS} may be determined from α_{AV} using

where 〈*h*〉 is the mean smoothing length on particles in a cylindrical ring at a given radius.

In practice, this means that one must uniformly resolve the scale height in order to obtain a constant α_{SS} in the disc. We have achieved this in simulations to date by choosing the initial surface density profile and the power-law index of the temperature profile (when using a locally isothermal EOS) to ensure that this is the case (Lodato & Pringle Reference Lodato and Pringle2007). Confirmation that the scaling provided by (124) is correct is shown in Figure 4 of Lodato & Price (Reference Lodato and Price2010) and is checked automatically in the Phantom test suite.

In the original implementation (Lodato & Price Reference Lodato and Price2010), we also set the β^{AV} to zero, but this is dangerous if the disc dynamics are complex as there is nothing to prevent particle penetration (see Section 2.2.7). Hence, in the current version of the code, β^{AV} = 2 by default even if disc viscosity is set, but is only applied to approaching particles (c.f. 120). Applying any component of viscosity to only approaching particles can affect the sign of the precession induced in warped discs (Lodato & Pringle Reference Lodato and Pringle2007), but in general retaining the β^{AV} term is safer with no noticeable effect on the overall dissipation due to the second-order dependence of this term on resolution.

Using α^{AV} to set the disc viscosity has two useful consequences. First, it forces one to consider whether or not the scale height, *H*, is resolved. Second, knowing the value of α^{AV} is helpful, as α^{AV} ≈ 0.1 represents the lower bound below which a physical viscosity is not resolved in SPH (that is, viscosities smaller than this produce disc spreading independent of the value of α^{AV}, see Bate Reference Bate1995; Meru & Bate Reference Meru and Bate2012), while α^{AV} > 1 constrains the timestep (Section 2.3.2).

#### 2.6.2. Disc viscosity using the Navier–Stokes viscosity terms

An alternative approach is to compute viscous terms directly from the Navier–Stokes equation. Details of how the Navier–Stokes terms are represented are given below (Section 2.7), but for disc viscosity a method for determining the kinematic viscosity is needed, which in turn requires specifying the scale height as a function of radius. We use

where we assume Keplerian rotation $\Omega = \sqrt{GM/R^{3}}$ and *c* _{s} is obtained for a given particle from the EOS (which for consistency must be either isothermal or locally isothermal). It is important to note that this restricts the application of this approach only to discs where *R* can be meaningfully defined, excluding, for example, discs around binary stars.

The shear viscosity is then set using

where α_{SS} is a pre-defined/input parameter. The timestep is constrained using *C* _{visc}*h* ^{2}/ν as described in Section 2.7. The advantage to this approach is that the shear viscosity is set directly and does not depend on the smoothing length. However, as found by Lodato & Price (Reference Lodato and Price2010), it remains necessary to apply some bulk viscosity to capture shocks and prevent particle penetration of the disc midplane, so one should apply the shock viscosity as usual. Using a shock-detection switch (Section 2.2.9) means that this is usually not problematic. This formulation of viscosity was used in Facchini et al. (Reference Facchini, Lodato and Price2013).

### 2.7. Navier–Stokes viscosity

Physical viscosity is implemented as described in Lodato & Price (Reference Lodato and Price2010). Here, (23) and (24) are replaced by the compressible Navier–Stokes equations, i.e.

with the stress tensor given by

where δ^{ij} is the Kronecker delta, and ζ and η are the bulk and shear viscosity coefficients, related to the volume and kinematic shear viscosity coefficients by ζ_{v} ≡ ζ/ρ and ν ≡ η/ρ.

#### 2.7.1. Physical viscosity using two first derivatives

As there is no clear consensus on the best way to implement physical viscosity in SPH, Phantom currently contains two implementations. The simplest is to use two first derivatives, which is essentially that proposed by Flebbe et al. (Reference Flebbe, Muenzel, Herold, Riffert and Ruder1994), Watkins et al. (Reference Watkins, Bhattal, Francis, Turner and Whitworth1996), and Sijacki & Springel (Reference Sijacki and Springel2006). In this case, (127) is discretised in the standard manner using

where the velocity gradients are computed during the density loop using

Importantly, the differenced SPH operator is used in (131), whereas (130) uses the symmetric gradient operator. The use of conjugate operatorsFootnote ^{5} is a common requirement in SPH in order to guarantee energy conservation and a positive definite entropy increase from dissipative terms (e.g. Price Reference Price2010; Tricco & Price Reference Tricco and Price2012). Total energy conservation means that

This implies a contribution to the thermal energy equation given by

which can be seen to reduce to (24) in the inviscid case (*S ^{ij}*

_{NS}=

*P*δ

^{ij}), but in general is an SPH expression for

Using *S ^{ij}*

_{NS}=

*S*

_{NS}

^{ji}, we have

which, using (129), gives

By the square in the last term, we mean the tensor summation ∑_{j}∑_{i}*T* _{ij}*T* _{ij}, where *T _{ij}* ≡ ∂

*v*/∂

^{i}_{a}*x*+ ∂

^{j}_{a}*v*

_{a}^{j}/∂

*x*. The heating term is therefore positive definite provided that the velocity gradients and divergence are computed using the difference operator (131), both in (136) and when computing the stress tensor (129).

^{i}_{a}The main disadvantage of the first derivatives approach is that it requires storing the strain tensor for each particle, i.e. six additional quantities when taking account of symmetries.

#### 2.7.2. Physical viscosity with direct second derivatives

The second approach is to use SPH second derivative operators directly. Here we use modified versions of the identities given by Español & Revenga (Reference Español and Revenga2003) (see also Monaghan Reference Monaghan2005; Price Reference Price2012a), namely

where *G* _{ab} ≡ −2*F* _{ab}/|*r* _{ab}|, i.e. the scalar part of the kernel gradient divided by the particle separation, which can be thought of as equivalent to defining a new ‘second derivative kernel’ (Brookshaw Reference Brookshaw1985, Reference Brookshaw1994; Price Reference Price2012a; Price & Laibe Reference Price and Laibe2015a).

From the compressible Navier–Stokes equations, (127) with (129), the coefficients in these two terms are

so that we can simply use

where

The corresponding heating terms in the thermal energy equation are given by

This is the default formulation of Navier–Stokes viscosity in the code since it does not require additional storage. In practice, we have found little difference between the two formulations of physical viscosity, but this would benefit from a detailed study. In general one might expect the two first derivatives formulation to offer a less noisy estimate at the cost of additional storage. However, direct second derivatives are the method used in ‘Smoothed Dissipative Particle Dynamics’ (Español & Revenga Reference Español and Revenga2003).

#### 2.7.3. Timestep constraint

Both approaches to physical viscosity use explicit timestepping, and therefore imply a constraint on the timestep given by

where *C* _{visc} = 0.25 by default (Brookshaw Reference Brookshaw1994). When physical viscosity is turned on, this constraint is included with other timestep constraints according to (77).

#### 2.7.4. Physical viscosity and the tensile instability

Caution is required in the use of physical viscosity at high Mach number, since negative stress can lead to the tensile instability (Morris Reference Morris1996b; Monaghan Reference Monaghan2000; Gray, Monaghan, & Swift Reference Gray, Monaghan and Swift2001). For subsonic applications, this is usually not a problem since the strain tensor and velocity divergence are small compared to the pressure. In the current code, we simply emit a warning if physical viscosity leads to negative stresses during the calculation, but this would benefit from a detailed study.

#### 2.7.5. Physical viscosity and angular momentum conservation

Neither method for physical viscosity exactly conserves angular momentum because the force is no longer directed along the line of sight joining the particles. However, the error is usually small (see discussion in Bonet & Lok Reference Bonet and Lok1999, Section 5 of Price & Monaghan Reference Price and Monaghan2004b or Hu & Adams Reference Hu and Adams2006). Recently, Müller, Fedosov, & Gompper (Reference Müller, Fedosov and Gompper2015) have proposed an algorithm for physical viscosity in SPH that explicitly conserves angular momentum by tracking particle spin, which may be worth investigating.

### 2.8. Sink particles

Sink particles were introduced into SPH by Bate, Bonnell, & Price (Reference Bate, Bonnell and Price1995) in order to follow star formation simulations beyond the point of fragmentation. In Phantom, these are treated separately to the SPH particles, and interact with other particles, including other sink particles, only via gravity. The differences with other point-mass particles implemented in the code (e.g. dust, stars, and dark matter) are that (i) the gravitational interaction is computed using a direct *N* ^{2} summation which is *not* softened by default (i.e., the *N*-body algorithm is collisional); (ii) they are allowed to accrete gas; and (iii) they store the accreted angular momentum and other extended properties, such as the accreted mass. Sink particles are evolved in time using the RESPA algorithm (Section 2.3.3), which is second-order accurate, symplectic, and allows sink particles to evolve on shorter timesteps compared to SPH particles.

#### 2.8.1. Sink particle accelerations

The equations of motion for a given sink particle, *i*, are

where ϕ′_{ab} is the softening kernel (Section 2.12.2), *N* _{part} is the total number of gas particles, and *N* _{sink} is the total number of sink particles. The sink–gas softening length, ε_{ib}, is defined as the maximum of the (fixed) softening length defined for the sink particles, ε, and the softening length of the gas particle, ε_{b}. That is, ε_{ib} ≡ max(ε, ε_{b}). SPH particles receive a corresponding acceleration

Softening of sink–gas interactions is not applied if the softening length for sink particles is set to zero, in which case the sink–gas accelerations reduce simply to

This is the default behaviour when sink particles are used in the code. Softening of sink–gas interactions is useful to model a point-mass particle that does not accrete gas (e.g. by setting the accretion radius to zero). For example, we used a softened sink particle to simulate the core of the red giant in Iaconi et al. (Reference Iaconi, Reichardt, Staff, De Marco, Passy, Price, Wurster and Herwig2017). The sink–sink interaction is unsoftened by default (ε = 0), giving the usual

Caution is required when integrating tight binary or multiple systems when ε = 0 to ensure that the timestep conditions (Section 2.3.2) are strict enough.

#### 2.8.2. Accretion onto sink particles

Accretion of gas particles onto a sink particle occurs when a gas particle passes a series of accretion checks within the accretion radius *r* _{acc} of a sink particle (set in the initial conditions or when the sink particle is created, see Section 2.8.4). First, a gas particle is indiscriminately accreted without undergoing any additional checks if it falls within *f* _{acc}*r* _{acc}, where 0 ⩽ *f* _{acc} ⩽ 1 (default *f* _{acc} = 0.8). In the boundary region *f* _{acc}*r* _{acc} < *r* < *r* _{acc}, a gas particle undergoes accretion if

1. $\vert {\bm L}_{ai} \vert < \vert {\bm L}_{\rm acc} \vert$, that is, its specific angular momentum is less than that of a Keplerian orbit at

*r*_{acc},2. $e = \frac{v_{ai}^2}{2} - \frac{GM_i}{r_{ai}} < 0$, i.e., it is gravitationally bound to the sink particle, and

3.

*e*for this gas–sink pair is smaller than*e*with any other sink particle, that is, out of all sink particles, the gas particle is most bound to this one.

In the above conditions, ${\bm L}_{ai}$ is the relative specific angular momentum of the gas–sink pair, *a* − *i*, defined by

while $\vert {\bm L}_{\rm acc} \vert = r_{\rm acc}^2 \Omega _{\rm acc}$ is the angular momentum at *r* _{acc}, where $\Omega _{\rm acc} = \sqrt{GM_i / r_{ai}^{3}}$ is the Keplerian angular speed at *r* _{acc}, *v* _{ai}, and *r* _{ai} are the relative velocity and position, respectively, and *M* _{i} is the mass of the sink particle.

When a particle, *a*, passes the accretion checks, then the mass, position, velocity, acceleration, and spin angular momentum of the sink particle are updated according to

This ensures that mass, linear momentum, and angular momentum (but not energy) are conserved by the accretion process. The accreted mass as well as the total mass for each sink particle is stored to avoid problems with round-off error in the case where the particle masses are much smaller than the sink mass. Accreted particles are tagged by setting their smoothing lengths negative. Those particles with *h* ⩽ 0 are subsequently excluded when the *k*d-tree is built.

#### 2.8.3. Sink particle boundary conditions

No special sink particle boundary conditions are implemented in Phantom at present. More advanced boundary conditions to regularise the density, pressure, and angular momentum near a sink have been proposed by Bate et al. (Reference Bate, Bonnell and Price1995) and used in Bate & Bonnell (Reference Bate and Bonnell1997), and proposed again more recently by Hubber, Walch, & Whitworth (Reference Hubber, Walch and Whitworth2013b). While these conditions help to regularise the flow near the sink particle, they can also cause problems—particularly the angular momentum boundary condition if the disc near the sink particle has complicated structure such as spiral density waves (Bate 2014, private communication). Often it is more cost effective to simply reduce the accretion radius of the sink. This may change in future code versions.

#### 2.8.4. Dynamic sink particle creation

As described in Bate et al. (Reference Bate, Bonnell and Price1995), it is also possible to create sink particles on-the-fly provided certain physical conditions are met and self-gravity is turned on (Section 2.12). The primary conditions required for sink particle formation are that the density of a given particle exceeds some threshold physical density somewhere in the domain, and that this density peak occurs more than a critical distance *r* _{crit} from an existing sink. Once these conditions are met on a particular particle, *a*, the creation of a new sink particle occurs by passing the following conditions (Bate et al. Reference Bate, Bonnell and Price1995):

1. The particle is a gas particle.

2. $\nabla \cdot {\bm v}_{a} \le 0$, that is, gas surrounding the particle is at rest or collapsing.

3.

*h*_{a}<*r*_{acc}/2, i.e., the smoothing length of the particle is less than half of the accretion radius.4. All neighbours within

*r*_{acc}are currently active.5. The ratio of thermal to gravitational energy of particles within

*r*_{acc}, α_{J}, satisfies α_{J}⩽ 1/2.6. α

_{J}+ β_{rot}⩽ 1, where β_{rot}= |*e*_{rot}|/|*e*_{grav}| is the ratio of rotational energy to the magnitude of the gravitational energy for particles within*r*_{acc}.7.

*e*_{tot}< 0, that is, the total energy of particles within*r*_{acc}is negative (i.e. the clump is gravitationally bound).8. The particle is at a local potential minimum, i.e. Φ is less than Φ computed on all other particles within

*r*_{acc}(Federrath et al. Reference Federrath, Banerjee, Clark and Klessen2010b).

A new sink particle is created at the position of particle *a* if these checks are passed, and immediately the particles within *r* _{acc} are accreted by calling the routine described in Section 2.8.2. The checks above are the same as those in Bate et al. (Reference Bate, Bonnell and Price1995), with the additional check from Federrath et al. (Reference Federrath, Banerjee, Clark and Klessen2010b) to ensure that sink particles are only created in a local minimum of the gravitational potential.

The various energies used to evaluate the criteria above are computed according to

where ${\bm L}_{ab} \equiv ({\bm r}_{a} - {\bm r}_{b}) \times ({\bm v}_{a} - {\bm v}_{b})$ is the specific angular momentum between a pair of particles, and ϕ is the gravitational softening kernel (defined in Section 2.12), which has units of inverse length. Adding the contribution from *all* pairs, *b* − *c*, within the clump is required to obtain the total potential of the clump.

#### 2.8.5. Sink particle timesteps

Sink particles are integrated together with a global, but adaptive, timestep, following the inner loop of the RESPA algorithm given in (80)–(83) corresponding to a second-order Leapfrog integration. The timestep is controlled by the minimum of the sink–gas timestep, (75), and a sink–sink timestep (Dehnen & Read Reference Dehnen and Read2011)

where the potential and gradient include other sink particles, plus any external potentials applied to sink particles except the sink–gas potential. We set $\eta _\Phi = 0.05$ by default, resulting in ~300–500 steps per orbit for a binary orbit with the default *C* _{force} = 0.25 (see Section 5.5.1).

More accurate integrators such as the fourth-order Hermite scheme (Makino & Aarseth Reference Makino and Aarseth1992) or the fourth-order symplectic schemes proposed by Omelyan, Mryglod, & Folk (Reference Omelyan, Mryglod and Folk2002) or Chin & Chen (Reference Chin and Chen2005) are not yet implemented in Phantom, but it would be a worthwhile effort to incorporate one of these in a future code version. See Hubber et al. (Reference Hubber, Allison, Smith and Goodwin2013a) for a recent implementation of a fourth-order Hermite scheme for sink particles in SPH.

### 2.9. Stellar physics

A tabulated EOS can be used to take account of the departure from an ideal gas, for example, due to changes in ionisation or molecular dissociation and recombination. This tabulated EOS in Phantom is adapted from the log*P* _{gas} − *T* EOS tables provided with the open source package Modules for Experiments in Stellar Astrophysics mesa (Paxton et al. Reference Paxton, Bildsten, Dotter, Herwig, Lesaffre and Timmes2011). Details of the data, originally compiled from blends of equations of state from Saumon, Chabrier, & van Horn (Reference Saumon, Chabrier and van Horn1995) (SCVH), Timmes & Swesty (Reference Timmes and Swesty2000), Rogers & Nayfonov (Reference Rogers and Nayfonov2002, also the 2005 update), Potekhin & Chabrier (Reference Potekhin and Chabrier2010) and for an ideal gas, are outlined by Paxton et al. (Reference Paxton, Bildsten, Dotter, Herwig, Lesaffre and Timmes2011).

In our implementation (adapted from original routines for the Music code; Goffrey et al. Reference Goffrey2017), we compute the pressure and other required EOS variables for a particular composition by interpolation between sets of tables for different hydrogen abundance *X* = 0.0, 0.2, 0.4, 0.6, 0.8 and metallicity *Z* = 0.0, 0.02, 0.04. Pressure is calculated with bicubic interpolation, and Γ_{1} ≡ ∂ln*P*/∂lnρ|_{s} with bilinear interpolation, in log*u* and log*V* ≡ logρ − 0.7log*u* + 20. The tables are currently valid in the ranges 10.5 ⩽ log*u* ⩽ 17.5 and 0.0 ⩽ log*V* ⩽ 14.0. Values requested outside the tables are currently computed by linear extrapolation. This triggers a warning to the user.

We have not tested the thermodynamic consistency of our interpolation scheme from the tables (Timmes & Arnett Reference Timmes and Arnett1999).

### 2.10. Magnetohydrodynamics

Phantom implements the smoothed particle magnetohydrodynamics (SPMHD) algorithm described in Price (Reference Price2012a) and Tricco & Price (Reference Tricco and Price2012, Reference Tricco and Price2013), based on the original work by Phillips & Monaghan (Reference Phillips and Monaghan1985) and Price & Monaghan (Reference Price and Monaghan2004a, Reference Price and Monaghan2004b, Reference Price and Monaghan2005). Phantom was previously used to test a vector potential formulation (Price Reference Price2010), but this algorithm has been subsequently removed from the code due to its poor performance (see Price Reference Price2010).

The important difference between Phantom and the gadget implementation of SPMHD (Dolag & Stasyszyn Reference Dolag and Stasyszyn2009; Bürzle et al. Reference Bürzle, Clark, Stasyszyn, Greif, Dolag, Klessen and Nielaba2011a, Reference Bürzle, Clark, Stasyszyn, Dolag and Klessen2011b), which also implements the core algorithms from Price & Monaghan (Reference Price and Monaghan2004a, Reference Price and Monaghan2004b, Reference Price and Monaghan2005), is our use of the divergence-cleaning algorithm from Tricco & Price (Reference Tricco and Price2012, Reference Tricco and Price2013) and Tricco, Price, & Bate (Reference Tricco, Price and Bate2016a). This is vital for preserving the divergence-free (no monopoles) condition on the magnetic field.

For recent applications of Phantom to MHD problems, see e.g. Tricco et al. (Reference Tricco, Price and Federrath2016b), Dobbs et al. (Reference Dobbs, Price, Pettitt, Bate and Tricco2016), Bonnerot et al. (Reference Bonnerot, Price, Lodato and Rossi2017), Forgan, Price, & Bonnell (Reference Forgan, Price and Bonnell2017), and Wurster et al. (Reference Wurster, Price and Bate2016, Reference Wurster, Price and Bate2017).

#### 2.10.1. Equations of magnetohydrodynamics

Phantom solves the equations of MHD in the form

where ${\bm B}$ is the magnetic field, ψ is a scalar used to control the divergence error in the magnetic field (see Section 2.10.8), and $\mathcal {D}_{\rm diss}$ represents magnetic dissipation terms (Sections 2.10.5 and 2.11). The Maxwell stress tensor, *M* _{ij}, is given by

where δ^{ij} is the Kronecker delta and μ_{0} is the permeability of free space. A source term related to the numerically induced divergence of the magnetic field, given by

is necessary to prevent the tensile instability in SPMHD (Phillips & Monaghan Reference Phillips and Monaghan1985; Monaghan Reference Monaghan2000; Børve, Omang, & Trulsen Reference Børve, Omang and Trulsen2001; Price Reference Price2012a). With this source term, the equation set for ideal MHD in the absence of the divergence cleaning field, ψ, is formally the same as in the Powell et al. (Reference Powell, Roe, Linde, Gombosi and de Zeeuw1999) eight-wave scheme (Price Reference Price2012a), meaning that the divergence errors in the magnetic field are advected by the flow, but not dissipated, unless cleaning is used.

#### 2.10.2. Discrete equations

The discrete version of (165) follows the same procedure as for physical viscosity (Section 2.7), i.e.

where *M ^{ij}_{a}* is defined according to (169),

*f*

_{divB}is a correction term for stability (discussed below), and accelerations due to external forces are as described in Section 2.4.

Equations (167) and (168) are discretised according to (Price & Monaghan Reference Price and Monaghan2005; Tricco & Price Reference Tricco and Price2012; Tricco et al. Reference Tricco, Price and Bate2016a)

The first term in (173) uses the divergence of the magnetic field discretised according to

which is therefore the operator we use when measuring the divergence error (c.f. Tricco & Price Reference Tricco and Price2012).

#### 2.10.3. Code units

An additional unit is required when magnetic fields are included to describe the unit of magnetic field. We adopt code units such that μ_{0} = 1, as is common practice. The unit scalings for the magnetic field can be determined from the definition of the Alfvén speed,

Since the Alfvén speed has dimensions of length per unit time, this implies a unit for the magnetic field, *u* _{mag}, given by

Converting the magnetic field in the code to physical units therefore only requires specifying μ_{0} in the relevant unit system. In particular, it avoids the differences between SI and cgs units in how the charge unit is defined, since μ_{0} is dimensionless and equal to 4π in cgs units but has dimensions that involve charge in SI units.

#### 2.10.4. Tensile instability correction

The correction term *f* _{divB} is necessary to avoid the tensile instability—a numerical instability where particles attract each other along field lines—in the regime where the magnetic pressure exceeds the gas pressure, that is, when plasma $\beta \equiv P / \frac{1}{2} B^2 < 1$ (Phillips & Monaghan Reference Phillips and Monaghan1985). The correction term is computed using the symmetric divergence operator (Børve et al. Reference Børve, Omang and Trulsen2001; Price Reference Price2012a; Tricco & Price Reference Tricco and Price2012)

Since this term violates momentum conservation to the extent that the $\nabla \cdot {\bm B}$ term is non-zero, several authors have proposed ways to minimise its effect. Børve et al. (Reference Børve, Omang and Trulsen2004) showed that stability could be achieved with $\hat{B}^i = \frac{1}{2} B^i$ and also proposed a scheme for scaling this term to zero for β > 1. Barnes, Kawata, & Wu (Reference Barnes, Kawata and Wu2012) similarly advocated using a factor of $\frac{1}{2}$ in this term. However, Tricco & Price (Reference Tricco and Price2012) showed that this could lead to problematic effects (their Figure 12). In Phantom, we use

to provide numerical stability in the strong field regime while maintaining conservation of momentum when β > 10. This also helps to reduce errors in the MHD wave speed caused by the correction term (Iwasaki Reference Iwasaki2015).

#### 2.10.5. Shock capturing

The shock capturing term in the momentum equation for MHD is identical to (39) and (40) except that the signal speed becomes (Price & Monaghan Reference Price and Monaghan2004a, Reference Price and Monaghan2005; Price Reference Price2012a)

where

is the fast magnetosonic speed. Apart from this, the major difference to the hydrodynamic case is the addition of an artificial resistivity term to capture shocks and discontinuities in the magnetic field (i.e. current sheets). This is given by

where *v ^{B}*

_{sig, a}is an appropriate signal speed (see below) multiplied by a dimensionless coefficient, α

^{B}. The corresponding contribution to the thermal energy from the resistivity term in (42) is given by

As with the artificial viscosity, (181) and (182) are the SPH representation of a physical resistivity term, $\eta \nabla ^2 {\bm B}$, but with a coefficient that is proportional to resolution (Price & Monaghan Reference Price and Monaghan2004a). The resistive dissipation rate from the shock capturing term is given by

where |*r* _{ab}|∝*h*.

#### 2.10.6. Switch to reduce resistivity

Phantom previously used the method proposed by Tricco & Price (Reference Tricco and Price2013) to reduce the dissipation in the magnetic field away from shocks and discontinuities. The signal velocity, *v ^{B}*

_{sig}, was set equal to the magnetosonic speed [Equation (180)] multiplied by the dimensionless coefficient α

_{B}, which was set according to

where α^{B}_{max} = 1.0 by default and $\vert \nabla {\bm B}_{a} \vert$ is the two-norm of the gradient tensor, i.e. the root mean square of all nine components of this tensor. Unlike the viscous dissipation, this is set based on the instantaneous values of *h* and ${\bm B}$ and there is no source/decay equation involved, as Tricco & Price (Reference Tricco and Price2013) found it to be unnecessary. Since α^{B} is proportional to resolution, from (183), we see that this results in dissipation that is effectively second order (∝*h* ^{2}). When individual particle timesteps were used, inactive particles retained their value of α^{B} from the last timestep they were active.

More recently, we have found that a better approach, similar to that used for artificial conductivity, is to simply set α^{B} = 1 for all particles and set the signal speed for artificial resistivity according to

We find that this produces better results on all of our tests (Section 5.6), in particular, producing zero numerical dissipation on the current loop advection test (Section 5.6.5). As with the Tricco & Price (Reference Tricco and Price2013) switch, it gives second-order dissipation in the magnetic field (demonstrated in Section 5.6.1, Figure 26). This is now the default treatment for artificial resistivity in Phantom.

#### 2.10.7. Conservation properties

The total energy when using MHD is given by

Hence, total energy conservation, in the absence of divergence cleaning, corresponds to

Neglecting the *f* _{divB} correction term for the moment, substituting (171), (35), and (172) into (187) with the ideal MHD and shock capturing terms included demonstrates that the total energy is exactly conserved, using the same argument as the one given in Section 2.2.6 (detailed workings can be found in Price & Monaghan Reference Price and Monaghan2004b). The total linear momentum is also exactly conserved following a similar argument as in Section 2.2.11. However, the presence of the *f* _{divB} correction term, though necessary for numerical stability, violates the conservation of both momentum and energy in the strong field regime (in the weak field regime, it is switched off and conservation is preserved). The severity of this non-conservation is related to the degree in which divergence errors are present in the magnetic field, hence inadequate divergence control (see below) usually manifests as a loss of momentum conservation in the code (see Tricco & Price Reference Tricco and Price2012, for details).

#### 2.10.8. Divergence cleaning

We adopt the ‘constrained’ hyperbolic/parabolic divergence cleaning algorithm described by Tricco & Price (Reference Tricco and Price2012) and Tricco et al. (Reference Tricco, Price and Bate2016a) to preserve the divergence-free condition on the magnetic field. This formulation addresses a number of issues with earlier formulations by Dedner et al. (Reference Dedner, Kemm, Kröner, Munz, Schnitzer and Wesenberg2002) and Price & Monaghan (Reference Price and Monaghan2005).

The main idea of the scheme is to propagate divergence errors according to a damped wave equation (Dedner et al. Reference Dedner, Kemm, Kröner, Munz, Schnitzer and Wesenberg2002; Price & Monaghan Reference Price and Monaghan2005). This is facilitated by introducing a new scalar field, ψ, which is coupled to the magnetic field in (167) and evolved according to (168).

Tricco et al. (Reference Tricco, Price and Bate2016a) generalised the method of Dedner et al. (Reference Dedner, Kemm, Kröner, Munz, Schnitzer and Wesenberg2002) to include the case where the hyperbolic wave speed, *c* _{h}, varies in time and space. This is the approach we use in Phantom. The resulting ‘generalised wave equation’ may be derived by combining the relevant term in (167) with (168) to give (Tricco et al. Reference Tricco, Price and Bate2016a)

When *c* _{h}, ρ, τ_{c}, and the fluid velocity are constant, this reduces to the usual damped wave equation in the form

The same equation holds for the evolution of ${\nabla \cdot {\bm B}}$ itself, i.e.

from which it is clear that *c* _{h} represents the speed at which divergence errors are propagated and τ_{c} is the decay timescale over which divergence errors are removed.

Tricco & Price (Reference Tricco and Price2012) formulated a ‘constrained’ SPMHD implementation of hyperbolic/parabolic cleaning which guarantees numerical stability of the cleaning. The constraint imposed by Tricco & Price (Reference Tricco and Price2012) is that, in the absence of damping, any energy removed from the magnetic field during cleaning must be conserved by the scalar field, ψ. This enforces particular choices of numerical operators for $\nabla \cdot {\bm B}$ and ∇ψ in (172) and (173), respectively, in particular that they form a conjugate pair of difference and symmetric derivative operators. This guarantees that the change of magnetic energy is negative definite in the presence of the parabolic term (see below).

In Phantom, we set the cleaning speed, *c* _{h}, equal to the fast magnetosonic speed [Equation (180)] so that its timestep constraint is satisfied already by (72), as recommended by Tricco & Price (Reference Tricco and Price2013). The decay timescale is set according to

where the dimensionless factor σ_{c} sets the ratio of parabolic to hyperbolic cleaning. This is set to σ_{c} = 1.0 by default, which was empirically determined by Tricco & Price (Reference Tricco and Price2012) to provide optimal reduction of divergence errors in three dimensions.

The divergence cleaning dissipates energy from the magnetic field at a rate given by (Tricco & Price Reference Tricco and Price2012)

In general, this is so small compared to other dissipation terms (e.g. resistivity for shock capturing) that it is not worth monitoring (Tricco et al. Reference Tricco, Price and Bate2016a). This energy is not added as heat, but simply removed from the calculation.

#### 2.10.9. Monitoring of divergence errors and over-cleaning

The divergence cleaning algorithm is guaranteed to either conserve or dissipate magnetic energy, and cleans divergence errors to a sufficient degree for most applications. However, the onus is on the user to ensure that divergence errors are not affecting simulation results. This may be monitored by the dimensionless quantity

The maximum and mean values of this quantity should be used to check the fidelity of simulations that include magnetic fields. A good rule-of-thumb is that the mean should remain ≲ 10^{−2} for the simulation to remain qualitatively unaffected by divergence errors.

The cleaning wave speed can be arbitrarily increased to improve the effectiveness of the divergence cleaning according to

where *f* _{clean} is an ‘over-cleaning’ factor (by default, *f* _{clean} = 1, i.e. no ‘over-cleaning’). Tricco et al. (Reference Tricco, Price and Bate2016a) showed that increasing *f* _{clean} leads to further reduction in divergence errors, without affecting the quality of obtained results, but with an accompanying computational expense associated with a reduction in the timestep size.

### 2.11. Non-ideal magnetohydrodynamics

Phantom implements non-ideal MHD including terms for Ohmic resistivity, ambipolar (ion-neutral) diffusion and the Hall effect. Algorithms and tests are taken from Wurster, Price, & Ayliffe (Reference Wurster, Price and Ayliffe2014) and Wurster, Price, & Bate (Reference Wurster, Price and Bate2016). See Wurster et al. (Reference Wurster, Price and Bate2016, Reference Wurster, Price and Bate2017) and Wurster, Bate, & Price (Reference Wurster, Bate and Price2018) for recent applications. Our formulation of non-ideal SPMHD in Phantom is simpler than the earlier formulation proposed by Hosking & Whitworth (Reference Hosking and Whitworth2004) because we consider only one set of particles, representing a mixture of charged and uncharged species. Ours is similar to the implementation by Tsukamoto, Iwasaki, & Inutsuka (Reference Tsukamoto, Iwasaki and Inutsuka2013) and Tsukamoto et al. (Reference Tsukamoto, Iwasaki, Okuzumi, Machida and Inutsuka2015).

#### 2.11.1. Equations of non-ideal MHD

We assume the strong coupling or ‘heavy ion’ approximation (see e.g. Wardle & Ng Reference Wardle and Ng1999; Shu et al. Reference Shu, Galli, Lizano and Cai2006; Pandey & Wardle Reference Pandey and Wardle2008), which neglects ion pressure and assumes ρ_{i} ≪ ρ_{n}, where the subscripts *i* and *n* refer to the ionised and neutral fluids, respectively. In this case, (167) contains three additional terms in the form

where σ_{e} is the electrical conductivity, *n* _{e} is the number density of electrons, *e* is the charge on an electron, and γ_{AD} is the collisional coupling constant between ions and neutrals (Pandey & Wardle Reference Pandey and Wardle2008). We write this in the form

where $\hat{\bm B}$ is the unit vector in the direction of ${\bm B}$ such that η_{O}, η_{AD}, and η_{Hall} are the coefficients for resistive and ambipolar diffusion and the Hall effect, respectively, each with dimensions of area per unit time.

To conserve energy, we require the corresponding resistive and ambipolar heating terms in the thermal energy equation in the form

The Hall term is non-dissipative, being dispersive rather than diffusive, so does not enter the energy equation.

We currently neglect the ‘Biermann battery’ term (Biermann Reference Biermann1950) proportional to ∇*P* _{e}/(*en* _{e}) in our non-ideal MHD implementation, both because it is thought to be negligible in the interstellar medium (Pandey & Wardle Reference Pandey and Wardle2008) and because numerical implementations can produce incorrect results (Graziani et al. Reference Graziani, Tzeferacos, Lee, Lamb, Weide, Fatenejad and Miller2015). This term is mainly important in generating seed magnetic fields for subsequent dynamo processes (e.g. Khomenko et al. Reference Khomenko, Vitas, Collados and de Vicente2017).

#### 2.11.2. Discrete equations

Our main constraint is that the numerical implementation of the non-ideal MHD terms should exactly conserve energy, which is achieved by discretising in the form (Wurster et al. Reference Wurster, Price and Ayliffe2014)

where

The corresponding term in the energy equation is given by

where the magnetic current density is computed alongside the density evaluation according to

Non-ideal MHD therefore utilises a ‘two first derivatives’ approach, similar to the formulation of physical viscosity described in Section 2.7.1. This differs from the ‘direct second derivatives’ approach used for our artificial resistivity term, and in previous formulations of physical resistivity (Bonafede et al. Reference Bonafede, Dolag, Stasyszyn, Murante and Borgani2011). In practice, the differences are usually minor. Our main reason for using two first derivatives for non-ideal MHD is that it is easier to incorporate the Hall effect and ambipolar diffusion terms.

#### 2.11.3. Computing the non-ideal MHD coefficients

To self-consistently compute the coefficients η_{O}, η_{H}, and η_{AD} from the local gas properties, we use the nicil library (Wurster Reference Wurster2016) for cosmic ray ionisation chemistry and thermal ionisation. We refer the reader to Wurster (Reference Wurster2016) and Wurster et al. (Reference Wurster, Price and Bate2016) for details, since this is maintained and versioned as a separate package.

#### 2.11.4. Timestepping

With explicit timesteps, the timestep is constrained in a similar manner to other terms, using

where *C* _{nimhd} = 1/(2π) by default. This can prove prohibitive, so we employ the so-called ‘super-timestepping’ algorithm from Alexiades, Amiez, & Gremaud (Reference Alexiades, Amiez and Gremaud1996) to relax the stability criterion for the Ohmic and ambipolar terms (only). The implementation is described in detail in Wurster et al. (Reference Wurster, Price and Bate2016). Currently, the Hall effect is always timestepped explicitly in the code.

### 2.12. Self-gravity

Phantom includes self-gravity between particles. By self-gravity, we mean a solution to Poisson’s equation

where Φ is the gravitational potential and ρ represents a continuous fluid density. The corresponding acceleration term in the equation of motion is

Since (203) is an elliptic equation, implying instant action, it requires a global solution. This solution is obtained in Phantom by splitting the acceleration into ‘short-range’ and ‘long-range’ contributions.

where the ‘short-range’ interaction is computed by direct summation over nearby particles, and the ‘long-range’ interaction is computed by hierarchical grouping of particles using the *k*d-tree.

The distance at which the gravitational acceleration is treated as ‘short-’ or ‘long-range’ is determined for each node–node pair, *n*–*m*, either by the tree opening criterion,

where 0 ⩽ θ ⩽ 1 is the tree opening parameter, or by nodes whose smoothing spheres intersect,

Here, *s* is the node size, which is the minimum radius about the centre of mass that contains all the particles in the node, and *h* _{max} is the maximum smoothing length of the particles within the node. Node pairs satisfying either of these criteria have the particles contained within them added to a trial neighbour list, used for computing the short-range gravitational acceleration. Setting θ = 0, therefore, leads to the gravitational acceleration computed entirely as ‘short-range’, that is, only via direction summation, while θ = 1 gives the fastest possible, but least accurate, gravitational force evaluation. The code default is θ = 0.5.

#### 2.12.1. Short-range interaction

How to solve (203) on particles is one of the most widely misunderstood problems in astrophysics. In SPH or collisionless *N*-body simulations (i.e. stars and dark matter), the particles do not represent physical point-mass particles, but rather interpolation points in a density field that is assumed to be continuous. Hence, one needs to first reconstruct the density field on the particles, then solve (203) in a manner which is consistent with this (e.g. Hernquist & Barnes Reference Hernquist and Barnes1990).

How to do this consistently using a spatially adaptive softening length was demonstrated by Price & Monaghan (Reference Price and Monaghan2007), since an obvious choice is to use the iterative kernel summation in (3) to both reconstruct the density field and set the softening length, i.e.Footnote ^{6}

It can then be shown that the gravitational potential consistent with this choice is given by

where ϕ is the softening kernel derived from the density kernel via Poisson’s equation (Section 2.12.2). For a variable smoothing length, energy conservation necessitates taking an average of the kernels, i.e.

Price & Monaghan (Reference Price and Monaghan2007) showed how the equations of motion could then be derived from a Lagrangian in order to take account of the softening length gradient terms, giving equations of motion in the form

where Ω^{ε} and ζ are correction terms necessary for energy conservation, with Ω as in (5) but with *h* replaced by ε, and ζ defined as

The above formulation satisfies all of the conservation properties, namely conservation of linear momentum, angular momentum, and energy.

The short-range acceleration is evaluated for each particle in the leaf node *n* by summing (211) over the trial neighbour list obtained by node–node pairs that satisfy either of the criteria in (206) or (207). For particle pairs separated outside the softening radius of either particle, the short range interaction reduces to

We use this directly for such pairs to avoid unnecessary evaluations of the softening kernel.

It is natural in SPH to set the gravitational softening length equal to the smoothing length ε = *h*, since both derive from the same density estimate. Indeed, Bate & Burkert (Reference Bate and Burkert1997) showed that this is a crucial requirement to resolve gas fragmentation correctly. For pure *N*-body calculations, Price & Monaghan (Reference Price and Monaghan2007) also showed that setting the (variable) softening length in the same manner as the SPH smoothing length (Sections 2.1.3–2.1.4) results in a softening that is always close to the ‘optimal’ fixed softening length (Merritt Reference Merritt1996; Athanassoula et al. Reference Athanassoula, Fady, Lambert and Bosma2000; Dehnen Reference Dehnen2001). In collisionless *N*-body simulations, this has been found to increase the resolving power, giving results at lower resolution comparable to those obtained at higher resolution with a fixed softening length (Bagla & Khandai Reference Bagla and Khandai2009; Iannuzzi & Dolag Reference Iannuzzi and Dolag2011). It also avoids the problem of how to ‘choose’ the softening length, negating the need for ‘rules of thumb’ such as the one given by Springel (Reference Springel2005) where the softening length is chosen to be 1/40 of the average particle spacing in the initial conditions.

#### 2.12.2. Functional form of the softening kernel

The density kernel and softening potential kernel are related using Poisson’s equation (203), i.e.

where $r \equiv \vert {\bm r} - {\bm r}^{\prime }\vert$. Integrating this equation gives the softening kernels used for the force and gravitational potential. As with the standard kernel functions (Section 2.1.5), we define the potential and force kernels in terms of dimensionless functions of the scaled interparticle separation, *q* ≡ *r*/*h*, according to

where the dimensionless force kernel is obtained from the density kernel *f*(*q*) (Section 2.1.5–2.1.6) using

with the integration constant set such that $\tilde{\phi }^{\prime }(q) = 1/q^{2}$ at *q* = *R* _{kern}. The potential function is

The derivative of ϕ with respect to ε required in (212) is also written in terms of a dimensionless function, i.e.

where from differentiating (215), we have

Included in the Phantom source code is a Python script using the sympy library to solve (217), (218), and (220) using symbolic integration to obtain the softening kernel from the density kernel. This makes it straightforward to obtain the otherwise laborious expressions needed for each kernel [expressions for the cubic spline kernel are in Appendix A of Price & Monaghan (Reference Price and Monaghan2007) and for the quintic spline in Appendix A of Hubber et al. (Reference Hubber, Batty, McLeod and Whitworth2011)]. Figure 3 shows the functional form of the softening kernels for each of the kernels available in Phantom. The kernel function *f*(*q*) is shown for comparison (top row in each case).

#### 2.12.3. Softening of gravitational potential due to stars, dark matter, and dust

In the presence of collisionless components (e.g. stars, dark matter, and dust), we require estimates of the density in order to set the softening lengths for each component. We follow the generalisation of the SPH density estimate to multi-fluid systems described by Laibe & Price (Reference Laibe and Price2012a) where the density (and hence the softening length and Ω^{ε}) for each component is computed in the usual iterative manner (Section 2.1.4), but using only neighbours of the same type (c.f. Section 2.13.3). That is, the softening length for stars is determined based on the local density of stars, the softening length for dark matter is based on the local density of dark matter particles, and so on. The gravitational interaction both within each type and between different types is then computed using (211). This naturally symmetrises the softening between different types, ensuring that momentum, angular momentum, and energy are conserved.

#### 2.12.4. Long-range interaction

At long range, that is *r* > *R* _{kern}ε_{a} and *r* > *R* _{kern}ε_{b}, the second term in (211) tends to zero since ζ = 0 for *q* ⩾ *R* _{kern}, while the first term simply becomes 1/*r* ^{2}. Computing this via direct summation would have an associated $\mathcal {O}(N^{2})$ computational cost, thus we adopt the usual practice of using the *k*d-tree to reduce this cost to $\mathcal {O}(N\log N)$.

The main optimisation in Phantom compared to a standard tree code (e.g. Hernquist & Katz Reference Hernquist and Katz1989; Benz et al. Reference Benz, Cameron, Press and Bowers1990) is that we compute the long-range gravitational interaction once *per leaf-node* rather than once *per-particle* and that we use Cartesian rather than spherical multipole expansions to enable this (Dehnen Reference Dehnen2000b; Gafton & Rosswog Reference Gafton and Rosswog2011).

The long-range acceleration on a given leaf node *n* consists of a sum over distant nodes *m* that satisfy neither (206) nor (207).

The acceleration along the node centres, between a given pair *n* and *m*, is given (using index notation) by

where *r ^{i}* ≡

*x*−

^{i}_{n}*x*is the relative position vector, $\hat{r}$ is the corresponding unit vector,

^{i}_{m}*M*

_{m}is the total mass in node

*m*,

*Q*is the quadrupole moment of node

^{m}_{ij}*m*, and repeated indices imply summation. We define the following scalar and vector quantities for convenience:

Alongside the acceleration, we compute six independent components of the first derivative matrix:

where

and ten independent components of the second derivatives, given by

The acceleration on each individual particle inside the leaf node *n* is then computed using a second-order Taylor series expansion of ${\bm a}_{\rm node}^{n}$ about the node centre, i.e.

where Δ*x ^{i}_{a}* ≡

*x*−

^{i}_{a}*x*

^{i}_{0}is the relative distance of each particle from the node centre of mass. Pseudo-code for the resulting force evaluation is shown in Figure A5.

The quadrupole moments are computed during the tree build using

where the sum is over all particles in the node. Since *Q* is a symmetric tensor, only six independent quantities need to be stored (*Q* _{xx}, *Q* _{xy}, *Q* _{xz}, *Q* _{yy}, *Q* _{yz} and *Q* _{zz}).

The current implementation in Phantom is $\mathcal {O}(N_{\rm {leafnodes}} \log N_{\rm part})$ rather than the $\mathcal {O}(N)$ treecode implementation proposed by Dehnen (Reference Dehnen2000b), since we do not currently implement the symmetric node–node interactions required for $\mathcal {O}(N)$ scaling. Neither does our treecode conserve linear momentum to machine precision, except when θ = 0. Implementing these additional features would be desirable.

### 2.13. Dust–gas mixtures

Modelling dust–gas mixtures is the first step in the ‘grand challenge’ of protoplanetary disc modelling (Haworth et al. Reference Haworth2016). The public version of Phantom implements dust–gas mixtures using two approaches. One models the dust and gas as two separate types of particles (two-fluid), as presented in Laibe & Price (Reference Laibe and Price2012a, Reference Laibe and Price2012b), and the other, for small grains, using a single type of particle that represents the combination of dust and gas together (one-fluid), as described in Price & Laibe (Reference Price and Laibe2015a). Various combinations of these algorithms have been used in our recent papers using Phantom, including Dipierro et al. (Reference Dipierro, Price, Laibe, Hirsh and Cerioli2015, Reference Dipierro, Laibe, Price and Lodato2016), Ragusa et al. (Reference Ragusa, Dipierro, Lodato, Laibe and Price2017), and Tricco et al. (Reference Tricco, Price and Laibe2017) (see also Hutchison et al. Reference Hutchison, Price, Laibe and Maddison2016).

In the two-fluid implementation, the dust and gas are treated as two separate fluids coupled by a drag term with only explicit timestepping. In the one-fluid implementation, the dust is treated as part of the mixture, with an evolution equation for the dust fraction.

#### 2.13.1. Continuum equations

The two-fluid formulation is based on the continuum equations in the form:

where the subscripts g and d refer to gas and dust properties, *K* is a drag coefficient and the drag heating is

The implementation in Phantom currently neglects any thermal coupling between the dust and the gas (see Laibe & Price Reference Laibe and Price2012a), aside from the drag heating. Thermal effects are important for smaller grains since they control the heating and cooling of the gas (e.g. Dopcke et al. Reference Dopcke, Glover, Clark and Klessen2011). Currently, the internal energy (*u*) of dust particles is simply set to zero.

#### 2.13.2. Stopping time

The stopping time

is the characteristic timescale for the exponential decay of the differential velocity between the two phases caused by the drag. In the code, *t* _{s} is by default specified in physical units, which means that code units need to be defined appropriately when simulating dust–gas mixtures.

#### 2.13.3. Two-fluid dust–gas in SPH

In the two-fluid method, the mixture is discretised into two distinct sets of ‘dust’ and ‘gas’ particles. In the following, we adopt the convention from Monaghan & Kocharyan (Reference Monaghan and Kocharyan1995) that subscripts *a*, *b*, and *c* refer to gas particles while *i*, *j*, and *k* refer to dust particles. Hence, (230)–(231) are discretised with a density summation *over neighbours of the same type* (c.f. Section 2.12.3), giving

for a gas particle, and

for a dust particle. The kernel used for density is the same as usual (Section 2.1.6). We discretise the equations of motion for the gas particles, (232), using

and for dust, (233), using

where *D* is a ‘double hump’ kernel, defined in Section 2.13.4. The drag heating term in the energy equation, (234), is discretised using

Notice that gas properties are only defined on gas particles and dust properties are defined only on dust particles, greatly simplifying the algorithm. Buoyancy terms caused by dust particles occupying a finite volume (Monaghan & Kocharyan Reference Monaghan and Kocharyan1995; Laibe & Price Reference Laibe and Price2012a) are negligible in astrophysics because typical grain sizes (μm) are negligible compared to simulation scales of ~au or larger.

#### 2.13.4. Drag kernels

Importantly, we use a ‘double-hump’ shaped kernel function *D* (Fulk & Quinn Reference Fulk and Quinn1996) instead of the usual bell-shaped kernel *W* when computing the drag terms. Defining *D* in terms of a dimensionless kernel function as previously (c.f. Section 2.1.5).

then the double hump kernels are defined from the usual kernels according to

where the normalisation constant σ is computed by enforcing the usual normalisation condition

Figure 4 shows the functional forms of the double hump kernels used in Phantom. Using double hump kernels for the drag terms was found by Laibe & Price (Reference Laibe and Price2012a) to give a factor of 10 better accuracy at no additional cost. The key feature is that these kernels are zero at the origin putting more weight in the outer parts of the kernel where the velocity difference is large. This also solves the problem of how to define the unit vector in the drag terms (239)–(241)—it does not matter since *D* is also zero at the origin.

#### 2.13.5. Stopping time in SPH

The stopping time is defined between a pair of particles, using the properties of gas and dust defined on the particle of the respective type, i.e.

The default prescription for the stopping time in Phantom automatically selects a physical drag regime appropriate to the grain size, as described below and in Laibe & Price (Reference Laibe and Price2012b). Options to use either a constant *K* or a constant *t* _{s} between pairs are also implemented, useful for testing and debugging (c.f. Section 5.9).

#### 2.13.6. Epstein drag

To determine the appropriate physical drag regime, we use the procedure suggested by Stepinski & Valageas (Reference Stepinski and Valageas1996) where we first evaluate the Knudsen number

where *s* _{grain} is the grain size and λ_{g} is the gas mean free path (see Section 2.13.8, below, for how this is evaluated). For *K* _{n} ⩾ 1, the drag between a particle pair is computed using the generalised formula for Epstein drag from Kwok (Reference Kwok1975), as described in Paardekooper & Mellema (Reference Paardekooper and Mellema2006) and Laibe & Price (Reference Laibe and Price2012b), giving

where

and ρ_{grain} is the intrinsic grain density, which is 3 g/cm^{3} by default. The variable *f* is a correction for supersonic drift velocities given by (Kwok Reference Kwok1975)

where $\Delta v \equiv \vert {\bm v}_{\rm d}- {\bm v}_{\rm g}\vert = v_{\rm d}^{j} - v_{\rm g}^{a}$. The stopping time is therefore

where ρ ≡ ρ_{d} + ρ_{g}. This formula, (250), reduces to the standard expression for the linear Epstein regime in the limit where the drift velocity is small compared to the sound speed (i.e. *f* → 1). Figure 5 shows the difference between the above simplified prescription and the exact expression for Epstein drag (Epstein Reference Epstein1924; c.f. equations (11) and (38) in Laibe & Price Reference Laibe and Price2012b) as a function of Δ*v*/*c* _{s}, which is less than 1% everywhere.

#### 2.13.7. Stokes drag

For *K* _{n} < 1, we adopt a Stokes drag prescription, describing the drag on a sphere with size larger than the mean free path of the gas (Fan & Zhu Reference Fan and Zhu1998). Here, we use (Laibe & Price Reference Laibe and Price2012b)

where the coefficient *C* _{D} is given by (Fassio & Probstein Reference Fassio and Probstein1970) (see Whipple Reference Whipple and Elvius1972; Weidenschilling Reference Weidenschilling1977)

where *R* _{e} is the local Reynolds number around the grain

and ν is the microscopic viscosity of the gas (see below, not to be confused with the disc viscosity). Similar formulations of Stokes drag can be found elsewhere (see e.g. discussion in Woitke & Helling Reference Woitke and Helling2003 and references therein). The stopping time in the Stokes regime is therefore given by

where it remains to evaluate ν and λ_{g}.

#### 2.13.8. Kinematic viscosity and mean free path

We evaluate the microscopic kinematic viscosity, ν, assuming gas molecules interact as hard spheres, following Chapman & Cowling (Reference Chapman and Cowling1970). The viscosity is computed from the mean free path and sound speed according to

with the mean free path defined by relating this expression to the expression for the dynamic viscosity of the gas (Chapman & Cowling Reference Chapman and Cowling1970) given by

with μ_{ν} = ρ_{g}ν, giving

where *n* _{g} = ρ_{g}/*m* is the number density of molecules and σ_{s} is the collisional cross section. To compute this, Phantom currently assumes the gas is molecular Hydrogen, such that the mass of each molecule and the collisional cross section are given by

#### 2.13.9. Stokes/Epstein transition

At the transition between the two regimes, assuming *R* _{e} < 1, (254) reduces to

which is the same as the Epstein drag in the subsonic regime when λ_{g} = 4*s* _{grain}/9, i.e. *K* _{n} = 1. That this transition is indeed continuous in the code is demonstrated in Figure 6, which shows the transition from Epstein to Stokes drag and also through each of the Stokes regimes in (252) by varying the grain size while keeping the other parameters fixed. For simplicity, we assumed a fixed Δ*v* = 0.01*c* _{s} in this plot, even though in general one would expect Δ*v* to increase with stopping time [see Equation (270)].

#### 2.13.10. Self-gravity of dust

With self-gravity turned on, dust particles interact in the same way as stars or dark matter (Section 2.12.3), with a softening length equal to the smoothing length determined from the density of neighbouring dust particles. Dust particles can be accreted by sink particles (Section 2.8.2), but a sink cannot currently be created from dust particles (Section 2.8.4). There is currently no mechanism in the code to handle the collapse of dust to form a self-gravitating object independent of the gas.

#### 2.13.11. Timestep constraint

For the two-fluid method, the timestep is constrained by the stopping time according to

This requirement, alongside the spatial resolution requirement *h* ≲ *c* _{s}*t* _{s} (Laibe & Price Reference Laibe and Price2012a), means the two-fluid method becomes both prohibitively slow and increasingly inaccurate for small grains. In this regime, one should switch to the one-fluid method, as described below.

#### 2.13.12. Continuum equations: One-fluid

In Laibe & Price (Reference Laibe and Price2014a), we showed that the two-fluid equations, (230)–(234), can be rewritten as a single fluid mixture using a change of variables given by

where ρ is the combined density, ε is the dust fraction, ${\bm v}$ is the barycentric velocity, and $\Delta {\bm v}$ is the differential velocity between the dust and gas.

In Laibe & Price (Reference Laibe and Price2014a), we derived the full set of evolution equations in these variables, and in Laibe & Price (Reference Laibe and Price2014c), implemented and tested an algorithm to solve these equations in SPH. However, using a fluid approximation cannot properly capture the velocity dispersion of large grains, as occurs for example when large planetesimals stream simultaneously in both directions through the midplane of a protoplanetary disc. For this reason, the one-fluid equations are better suited to treating small grains, where the stopping time is shorter than the computational timestep. In this limit, we employ the ‘terminal velocity approximation’ (e.g. Youdin & Goodman Reference Youdin and Goodman2005) and the evolution equations reduce to (Laibe & Price Reference Laibe and Price2014a; Price & Laibe Reference Price and Laibe2015a)

where

where ${\bm a}_{\rm d}$ and ${\bm a}_{\rm g}$ refers to any acceleration acting only on the dust or gas phase, respectively. For the simple case of pure hydrodynamics, the only difference is the pressure gradient, giving

such that (268) becomes

Importantly, the one-fluid dust algorithm does not result in any heating term in d*u*/d*t* due to drag, because this term is $\mathcal {O}(\Delta {\bm v}^{2})$ and thus negligible (Laibe & Price Reference Laibe and Price2014a).

#### 2.13.13. Visualisation of one-fluid results

Finally, when visualising results of one-fluid calculations, one must reconstruct the properties of the dust and gas in post-processing. We use

To visualise the one-fluid results in a similar manner to those from the two-fluid method, we reconstruct a set of ‘dust’ and ‘gas’ particles with the same positions but with the respective properties of each type of fluid particle copied onto them. We compute $\Delta {\bm v}$ from (271) using the pressure gradient computed using (34), multiplied by the stopping time and the gas fraction. See Price & Laibe (Reference Price and Laibe2015a) for more details.

#### 2.13.14. One-fluid dust–gas implementation

Our implementation of the one-fluid method in Phantom follows Price & Laibe (Reference Price and Laibe2015a) with a few minor changes and correctionsFootnote ^{7}. In particular, we use the variable $s = \sqrt{\epsilon \rho }$ described in Appendix B of Price & Laibe (Reference Price and Laibe2015a) to avoid problems with negative dust fractions. The evolution equation (268) expressed in terms of *s* is given by

which for the case of hydrodynamics becomes

The SPH discretisation of this equation is implemented in the form

where $\overline{F}_{ab} \equiv \frac{1}{2} [ F_{ab} (h_{a}) + F_{ab}(h_{b}) ]$. The thermal energy equation, (269), takes the form

the first term of which is identical to (35) and the second term of which is discretised in Phantom according to

#### 2.13.15. Conservation of dust mass

Conservation of dust mass with the one-fluid scheme is in principle exact because (Price & Laibe Reference Price and Laibe2015a)

In practice, some violation of this can occur because although the above algorithm guarantees positivity of the dust fraction, it does not guarantee that ε remains less than unity. Under this circumstance, which occurs only rarely, we set ε = max(ε, 1) in the code. However, this violates the conservation of dust mass. This specific issue has been recently addressed in detail in the study by Ballabio et al. (Reference Ballabio, Dipierro, Veronesi, Lodato, Hutchison, Laibe and Price2018). Therefore, in the latest code, there are two main changes as follows:

• Rather than evolve $s = \sqrt{\epsilon \rho }$, in the most recent code, we instead evolve a new variable $s^{\prime } = \sqrt{\rho _{\rm d}/\rho _{\rm g}}$. This prevents the possibility of ε > 1.

• We limit the stopping time such that the timestep from the one fluid algorithm does not severely restrict the computational performance.

For details of these changes, we refer the reader to Ballabio et al. (Reference Ballabio, Dipierro, Veronesi, Lodato, Hutchison, Laibe and Price2018).

#### 2.13.16. Conservation of energy and momentum

Total energy with the one-fluid scheme can be expressed via

which is conserved exactly by the discretisation since

Conservation of linear and angular momentum also hold since the discretisation of the momentum equation is identical to the hydrodynamics algorithm.

#### 2.13.17. Timestep constraint

For the one-fluid method, the timestep is constrained by the *inverse* of the stopping time according to

This becomes prohibitive precisely in the regime where the one-fluid method is no longer applicable (*t* _{s} > *t* _{Cour}; see Laibe & Price Reference Laibe and Price2014a), in which case one should switch to the two-fluid method instead. There is currently no mechanism to automatically switch regimes, though this is possible in principle and may be implemented in a future code version.

### 2.14. Interstellar medium (ISM) physics

#### 2.14.1. Cooling function

The cooling function in Phantom is based on a set of Fortran modules written by Glover & Mac Low (Reference Glover and Mac Low2007), updated further by Glover et al. (Reference Glover, Federrath, Mac Low and Klessen2010). It includes cooling from atomic lines (H I), molecular excitation (H_{2}), fine structure metal lines (Si I, Si II, O I, C I, and C II), gas–dust collisions, and polycyclic aromatic hydrocarbon (PAH) recombination (see Glover & Mac Low Reference Glover and Mac Low2007 for references on each process). Heating is provided by cosmic rays and the photoelectric effect. The strength of the cooling is a function of the temperature, density, and various chemical abundances. Table 2 summarises these various heating and cooling processes. Figure 7 shows the resulting emissivity Λ_{E}(*T*) for temperatures between 10^{4} and 10^{8} K. The cooling rate per unit volume is related to the emissivity according to

where *n* is the number density. The cooling in the energy equation corresponds to

These routines were originally adapted for use in sphng (Dobbs et al. Reference Dobbs, Glover, Clark and Klessen2008) and result in an approximate two-phase ISM with temperatures of 100 K and 10 000 K. Note that the cooling depends on a range of parameters (dust-to-gas ratio, cosmic ray ionisation rate, etc.), many of which can be specified at runtime. Table 3 lists the default abundances, which are set to values appropriate for the Warm Neutral Medium taken from Sembach et al. (Reference Sembach, Howk, Ryans and Keenan2000). The abundances listed in Table 3, along with the dust-to-gas ratio, are the only metallicity-dependent parameters that can be changed at runtime. An option for cooling appropriate to the zero metallicity early universe is also available.

#### 2.14.2. Timestep constraint from cooling

When cooling is used, we apply an additional timestep constraint in the form

where *C* _{cool} = 0.3 following Glover & Mac Low (Reference Glover and Mac Low2007). The motivation for this additional constraint is to not allow the cooling to completely decouple from the other equations in the code (Suttner et al. Reference Suttner, Smith, Yorke and Zinnecker1997), and to avoid cooling instabilities that may be generated by numerical errors (Ziegler, Yorke, & Kaisig Reference Ziegler, Yorke and Kaisig1996).

Cooling is currently implemented only with explicit timestepping of (287), where *u* is evolved alongside velocity in our leapfrog timestepping scheme. However, the substepping scheme described below for the chemical network (Section 2.14.4) is also used to update the cooling on the chemical timestep, meaning that the cooling can evolve on a much shorter timestep than the hydrodynamics when it is used in combination with chemistry, which it is by default. Implementation of an implicit cooling method, namely the one proposed by Townsend (Reference Townsend2009), is under development.

#### 2.14.3. Chemical network

A basic chemical network is included for ISM gas that evolves the abundances of H, H^{+}, e^{−}, and the molecules H_{2} and CO. The number density of each species, *n* _{X}, is evolved using simple rate equations of the form

where *C* _{X} and *D* _{X} are creation and destruction coefficients for each species. In general, *C* _{X} and *D* _{X} are functions of density, temperature, and abundances of other species. The number density of each species, *X*, is time integrated according to

There are in effect only three species to evolve (H, H_{2}, and CO), as the H^{+} and e^{−} abundances are directly related to the H abundance.

The chemistry of atomic hydrogen is effectively the same as in Glover & Mac Low (Reference Glover and Mac Low2007). H is created by recombination in the gas phase and on grain surfaces, and destroyed by cosmic ray ionisation and free electron collisional ionisation. H_{2} chemistry is based on the model of Bergin et al. (Reference Bergin, Hartmann, Raymond and Ballesteros-Paredes2004), with H_{2} created on grain surfaces and destroyed by photo-dissociation and cosmic rays (see Dobbs et al. Reference Dobbs, Glover, Clark and Klessen2008 for computational details).

The underlying processes behind CO chemistry are more complicated, and involve many intermediate species in creating CO from C and O by interactions with H species. Instead of following every intermediate step, we use the model of Nelson & Langer (Reference Nelson and Langer1997) (see Pettitt et al. Reference Pettitt, Dobbs, Acreman and Price2014 for computational details). CO is formed by a gas phase reaction from an intermediate CH_{Z} step after an initial reaction of C^{+} and H_{2} (where *Z* encompasses many similar type species). CO and CH_{Z} are subject to independent photo-destruction, which far outweighs the destruction by cosmic rays. Abundances of C^{+} and O are used in the CO chemistry, and their abundance is simply the initial value excluding what has been used up in CO formation. Glover & Clark (Reference Glover and Clark2012) test this and a range of simpler and more complicated models, and show that the model adopted here is sufficient for large-scale simulations of CO formation, although it tends to over-produce CO compared to more sophisticated models.

The details for each reaction in the H, H_{2}, and CO chemistry are given in Table 4, with relevant references for each process.

* H ^{+} _{2} ions produced by cosmic ray ionisation of H_{2} are assumed to dissociatively recombine to H + H, so that the effective reaction in the code is actually H_{2} + c.r. → H + H.

† Process is intermediate and is assumed rather than fully represented.

^{††} C is not present in our chemistry, but is assumed to rapidly photoionise to C^{+}.

#### 2.14.4. Timestep constraint from chemistry

H chemistry is evolved on the cooling timestep, since the timescale on which the H^{+} abundance changes significantly is generally comparable to or longer than the cooling time. This is not true for H_{2} and CO. Instead, these species are evolved using a chemical timestepping criterion, where (290) is subcycled during the main time step at the interval Δ*t* _{chem}. If the abundance is decreasing, then the chemical timestep is

i.e., 10% of the time needed to completely deplete the species. If the abundance is increasing,

where Δ*t* _{hydro} is the timestep size for the hydrodynamics, and was found to be an appropriate value by test simulations. These updated abundances feed directly into the relevant cooling functions. Although the cooling function includes Si I and C I, the abundances of these elements are set to zero in the current chemical model.

### 2.15. Particle injection

We implement several algorithms for modelling inflow boundary conditions (see Toupin et al. Reference Toupin, Braun, Siess, Jorissen, Gail and Price2015a, Reference Toupin, Braun, Siess, Jorissen, Price, Kerschbaum, Wing and Hron2015b for recent applications) This includes injecting SPH particles in spherical winds from sink particles (both steady and time dependent), in a steady Cartesian flow and for injection at the *L* _{1} point between a pair of sink particles to simulate the formation of accretion discs by Roche Lobe overflow in binary systems.

## 3 INITIAL CONDITIONS

### 3.1. Uniform distributions

The simplest method for initialising the particles is to set them on a uniform Cartesian distribution. The lattice arrangement can be cubic (equal particle spacing in each direction, Δ*x* = Δ*y* = Δ*z*), close-packed ($\Delta y = \sqrt{3/4}\Delta x$, $\Delta z = \sqrt{6}/3 \Delta x$, repeated every three layers in *z*), hexagonal close-packed (as for close-packed but repeated every two layers in *z*), or uniform random. The close-packed arrangements are the closest to a ‘relaxed’ particle distribution, but require care with periodic boundary conditions due to the aspect ratio of the lattice. The cubic lattice is not a relaxed arrangement for the particles, but is convenient and sufficient for problems where the initial conditions are quickly erased (e.g. driven turbulence). For problems where initial conditions matter, it is usually best to relax the particle distribution by evolving the simulation for a period of time with a damping term (Section 3.6). This is the approach used, for example, in setting up stars in hydrostatic equilibrium (Section 3.4).

### 3.2. Stretch mapping

General non-uniform density profiles may be set up using ‘stretch mapping’ (Herant Reference Herant1994). The procedure for spherical distributions is the most commonly used (e.g. Fryer, Hungerford, & Rockefeller Reference Fryer, Hungerford and Rockefeller2007; Rosswog & Price Reference Rosswog and Price2007; Rosswog, Ramirez-Ruiz, & Hix Reference Rosswog, Ramirez-Ruiz and Hix2009), but we have generalised the method for any density profile that is along one coordinate direction (e.g. Price & Monaghan Reference Price and Monaghan2004b). Starting with particles placed in a uniform distribution, the key is that a particle should keep the same relative position in the mass distribution. For each particle with initial coordinate *x* _{0} in the relevant coordinate system, we solve the equation

where *M*(*x*) is the desired density profile integrated along the relevant coordinate direction, i.e.

where the area element d*S*(*x*′) depends on the geometry and the chosen direction, given by

We solve (293) for each particle using Newton–Raphson iterations

where

iterating until |*f*(*x*)| < 10^{−9}. The Newton–Raphson iterations have second-order convergence, but may fail in extreme cases. Therefore, if the root finding has failed to converge after 30 iterations, we revert to a bisection method, which is only first-order but guaranteed to converge.

Stretch mapping is implemented in such a way that only the desired density function need be specified, either as through an analytic expression (implemented as a function call) or as a tabulated dataset. Since the mass integral in (294) may not be known analytically, we compute this numerically by integrating the density function using the trapezoidal rule.

The disadvantage of stretch mapping is that in spherical or cylindrical geometry it produces defects in the particle distribution arising from the initial Cartesian distribution of the particles. In this case, the particle distribution should be relaxed into a more isotropic equilibrium state before starting the simulation. For stars, for example, this may be done by simulating the star in isolation with artificial damping added (Section 3.6). Alternative approaches are to relax the simulation using an external potential chosen to produce the desired density profile in equilibrium (e.g. Zurek & Benz Reference Zurek and Benz1986; Nagasawa, Nakamura, & Miyama Reference Nagasawa, Nakamura and Miyama1988) or to iteratively ‘cool’ the particle distribution to generate ‘optimal’ initial conditions (Diehl et al. Reference Diehl, Rockefeller, Fryer, Riethmiller and Statler2015).

### 3.3. Accretion discs

#### 3.3.1. Density field

The accretion disc setup module uses a Monte Carlo particle placement (details in Section A.7) in cylindrical geometry to construct density profiles of the form

where Σ_{0} is the surface density at *R* = *R* _{in} (if *f* _{s} = 1), *H* ≡ *c* _{s}/Ω is the scale height (with $\Omega \equiv \sqrt{GM/R^{3}}$), *p* is the power-law index (where *p* = 3/2 by default following Lodato & Pringle Reference Lodato and Pringle2007), and $f_{\rm s} \equiv (1 - \sqrt{R_{\rm in}/R} )$ is an optional factor to smooth the surface density near the inner disc edge.

Several authors have argued that a more uniform particle placement is preferable for setting up discs in SPH (Cartwright, Stamatellos, & Whitworth Reference Cartwright, Stamatellos and Whitworth2009; Vanaverbeke et al. Reference Vanaverbeke, Keppens, Poedts and Boffin2009). This may be important if one is interested in transient phenomena at the start of a simulation, but otherwise the particle distribution settles to a smooth density distribution within a few orbits (c.f. Lodato & Price Reference Lodato and Price2010).

#### 3.3.2. Velocity field

The orbital velocities of particles in the disc are set by solving the equation for centrifugal equilibrium, i.e.

where the correction from radial pressure gradients is given by

where *q* is the index of the sound speed profile such that *c* _{s}(*R*) = *c* _{s, in}(*R*/*R* _{in})^{−q} and *f* _{BH} is a correction used for discs around a spinning black hole (Nealon et al. Reference Nealon, Price and Nixon2015)

where *a* is the black hole spin parameter. The latter assumes Lense–Thirring precession is implemented as in Section 2.4.5. Where self-gravity is used, *M* is the enclosed mass at a given radius *M*( < *R*), otherwise it is simply the mass of the central object. Using the enclosed mass for the self-gravitating case is an approximation since the disc is not spherically symmetric, but the difference is small and the disc relaxes quickly into the true equilibrium. Equation (299) is a quadratic for *v* _{ϕ} which we solve analytically.

#### 3.3.3. Warps

Warps are applied to the disc (e.g. Lodato & Price Reference Lodato and Price2010; Nealon et al. Reference Nealon, Price and Nixon2015) by rotating the particles about the *y*-axis by the inclination angle *i* [in general, a function of radius *i* ≡ *i*(*R*)], according to

#### 3.3.4. Setting an α-disc viscosity

The simplest approach to mimicking an α-disc viscosity in SPH is to employ a modified shock viscosity term, setting the desired α_{SS} according to (124) as described in more detail in Section 2.6.1. Since the factor 〈*h*〉/*H* is dependent both on resolution and temperature profile (i.e. the *q*-index), it is computed in the initial setup by taking the desired α_{SS} as input in order to give the required α_{AV}. Although this does not guarantee that α_{SS} is constant with radius and time (this is only true with specific choices of *p* and *q* and if the disc is approximately steady), it provides a simple way to prescribe the disc viscosity.

### 3.4. Stars and binary stars

We implement a general method for setting up ‘realistic’ stellar density profiles, based on either analytic functions (e.g. polytropes) or tabulated data files output from stellar evolution codes [see Iaconi et al. (Reference Iaconi, Reichardt, Staff, De Marco, Passy, Price, Wurster and Herwig2017) for a recent application of this to common envelope evolution].

The basic idea is to set up a uniform density sphere of particles and set the density profile by stretch mapping (see above). The thermal energy of the particles is set so that the pressure gradient is in hydrostatic equilibrium with the self-gravity of the star for the chosen EOS. We then relax the star into equilibrium for several dynamical times using a damping parameter (Section 3.6), before re-launching the simulation with the star on an appropriate orbit.

For simulating red giants, it is preferable to replace the core of the star by a sink particle (see Passy et al. Reference Passy2012; Iaconi et al. Reference Iaconi, Reichardt, Staff, De Marco, Passy, Price, Wurster and Herwig2017). When doing so, one should set the accretion radius of the sink to zero and set a softening length for the sink particle consistent with the original core radius (see Section 2.8.1).

### 3.5. Galactic initial conditions

In addition to simulating ISM gas in galactic discs with analytic stellar potentials, one may represent bulge-halo-disc components by collisionless *N*-body particles (see Section 2.12.3). To replace a potential with a resolved system requires care with the initial conditions (i.e. position, velocity, and mass). If setup incorrectly the system will experience radial oscillations and undulations in the rotation curve, which will have strong adverse effects on the gas embedded within. We include algorithms for initialising the static-halo models of Pettitt et al. (Reference Pettitt, Dobbs, Acreman and Bate2015) (which used the sphng SPH code). These initial conditions require the NFW profile to be active and care must be taken to ensure the mass and scale lengths correspond to the rotation curve used to generate the initial conditions. Other codes may alternatively be used to seed multi-component *N*-body disc galaxies (e.g. Kuijken & Dubinski Reference Kuijken and Dubinski1995a; Boily, Kroupa, & Peñarrubia-Garrido Reference Boily, Kroupa and Peñarrubia-Garrido2001; McMillan & Dehnen Reference McMillan and Dehnen2007; Yurin & Springel Reference Yurin and Springel2014), including magalie (Boily et al. Reference Boily, Kroupa and Peñarrubia-Garrido2001) and galic (Yurin & Springel Reference Yurin and Springel2014) for which we have implemented format readers.

The gas in galactic scale simulations can be setup either in a uniform surface density disc, or according to the Milky Way’s specific surface density. The latter is based on the radial functions given in Wolfire et al. (Reference Wolfire, Hollenbach, McKee, Tielens and Bakes1995). As of yet, we have not implemented a routine for enforcing hydrostatic equilibrium (Springel, Di Matteo, & Hernquist Reference Springel, Di Matteo and Hernquist2005; Wang et al. Reference Wang, Klessen, Dullemond, van den Bosch and Fuchs2010), this may be included in a future update.

### 3.6. Damping

To relax a particle distribution into equilibrium, we adopt the standard approach (e.g. Gingold & Monaghan Reference Gingold and Monaghan1977) of adding an external acceleration in the form

such that a percentage of the kinetic energy is removed each timestep. The damping parameter, *f* _{d}, is specified by the user. A sensible value for *f* _{d} is of order a few percent (e.g. *f* _{d} = 0.03) such that a small fraction of the kinetic energy is removed over a Courant timescale.

## 4 SOFTWARE ENGINEERING

No code is completely bug free (experience is the name everyone gives to their mistakes; Wilde Reference Wilde1892). However, we have endeavoured to apply the principles of good software engineering to Phantom. These include

1. a modular structure,

2. unit tests of important modules,

3. nightly builds,

4. automated nightly tests,

5. automated code maintenance scripts,

6. version control with git,

7. wiki documentation, and

8. a bug database and issue tracker.

Together these simplify the maintenance, stability, and usability of the code, meaning that Phantom can be used direct from the development repository without fear of regression, build failures, or major bugs.

Specific details of how the algorithms described in Section 2 are implemented are given in the Appendix. Details of the test suite are given in Appendix A.9.

## 5 NUMERICAL TESTS

Unless otherwise stated, we use the *M* _{6} quintic spline kernel with *h* _{fac} = 1.0 by default, giving a mean neighbour number of 113 in 3D. Almost all of the test results are similar when adopting the cubic spline kernel with *h* _{fac} = 1.2 (requiring ≈58 neighbours), apart from the tests with the one-fluid dust method where the quintic is required. Since most of the algorithms used in Phantom have been extensively tested elsewhere, our aim is merely to demonstrate that the implementation in the code is correct, and to illustrate the typical results that should be achieved on these tests when run by the user. The input files used to run the entire test suite shown in the paper are available on the website, so it should be straightforward for even a novice user to reproduce our results.

Unless otherwise indicated, we refer to dimensionless ${\cal L}_{1}$ and ${\cal L}_{2}$ norms when referencing errors, computed according to

where *y* _{exact} is the exact or comparison solution interpolated or computed at the location of each particle *i* and *N* is the number of points. The norms are the standard error norms divided by a constant, which we set to the maximum value of the exact solution within the domain, *C* _{0} = max(*y* _{exact}), in order to give a dimensionless quantity. Otherwise quoting the absolute value of ${\cal L}_{1}$ or ${\cal L}_{2}$ is meaningless. Dividing by a constant has no effect when considering convergence properties. These are the default error norms computed by splash (Price Reference Price2007).

Achieving formal convergence in SPH is more complicated than in mesh-based codes where linear consistency is guaranteed (see Price Reference Price2012a). The best that can be achieved with regular (positive, symmetric) kernels is second-order accuracy away from shocks provided the particles remain well ordered (Monaghan Reference Monaghan1992). The degree to which this remains true depends on the smoothing kernel and the number of neighbours. Our tests demonstrate that formal second-order convergence can be achieved with Phantom on certain problems (e.g. Section 5.6.1). More typically, one obtains something between first- and second-order convergence in smooth flow depending on the degree of spatial disordering of the particles. The other important difference compared to mesh-based codes is that there is no intrinsic numerical dissipation in SPH due to its Hamiltonian nature—numerical dissipation terms must be explicitly added. We perform all tests with these terms included.

We use timestep factors of *C* _{Cour} = 0.3 and *C* _{force} = 0.25 by default for all tests (Section 2.3.2).

### 5.1. Hydrodynamics

#### 5.1.1. Sod shock tube

Figure 8 shows the results of the standard Sod (Reference Sod1978) shock tube test, performed in 3D using [ρ, *P*] = [1, 1] in the ‘left state’ (*x* ⩽ 0) and [ρ, *P*] = [0.125, 0.1] for the ‘right state’ (*x* > 0) with a discontinuity initially at *x* = 0 and zero initial velocity and magnetic field. We perform the test using an adiabatic EOS with γ = 5/3 and periodic boundaries in *y* and *z*. While many 1D solutions appear in the literature, only a handful of results on this test have been published for SPH in 3D (e.g. Dolag et al. Reference Dolag, Vazza, Brunetti and Tormen2005; Hubber et al. Reference Hubber, Batty, McLeod and Whitworth2011; Beck et al. Reference Beck2016; a 2D version is shown in Price Reference Price2012a). The tricky part in a 3D SPH code is how to set up the density contrast. Setting particles on a cubic lattice is a poor choice of initial condition since this is not a stable arrangement for the particles (Morris Reference Morris1996b, Reference Morris1996a; Lombardi et al. Reference Lombardi, Sills, Rasio and Shapiro1999; Børve et al. Reference Børve, Omang and Trulsen2004). The approach taken in Springel (Reference Springel2005) (where only the density was shown, being the easiest to get right) was to relax the two halves of the box into a stable arrangement using the gravitational force run with a minus sign, but this is time consuming.

Here we take a simpler approach which is to set the particles initially on a close-packed lattice (Section 3.1), since this is close to the relaxed arrangement (e.g. Lombardi et al. Reference Lombardi, Sills, Rasio and Shapiro1999). To ensure continuity of the lattice across periodic boundaries, we fix the number of particles in the *y* (*z*) direction to the nearest multiple of 2 (3) and adjust the spacing in the *x*-direction accordingly to give the correct density in each subdomain. We implement the boundary condition in the *x*-direction by tagging the first and last few rows of particles in the *x* direction as boundary particles, meaning that their particle properties are held constant. The results shown in Figure 8 use 256 × 24 × 24 particles initially in *x* ∈ [− 0.5, 0] and 128 × 12 × 12 particles in *x* ∈ [0, 0.5] with code defaults for the artificial conductivity [α_{u} = 1 with *v ^{u}*

_{sig}given by equation (43)] and artificial viscosity (α

^{AV}= 1, β

^{AV}= 2). The results are identical whether global or individual particle timesteps (Section 2.3.4) are used. Figure 9 shows the results when code defaults for viscosity are also employed, resulting in a time-dependent α

^{AV}(see lower right panel). There is more noise in the velocity field around the contact discontinuity in this case, but the results are otherwise identical.

The ${\cal L}_2$ errors for the solutions shown in Figure 8 are 0.0090, 0.0022, 0.0018, and 0.0045 for the density, velocity, thermal energy, and pressure, respectively. With dissipation switches turned on (Figure 9), the corresponding errors are 0.009, 0.0021, 0.0019, and 0.0044, respectively. That is, our solutions are within 1% of the analytic solution for all four quantities in both cases, with the density profile showing the strongest difference (mainly due to smoothing of the contact discontinuity).

Puri & Ramachandran (Reference Puri and Ramachandran2014) compared our shock capturing algorithm with other SPH variants, including Godunov SPH. Our scheme was found to be the most robust of those tested.

#### 5.1.2. Blast wave

As a more extreme version of the shock test, Figures 10 and 11 show the results of the blast wave problem from Monaghan (Reference Monaghan1997), set up initially with [ρ, *P*] = [1, 1000] for *x* ⩽ 0 and [ρ, *P*] = [1.0, 0.1] for *x* > 0 and with γ = 1.4 (appropriate to air). As previously, we set the particles on a close-packed lattice with a discontinuous initial pressure profile. We employ 800 × 12 × 12 particles in the domain *x* ∈ [− 0.5, 0.5]. Results are shown at *t* = 0.01. This is a more challenging problem than the Sod test due to the higher Mach number. As previously, we show results with both α^{AV} = 1 (Figure 10) and with the viscosity switch α ∈ [0, 1]. Both calculations use α_{u} = 1 with (43) for the signal speed in the artificial conductivity. For the solution shown in Figure 10, we find normalised ${\cal L}_2$ errors of 0.057, 0.063, 0.051, and 0.018 in the density, velocity, thermal energy, and pressure, respectively, compared to the analytic solution. Employing switches (Figure 11), we find corresponding ${\cal L}_2$ errors of 0.056, 0.059, 0.052, and 0.017. That is, our solutions are within 6% of the analytic solution at this resolution.

The main source of error is that the contact discontinuity is over-smoothed due to the artificial conductivity, while the velocity profile shows a spurious jump at the location of the contact discontinuity. This glitch is a startup error caused by our use of purely discontinuous initial conditions—it could be removed by adopting smoothed initial conditions but we prefer to perform the more difficult version of this test. There is also noise in the post-shock velocity profile because the viscosity switch does not apply enough dissipation here. As in the previous test, this noise can be reduced by increasing the numerical viscosity, e.g. by adopting a constant α^{AV} (compare Figures 10 and 11).

Figure 12 quantifies the error in energy conservation, showing the error in the total energy as a function of time, i.e. |*E* − *E* _{0}|/|*E* _{0}|. Energy is conserved to a relative accuracy of better than 2 × 10^{−6}.

#### 5.1.3. Sedov blast wave

The Sedov–Taylor blast wave (Taylor Reference Taylor1950a, Reference Taylor1950b; Sedov Reference Sedov1959) is a similar test to the previous but with a spherical geometry. This test is an excellent test for the individual timestepping algorithm, since it involves propagating a blast wave into an ambient medium of ‘inactive’ or ‘asleep’ particles, which can cause severe loss of energy conservation if they are not carefully awoken (Saitoh & Makino Reference Saitoh and Makino2009). For previous uses of this test with SPH, see e.g. Springel & Hernquist (Reference Springel and Hernquist2002) and Rosswog & Price (Reference Rosswog and Price2007), and for a comparison between SPH and mesh codes on this test, see Tasker et al. (Reference Tasker, Brunino, Mitchell, Michielsen, Hopton, Pearce, Bryan and Theuns2008).

We set up the problem in a uniform periodic box *x*, *y*, *z* ∈ [− 0.5, 0.5], setting the thermal energy on the particles to be non-zero in a barely resolved sphere around the origin. We assume an adiabatic EOS with γ = 5/3. The total energy is normalised such that the total thermal energy in the blast is *E* _{0} = ∑_{a}*m* _{a}*u* _{a} = 1, distributed on the particles within *r* < *R* _{kern}*h* _{0} using the smoothing kernel, i.e.

where $r = \sqrt{x^{2} + y^{2} + z^{2}}$ is the radius of the particle and we set *h* _{0} to be twice the particle smoothing length.

We simulate the Sedov blast wave using both global and individual timesteps at several different resolutions. Figure 13 shows the evolution of the relative error in total energy for our suite, while Figure 14 shows the density at *t* = 0.1 compared to the analytical solution given by the solid line. Energy is conserved to better than 1% in all cases. Using higher spatial resolution results in a better match of the post-shock density with the analytic solution. The scatter at the leading edge of the shock is a result of the default artificial conductivity algorithm. Given the initial strong gradient in thermal energy, using more artificial conductivity than our switch permits would reduce the noise on this problem (Rosswog & Price Reference Rosswog and Price2007).

#### 5.1.4. Kelvin–Helmholtz instability

Much has been written about Kelvin–Helmholtz instabilities with SPH (e.g. Agertz et al. Reference Agertz2007; Price Reference Price2008; Abel Reference Abel2011; Valdarnini Reference Valdarnini2012; Read & Hayfield Reference Read and Hayfield2012; Hubber, Falle, & Goodwin Reference Hubber, Falle and Goodwin2013c). For the present purpose, it suffices to say that the test problems considered by Agertz et al. (Reference Agertz2007) and Price (Reference Price2008) are not well posed. That is, the number of small-scale secondary instabilities will always increase with numerical resolution because high wavenumber modes grow fastest in the absence of physical dissipation or other regularising forces such as magnetic fields or surface tension. The ill-posed nature of the test problem has been pointed out by several authors (Robertson et al. Reference Robertson, Kravtsov, Gnedin, Abel and Rudd2010; McNally, Lyra, & Passy Reference McNally, Lyra and Passy2012; Lecoanet et al. Reference Lecoanet2016), who have each proposed well-posed alternatives.

We adopt the setup from Robertson et al. (Reference Robertson, Kravtsov, Gnedin, Abel and Rudd2010), similar to the approach by McNally et al. (Reference McNally, Lyra and Passy2012), where the initial density contrast is smoothed using a ramp function. This should suppress the formation of secondary instabilities long enough to allow a single large-scale mode to grow. The density and shear velocity in the *y* direction are given by

and

where ρ_{1} = 1, ρ_{2} = 2, *v* _{1} = −0.5, and *v* _{2} = 0.5 with constant pressure *P* = 2.5, γ = 5/3. The ramp function is given by

where

and we set Δ = 0.25. Finally, a perturbation is added in the velocity in the *y* direction, given by

The setup in Robertson et al. (Reference Robertson, Kravtsov, Gnedin, Abel and Rudd2010) is 2D, but since Phantom is a 3D code, we instead set up the problem using a thin 3D box. We first set up a uniform close packed lattice in a periodic box with dimensions $1 \times 1 \times \sqrt{24}/n_{x}$, where *n* _{x} is the initial resolution in the *x* direction such that the box thickness is set to be exactly 12 particle spacings in the *z* direction independent of the resolution used in the *x* and *y* direction. The box is set between [0,1] in *x* and *y*, consistent with the ramp function. We then set up the density profile by stretch mapping in the *y* direction using (312) as the input function (c.f. Section 3.2).

Figure 15 shows the results of this test, showing a cross section of density at *z* = 0 for three different resolutions (top to bottom) and at the times corresponding to those shown in Robertson et al. (Reference Robertson, Kravtsov, Gnedin, Abel and Rudd2010). We compute the quantitative difference between the calculations by taking the root mean square difference of the cross section slices shown above interpolated to a 1,024 × 1,024 pixel map. The error between the *n* _{x} = 64 calculation and the *n* _{x} = 256 calculation is 1.3 × 10^{−3}, while this reduces to 4.9 × 10^{−4} for the *n* _{x} = 128 calculation. Figure 16 shows the growth of the amplitude of the mode seeded in (316). We follow the procedure described in McNally et al. (Reference McNally, Lyra and Passy2012) to calculate the mode amplitude. At *t* = 2, the amplitude between the *n* _{x} = 128 and *n* _{x} = 256 calculations is within 4%. The artificial viscosity and conductivity tend to slow convergence on this problem, so it is a good test of the dissipation switches (we use the default code viscosity switch as discussed in Section 2.2.9).

### 5.2. External forces

#### 5.2.1. Lense–Thirring precession

We test the implementation of the Lense–Thirring precession by computing the precession induced on a pressure-less disc of particles, as outlined in Nealon et al. (Reference Nealon, Price and Nixon2015). This disc is simulated for one orbit at the outer edge such that the inner part of the disc has precessed multiple times but the outer region has not yet completed a full precession. The precession timescale is estimated by measuring the twist as a function of time for each radial bin; in the inner region, this is the time taken for the twist to go from a minimum (zero twist) to a maximum (fully twisted) and in the outer region the gradient of the twist against time is used to calculate the equivalent time. Figure 17 shows the precession timescale measured from the simulation as a function of the radius compared to the analytically derived