#!/usr/bin/env python
#
# Author: Adrien CR Thob
# Copyright (C) 2022 Adrien CR Thob
#
# This file is part of the py-Galaxia-ananke project,
# <https://github.com/athob/py-Galaxia-ananke>, which is licensed
# under the GNU Affero General Public License v3.0 (AGPL-3.0).
#
# The full copyright notice, including terms governing use, modification,
# and redistribution, is contained in the files LICENSE and COPYRIGHT,
# which can be found at the root of the source code distribution tree:
# - LICENSE <https://github.com/athob/py-Galaxia-ananke/blob/main/LICENSE>
# - COPYRIGHT <https://github.com/athob/py-Galaxia-ananke/blob/main/COPYRIGHT>
#
"""
galaxia_ananke
==============
Provides a set of utilities to run a modified version of the synthetic star
survey generator Galaxia (`Sharma et al 2011 <http://ascl.net/1101.007>`).
How to use
----------
galaxia_ananke comes with the function make_survey_from_particles, please
refer to its documentation for further help.
"""
from .__metadata__ import *
from ._constants import *
from ._defaults import *
from .Input import Input
from .Survey import Survey
from .Output import Output
__all__ = ['make_dummy_particles_input', 'make_dummy_kernels_input', 'make_survey_from_particles']
# check Galaxia installation
if __name__ == NAME:
assert GALAXIA.exists(), f"Galaxia's executable {GALAXIA} doesn't exist, which means that {NAME}'s installation didn't build the backend {GALAXIA_SUBMODULE_NAME} submodule appropriately.\nPlease consult {__url__}/#troubleshooting-installation for troubleshooting."
make_dummy_particles_input = Input.make_dummy_particles_input
make_dummy_kernels_input = Input.make_dummy_kernels_input
[docs]
def make_survey_from_particles(*args, pname=None, kname=None, photo_sys=DEFAULT_PSYS, cmd_magnames=DEFAULT_CMD, simname='sim', surveyname='survey', fsample=1, ngb=64, k_factor=1, caching=False, **kwargs): # args is (particles, rho_pos, rho_vel)
"""
Returns a handler object representing the synthetic star survey
generated by Galaxia given the properties of an input set of particles
and various survey parameters.
Call signatures::
output = make_survey_from_particles(particles, kernels,
photo_sys=DEFAULT_PSYS, cmd_magnames=DEFAULT_CMD, simname='sim',
surveyname='survey', fsample=1, ngb=64, **kwargs)
output = make_survey_from_particles(pname=None, kname=None,
photo_sys=DEFAULT_PSYS, cmd_magnames=DEFAULT_CMD,
surveyname='survey', fsample=1, **kwargs)
Parameters
----------
particles : dict
Dictionary where each elements represent the properties of the
input particles, given as equal-length array_like objects. Refer
to Input documentation for appropriate formatting. galaxia_ananke
also comes packaged with a function make_dummy_particles_input to
produce a dummy example for that dictionary.
kernels : array_like
Array containing the kernel characteristic lengths for each
input particle. Must be of equal length N as the arrays
provided in the particles dictionary, as either a (N) or a
(Nx2) array if representing respectively kernels in position
space, or in phase space (using the same position and velocity
unit as that of the corresponding particles dictionary entry).
pname : string
Path to existing pre-formatted particles EBF files to use as input
for Galaxia. This keyword argument must be used in conjunction
with kname. Default to None if unused.
kname : string
Path to existing pre-formatted kernel EBF files to use as input
for Galaxia. This keyword argument must be used in conjunction
with pname. Default to None if unused.
photo_sys : string or list
Name(s) of the photometric system(s) Galaxia should use to generate
the survey. Default to DEFAULT_PSYS - refer to the package
constants. Available photometric systems can be found with the
photometry submodule - please refer to its documentation for
further details.
cmd_magnames : string
Names of the filters Galaxia should use for the color-magnitude
diagram box selection. The given string must meet the following
format: f"{band1},{band2}-{band3}" where band1 is the magnitude
filter and (band2, band3) are the filters that define the
band2-band3 color index. The filter names must correspond to
filters that are part of the first chosen photometric system in
photo_sys. Default to DEFAULT_CMD - refer to the package
constants.
simname : string
Optional name Galaxia should use for the input files. Default to
'sim'.
surveyname : string
Optional name Galaxia should use for the output files. Default to
'survey'.
fsample : float
Sampling rate from 0 to 1 for the resulting synthetic star survey.
1 returns a full sample while any value below returns partial
surveys. Default to 1.
ngb : int
Number of neighbouring particles Galaxia should consider. Default to
64.
k_factor : float
Scaling factor applied to the kernels lengths to adjust all
the kernels sizes uniformly. Lower values reduces the kernels
extents, while higher values increases them.
Default to 1 (no adjustment).
caching : bool
TODO
**kwargs
Additional keyword arguments to customize the survey. Refer to
constant PARFILE_TEMPLATE for all the possible keyword arguments.
Returns
----------
output : :obj:`Output`
Handler with utilities to utilize the output survey and its data.
"""
if pname is not None and kname is not None:
input = Input(pname=pname, kname=kname, caching=caching)
elif len(args) == 2:
input = Input(*args, name=simname, ngb=ngb, k_factor=k_factor, caching=caching)
survey = Survey(input, photo_sys=photo_sys, surveyname=surveyname)
output = survey.make_survey(cmd_magnames=cmd_magnames, fsample=fsample, **kwargs)
return output
if __name__ == '__main__':
raise NotImplementedError()