How to incorporate binary or ascii data files into the Phantom repo

If your setup or module relies on external data files (e.g. an ascii table) to function, these files need to be distributed with Phantom in order for your modules to be portable.

Small files

For very small files (under 100Kb), you can simply add these to the git repository in a subdirectory of the phantom/data directory:

$ cd phantom/data
$ ls
README          forcing/        galaxy_merger/      isolatedgalaxy/     star_data_files/
eos/            gal_radii_cdfs/     galcen/         neutronstar/        velfield/

To use the datafile in your code, say from a file called ‘mydata.txt’ which is stored in the subdirectory ‘star_data_files/red_giant/’, you should use the find_phantom_datafile routine from the datafile module to retrieve the file:

#!fortran
use datafiles, only:find_phantom_datafile
character(len=120) :: filename
...

filename=find_phantom_datafile('mydata.txt','star_data_files/red_giant')

This routine searches for the file first in the current directory, followed by the phantom/data directory once the PHANTOM_DIR environment variable is specified, e.g.:

$ export PHANTOM_DIR=~/phantom
$ ./phantomsetup

Large files

For large data files, the procedure is as follows:

  1. Do NOT add the file to the git repository. Instead, place a README file in the directory where the file belongs and add this to the git repository:

git add data/star_data_files/red_giant/README
git commit -m 'placeholder for mydata.txt' data/star_data_files/red_giant/README

  1. Add the name of the file to the .gitignore file in the root-level phantom directory

  2. Then, upload your file(s) to a repository on zenodo.org, obtain the DOI for the repository, and submit it in the phantom zenodo community

    https://zenodo.org/communities/phantom/

    This will allow the file to be downloaded by Phantom users at runtime

  3. Edit the datafiles.f90 module to include the URL for the file in the map_dir_to_web routine. This routine maps the directory where the file should be located to the URL where the file can be downloaded from. For example, if the file is in the star_data_files/red_giant directory, you would add a case to the routine like so:

case('data/star_data_files/red_giant')
     url = 'https://zenodo.org/records/12345678/files/'

where the URL is the URL of the repository on zenodo.org

  1. Implement the call in the code as previously using the find_phantom_datafile routine. This will automatically retrieve the file from the web into your phantom/data directory at runtime. Alternatively you can manually download the file to the appropriate folder