Metadata-Version: 2.4
Name: PkdGrav-snapshot
Version: 1.0.0
Summary: Input/output of PkdGrav particle snapshots
Keywords: cosmology,astrophysics
Author: John Hennig
License-Expression: GPL-3.0-or-later
License-File: license.txt
Classifier: Development Status :: 5 - Production/Stable
Classifier: Topic :: Scientific/Engineering :: Physics
Classifier: Intended Audience :: Science/Research
Requires-Dist: pandas>=3
Requires-Dist: numpy>=2
Requires-Python: >=3.11
Project-URL: Source, https://cosmo-gitlab.phys.ethz.ch/cosmo_public/PkdGrav-snapshot
Project-URL: Releases, https://cosmo-gitlab.phys.ethz.ch/cosmo_public/PkdGrav-snapshot/-/releases
Description-Content-Type: text/markdown

﻿# PkdGrav-snapshot
*Input/output of PkdGrav particle snapshots*

This Python library reads and writes particle snapshots in the [Tipsy] format.
Files of this type are typically produced by [PkdGrav] at each time step of a
cosmological N-body simulation. The snapshot files contain information such
as mass, position, velocity… of gas, dark-matter, and star particles.


## Installation

Install the package directly from the Git repo:
```
❯ pip install git+https://cosmo-gitlab.phys.ethz.ch/john.hennig/PkdGrav-snapshot.git
```


## Usage

To read particle data from a PkdGrav snapshot file:
```python
import pkdsnap
(gas, dm, star, time) = pkdsnap.read('snapshot.tipsy')
```

This returns `gas`, `dm` (dark matter), and `star` particles as [Pandas data
frames][DataFrame] as well as the simulation `time` of the snapshot as a
number. The data frames correspond to the `struct` fields of the PkdGrav
file format as documented in the [section "Tipsy Format"][Tipsy] of the PkdGrav
documentation.

Note that PkdGrav does not typically use the `.tipsy` file extension. For a
simulation with output name (`achOutName`) "results", the files would be named
like `results.00140`, wherein 140 is the time step.

Given Pandas data frames of the same column structure as returned by `read()`,
particle data can be written to a PkdGrav snapshot file with:
```python
pkdsnap.write('snapshot.tipsy', gas=gas, dm=dm, star=star, time=0.01)
```

For example (made-up numbers, not necessarily physical):
```python
from pandas import DataFrame

gas = DataFrame({
    'm':  [  0.00001 ],
    'x':  [ -0.5     ],
    'y':  [ -0.5     ],
    'z':  [ -0.5     ],
    'vx': [ -0.02    ],
    'vy': [ +0.03    ],
    'vz': [ +0.01    ],
    'ρ':  [  0.1     ],
    'T':  [  4.2     ],
    'hs': [  9.5     ],
    'μ':  [  0.1     ],
    'φ':  [  0.1     ],
})

dm = DataFrame({
    'm':  [  0.00002 ,  0.00002 ],
    'x':  [ -0.1     , +0.5     ],
    'y':  [ -0.4     , +0.2     ],
    'z':  [ +0.1     , +0.4     ],
    'vx': [ -0.02    , +0.03    ],
    'vy': [ +0.03    , +0.00    ],
    'vz': [ -0.00    , +0.02    ],
    'ε':  [  0.0006  ,  0.0006  ],
    'φ':  [ -0.053   , -0.053   ],
})

star = DataFrame({
    'm':  [  0.00003 ,  0.00003 ,  0.00003 ],
    'x':  [ -0.4     , +0.3     , +0.5     ],
    'y':  [ +0.5     , +0.1     , -0.2     ],
    'z':  [ -0.5     , +0.2     , -0.1     ],
    'vx': [ -0.02    , +0.03    , +0.04    ],
    'vy': [ +0.01    , +0.02    , -0.01    ],
    'vz': [ +0.03    , -0.01    , -0.04    ],
    'μ':  [  0.1     ,  0.1     ,  0.1     ],
    'tf': [ 12.1     , 12.2     , 12.3     ],
    'ε':  [  0.0006  ,  0.0006  ,  0.0006  ],
    'φ':  [ -0.053   , -0.053   , -0.053   ],
})
```

Particle data may also be appended to an existing Tipsy file:
```python
pkdsnap.append('snapshot.tipsy', dm=more_dm_particles)
```

Note, however, that this only works if the existing file contains only
particles of the same type as those to be appended.


[PkdGrav]:   https://pkdgrav3.readthedocs.io
[Tipsy]:     https://pkdgrav3.readthedocs.io/en/latest/fileformats.html#tipsy-format
[DataFrame]: https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.DataFrame.html
