sarracen.write_phantom

sarracen.write_phantom(filename: str, sdf: SarracenDataFrame, sinks: SarracenDataFrame | None = None) → None

Write a Phantom dump file from a SarracenDataFrame.

Both particle data and global header parameters stored in the sdf.params dict are written. If required Phantom parameters are missing, then Sarracen will automatically infer and set critical parameters such as the number of particles per particle type and the mass of each particle type.

All entries in the sdf.params dict are written to the dump file. Phantom ignores parameters it does not recognise, so this is ok.

By design, Sarracen does not invent values for parameters that are absent. Phantom typically warns about missing parameters and then chooses default values. For example, Sarracen does not require a ‘time’ entry in sdf.params even though it sets the simulation time. If absent, then Phantom assumes t=0.

Many parameters stored in the global header of the dump file are also specified in the Phantom .in file. The equation of state is one example. Phantom stores this in both the .in file and the header of the dump file via ‘ieos’ (which can be set through the sdf.params dict).

Parameters:

filename (str) – Path to output file.
sdf (SarracenDataFrame) – The particle data to write. Must contain positions (x, y, z) and smoothing lengths. Must have params dictionary set with required parameters.
sinks (SarracenDataFrame, optional) – Sink particle data to write. Default is None.

Raises:

ValueError – If sdf contains NaN values. If sinks contains NaN values. If params is not set in sdf. If sdf is missing x, y, or z positions or smoothing lengths. If essential params are missing for the equation of state.

See also

read_phantom: Read Phantom dump files.

Notes

If ‘ieos’ is set, then Sarracen checks for additional parameters required for ‘ieos’ = [1, 2, 3], corresponding to the isothermal, adiabatic, and locally isothermal equations of state.

For periodic boundary conditions, set the domain limits using {‘xmin’, ‘xmax’, ‘ymin’, ‘ymax’, ‘zmin’, ‘zmax’}. If absent, then Phantom assumes a default periodic domain of x, y, z = [0, 1].

To set physical units, set {‘udist’, ‘utime’, ‘umass’, ‘umagfd’}. Otherwise, Phantom will assume default units.

Examples

Sarracen works well as a utility to modify existing Phantom dumps (moddump). This example shows how to use Sarracen to add a new sink particle to an existing Phantom dump.

>>> import sarracen
>>> sdf, sdf_sinks = sarracen.read_phantom('disc_00000')

There is one existing sink particle at (0, 0, 0) with unit mass.

>>> sdf_sinks
     x    y    z    m    h  ...   vx   vy   vz
0  0.0  0.0  0.0  1.0  1.0  ...  0.0  0.0  0.0

Create new sink properties and add to sinks SarracenDataFrame. Columns that were not specified will be NaN, which are set to 0 using fillna() in this example.

>>> new = {'x': -1, 'y': 0, 'z': 0, 'm': 9.54e-4, 'h': 0.17, 'vy': -0.316}
>>> sdf_sinks.loc[1] = new
>>> sdf_sinks.fillna(0, inplace=True)
>>> sdf_sinks
     x    y    z         m     h  ...   vx     vy   vz
0  0.0  0.0  0.0  1.000000  1.00  ...  0.0  0.000  0.0
1 -1.0  0.0  0.0  0.000954  0.17  ...  0.0 -0.316  0.0

Then write the new Phantom dump file with the added sink particle.

>>> sarracen.write_phantom('my_new_disc_00000', sdf, sdf_sinks)

Note that this will copy all entries in the sdf.params dict to the new dump file. This is often useful when modifying existing dump files.