API Reference

This page documents the public API of ComPyTools.

Equation of state

class compytools.EoS(params, thermo, init=None, compo=None, micro=None, mr=None, indir=None, do_checks=True)

Bases: object

Holds data structures pertaining to thermodynamic and microphysics quantities for an equation of state (EoS).

Parameters:

params – Data structure described by compytools.tables.params.Params holding the grid parameters t, nb and yq
thermo – Idem but described by compytools.tables.params.Thermo that holds thermodynamic quantities
init – Holds information needed to initialise the CompOSE fortran routines (grid parameters, particles and microphysics treated etc.)
compo – Idem but described by compytools.tables.compo.Compo that holds the composition
micro – Idem but described by compytools.tables.micro.Micro that holds the microphysics quantities.
mr – Holds the global properties of a neutron star (NS), calculated with the supplied EoS.
indir – Directory containing CompOSE EoS inputs
do_checks – Set to true to perform quality checks on the data

Notes

CompOSE tables prefixed with .t, .nb and .yq (parameter files) and .thermo (thermodynamic quantities) are mandatory. Microphysics (.mr), composition (.compo) and NS properties (.mr) are optional.

dfdT(f): Calculate the partial derivative of f w.r.t the temperature, T. Here, f is a 3D numpy array of a quantity specified on a grid of temperature, baryon number density and charge fraction in that order.

dfdn(f): Calculate the partial derivative of f w.r.t the baryon number density, n. Here, f is a 3D numpy array of a quantity specified on a grid of temperature, baryon number density and charge fraction in that order.

classmethod from_compose(indir, prefix='eos', do_checks=True, ncores=1)

Read a set of CompOSE tables and store the data into the corresponding data frames.

Parameters:

indir – Directory containing tables
prefix – File name suffix, without the table extension
(bool) (do_checks) – Set to True to perform checks on data
(int) (ncores) – Num. of cores to use when loading the CompOSE tables. Defaults to 1. Set to a larger value for general purpose tables.

classmethod from_lorene(infile: str)

Read the equation of state from a Lorene formatted table, and store the associated grid parameters and thermodynamic variables into the corresponding CompOSE tables.

Parameters:: infile – Name of input Lorene file

Notes

Valid only for cold, beta-equilibrated matter.

classmethod from_rns(infile: str)

Read the equation of state from an RNS formatted table, and store the associated grid parameters and thermodynamic variables into the corresponding CompOSE tables.

Parameters:: infile – Name of input RNS file

Notes

Valid only for cold, beta-equilibrated matter.

to_compose(outdir, prefix='eos')

Write out the CompOSE tables for the supplied EoS.

Parameters:

outdir – Directory path where files should be written
prefix – Table prefix name, without the extensions

Interface to CompOSE

class compytools.Interface(eospath, nbconfig, thermo_choice=None, extra_thermo_choice=None, particle_choice=None, micro_choice=None, nuclear_choice=None, slice_betaeq=False, slice_fixed_entropy_per_baryon=None, tconfig=None, yqconfig=None, calc_interp_errors=False, debug=False)

Bases: object

Provide a Python interface to the CompOSE Fortran executable in order to extract an interpolated subset of data from an equation of state table.

Parameters:

eospath – Directory containing the CompOSE tables
nbconfig – Instance of GridSettings defining grid parameters on baryon number density
thermo_choice – List containing the integers associated with desired thermodynamic variables to extract
extra_thermo_choice – Idem, but for additional (optional) thermodynamic quantities that may be provided
particle_choice – List containing the integers associated with desired particle number fractions to extract
micro_choice – Idem, but for microphysics quantities
nuclear_choice – Idem, but for nuclear quadrupled quantities
slice_betaeq – Set to True to extract beta-equilibrated data from a general purpose table
slice_fixed_entropy_per_baryon – Extract a slice from the input table for a given value of the entropy per baryon.
tconfig – Instance of GridSettings defining the grid parameters for temperature
yqconfig – Idem, but for the charge particle fraction
calc_interp_errors – Set to True to output the estimated errors from interpolation
debug – Set to True to print to screen output from the CompOSE code

Notes

The options for slice_betaeq and slice_fixed_entropy_per_baryon are only valid for general purpose equations of state.

run(outfile='eos.table')

Run the CompOSE interface for the following steps: 1) input of the desired quantities, 2) definition of the grid in nB, T and Yq and 3) creation of the interpolated table.

Parameters:: outfile – Name of the output interpolated table. Defaults to eos.table.
Returns:: astropy QTable holding the interpolated data.
Return type:: table

show_interpolation_errors(tablepath='eos.table', figpath=None)

Plot the estimated errors resulting from the interpolation used by CompOSE to create the output table.

Parameters:

tablepath – Name of the output table holding interpolated quantities. Defaults to eos.table.
figpath – Path where figure showing the errors should be written to. If None, then the plot will be shown on screen.

Notes

The columns holding the estimated errors are found in the last 8 columns after the requested quantities in the output table.

class compytools.GridSettings(min: float = None, max: float = None, order: int = 2, npoints: int = 200, logscale: bool = True)

Bases: object

Defines the grid to be used for a given parameter (i.e. baryon number density, temperature or charge number fraction) during the interpolation implemented in CompOSE.

Parameters:

min (float) – Minimum grid value
max (float) – Maximum grid value
order (int) – Interpolation order (1: linear, 2: quadratic, 3: cubic)
npoints (int) – Number of points in the grid
logscale (bool) – Set to true to use log scale in grid points

Tables

Grid Parameters

class compytools.Grid(t: Param, nb: Param, yq: Param)

Bases: object

Collect together the grid parameter information for a given equation of state.

Parameters:

t (compytools.tables.param.Param) – Instance of Param holding the temperature grid info
nb (compytools.tables.param.Param) – Idem, but for the baryon number density
yq (compytools.tables.param.Param) – Idem, but for the charge number fraction

classmethod from_dataset(grid_data)

Read in all parameter grid information via user-supplied arrays for each parameter.

Parameters:

tarr – Numpy array containing temperature grid points
nbarr – Idem, but for baryon num. density
yqarr – Idem, but for charge num. fraction.

Returns:

Instance of Grid containing all parameter grid information

Return type:

cls

classmethod from_file(eospath, eosprefix='eos')

Read in all of the parameter grid information.

Parameters:

eospath – Path to the eos.[t,nb,yq] CompOSE grid parameter files
eosprefix – Prefix of the file name of the grid parameter file

Returns:

Returns instance of Grid holding

Return type:

cls

property meta: Collect meta-data associated with each of the grid parameters. This will be needed to populate the eos.init file.

write(outdir, prefix='eos')

Write out the temperature, baryon number density and charge number fraction to their respective output files.

Parameters:

outdir – Path where files should be written
prefix – Prefix for the output file names.

class compytools.GridData(t: UnitDescriptor = None, nb: UnitDescriptor = None, yq: UnitDescriptor = None)

Bases: object

Store the grid points for each of the grid parameters.

Parameters:

t (compytools.tables._utils.UnitDescriptor) – Array of temperature grid points
nb (compytools.tables._utils.UnitDescriptor) – Idem, but for the baryon number density
yq (compytools.tables._utils.UnitDescriptor) – Idem, but for the charge fraction

Thermodynamics

class compytools.Thermo(data=None, masked=False, names=None, dtype=None, meta=None, copy=True, rows=None, copy_indices=True, units=None, descriptions=None, **kwargs)

Bases: BaseTable

Store the thermo table data.

Parameters:: nucleons – Instance of Nucleons holding particle information stored in the header of the thermo table.

classmethod from_dataset(thermo_data)

Store the table from a supplied dataset of thermodynamic quantities.

Parameters:: thermo_data – Instance of ThermoData holding the thermodynamic quantities
Returns:: Instance of Thermo class
Return type:: cls

classmethod from_file(infile)

Read a thermo table in the CompOSE format.

Parameters:: infile – Path to the CompOSE thermo file
Returns:: Instance of Thermo class holding the thermo and particle information.
Return type:: cls

write(outdir, prefix='eos')

Write out thermo table to output.

Parameters:

outdir – Directory where table should be written to
prefix – Prefix for the output file name.

class compytools.ThermoData(grid_params: Grid, nucleons: Nucleons, pressure: UnitDescriptor = None, entropy_density: UnitDescriptor = None, charge_chemical_potential: UnitDescriptor = None, lepton_chemical_potential: UnitDescriptor = None, free_energy_density: UnitDescriptor = None, internal_energy_density: UnitDescriptor = None, baryon_chemical_potential: array | None = None, Qextra: dict = None)

Bases: BaseData

Hold user-supplied data associated with the thermo table.

Parameters:

nucleons (compytools.tables.thermo.Nucleons) – Instance of Nucleons holding nucleonic masses and lepton flag
pressure (compytools.tables._utils.UnitDescriptor) – In MeV/fm^3
entropy_density (compytools.tables._utils.UnitDescriptor) – In fm^-3
baryon_chemical_potential (numpy.array | None) – In MeV
charge_chemical_potential (compytools.tables._utils.UnitDescriptor) – In MeV
lepton_chemical_potential (compytools.tables._utils.UnitDescriptor) – In MeV
free_energy_density (compytools.tables._utils.UnitDescriptor) – In MeV/fm^3
internal_energy_density (compytools.tables._utils.UnitDescriptor) – In MeV/fm^3
Qextra (dict) – Dictionary holding additional thermodynamic quantities

class compytools.Nucleons(has_leptons: int, mn: UnitDescriptor = None, mp: UnitDescriptor = None)

Bases: object

Hold neutron (mn) and proton (mp) masses as well as the flag indicated whether leptons are considered for the input EoS.

Composition

class compytools.Compo(data=None, masked=False, names=None, dtype=None, meta=None, copy=True, rows=None, copy_indices=True, units=None, descriptions=None, **kwargs)

Bases: BaseTable

Store the compo table data within an instance of astropy’s QTable.

classmethod from_dataset(compo_data)

Read in the composition from a user-provided dataset.

Parameters:: compo_data – Instance of the CompoData class

classmethod from_file(infile, ncores=1)

Read a compo table in the CompOSE format.

Parameters:: infile – Path to the CompOSE compo file
Returns:: Instance of Compo class holding the compo data
Return type:: cls

write(outdir, prefix='eos')

Write out thermo table to output.

Parameters:

outdir – Directory where table should be written to
prefix – Prefix for the output file name.

class compytools.CompoData(grid_params: Grid, Iphase: array, nuclear_sets: dict, particle_fractions: UnitDescriptor = None)

Bases: BaseData

Hold the data associated with the composition for the eos.compo file.

Parameters:

Iphase (numpy.array) – Integers indicating the phase of matter within the neutron star
particle_fractions (compytools.tables._utils.UnitDescriptor) – Hold the fractions for the considered particle species
nuclear_sets (dict) – Hold the nuclear “quadrupled” data

class compytools.NuclearSet(Aav: UnitDescriptor = None, Zav: UnitDescriptor = None, Ynuc: UnitDescriptor = None)

Bases: object

Nuclear data for a given particle set.

Parameters:

Aav (compytools.tables._utils.UnitDescriptor) – Average mass number for representative nucleus
Zav (compytools.tables._utils.UnitDescriptor) – Idem, but for the proton number
Ynuc (compytools.tables._utils.UnitDescriptor) – Nuclear fraction

Microphysics

class compytools.Micro(data=None, masked=False, names=None, dtype=None, meta=None, copy=True, rows=None, copy_indices=True, units=None, descriptions=None, **kwargs)

Bases: BaseTable

Store the micro table data in astropy’s QTable.

classmethod from_dataset(micro_data)

Store user-supplied microphysics data into tabular form.

Parameters:: micro_data – Instance of MicroData dataclass

classmethod from_file(infile, ncores=1)

Read a micro table in the CompOSE format.

Parameters:

infile – Path to the CompOSE micro table
(int) (ncores) – Num. of cores to read the file

Returns:

Instance of Micro class holding the micro data

Return type:

cls

write(outdir, prefix='eos')

Write out micro table to output file.

Parameters:

outdir – Directory where the file should be written to
prefix – Prefix appended to the name of the output file

class compytools.MicroData(grid_params: Grid, microphysics: UnitDescriptor = None)

Bases: BaseData

Data class holding the data associated with the eos.micro file (composition of matter).

Parameters:: microphysics (compytools.tables._utils.UnitDescriptor) – Dictionary holding quantities associated with a microphysics quantity.

Neutron Star Properties

class compytools.NeutronStar(data=None, masked=False, names=None, dtype=None, meta=None, copy=True, rows=None, copy_indices=True, units=None, descriptions=None, **kwargs)

Bases: BaseTable

Store the global neutron star properties located in eos.mr within astropy’s QTable.

add_grid_points(params)

Append grid point values for temperature, baryon number density and charge number fraction to the thermo table.

Parameters:: params – Instance of compytools.tables.param.Grid containing the values for temperature, baryon num. density and charge fraction read in from eos.[t,nb,yq] resepctively.
Returns:: astropy QTable containing the appended table
Return type:: appended_table

classmethod from_dataset(ns_data: NeutronStarData): Read in the neutron star global properties from an instance of the NeutronStarData dataclass.

classmethod from_file(infile)

Read a thermo table in the CompOSE format.

Parameters:: infile – Path to the CompOSE thermo file
Returns:: Instance of NeutronStar class holding the neutron star data.
Return type:: cls

write(outdir, prefix='eos')

Write out the mr table to output.

Parameters:

outdir – Directory where the table should be written to
prefix – Prefix for the output file name.

class compytools.NeutronStarData(grid_params: Grid, thermo: Thermo, compo: Compo | None = None)

Bases: object

Calculate the neutron star (NS) static properties from the input equation of state (EoS). The class calculates the TOV family of solutions as well as key global neutron star properties via the lalsimulation package in lalsuite.

Parameters:

grid_parameters – Considered EoS grid parameters in temperature, baryon num. density and charge num. fraction
thermo (compytools.tables.thermo.Thermo) – EoS thermodynamic quantities
compo (compytools.tables.compo.Compo | None) – Compositional information

mass_grav

Sequence of NS gravitational masses in TOV family (Msun)

Type:: numpy.array

mass_baryonic

Ditto, but for the baryonic mass (Msun)

Type:: numpy.array

radius

NS radii in TOV family (km)

Type:: numpy.array

central_baryon_number_density: NS central baryon num. density in TOV family (1/fm^3)

central_pressure

NS central pressure in TOV famility (MeV/fm^3)

Type:: numpy.array

Lambda2

NS quadrupole tidal deformability (l=2)

Type:: numpy.array

Lambda3

NS octupole tidal deformability (l=3)

Type:: numpy.array

Lambda4

NS hexadeacpole tidal deformability (l=4)

Type:: numpy.array

mass_max

Maximum gravitational mass in family (Msun)

Type:: float

mass_dURCA

Min. NS gravitational mass at which the direct URCA process will occur

Type:: float

radius_mmax

NS radius associated with the maximum NS mass, R(mass_max) (km)

Type:: float

radius_14

NS radius associated with NS mass of 1.4 Msun (km)

Type:: float

Lambda_14

NS tidal deformability (l=2) associated the mass at 1.4 Msun

Type:: float

Lambda_gw170817

Effective tidal deformability associated with GW170817

Type:: float

static baryon_num_density_dURCA_criterion(nB, Yn, Yp, Ye)

Defines the criterion Yn^1/3 = Yp^1/3 + Ye^1/3 where the direct URCA process will occur.

Parameters:

nB – Baryon num. density
Yn – Function giving the neutron num. fraction in terms of nB
Yp – Idem, but for the proton num. fraction
Ye – Idem, but for the electron num. fraction

calc_baryon_num_density_dURCA(): Determine the minimum baryon num. density where the direct URCA process will occur.

Utility Functions

compytools.get_particle_mass(particle_name) → Quantity: Return the particle mass in MeV as an astropy quantity, i.e. the unit is automatically attached to the value. If available, use the masses as supplied within the PDG database.

compytools.show_microphysics() → None: Print the available microphysics quantities, their indices and units in tabulated form.

compytools.show_particles() → None: Print the available particle names and their indices in tabulated form.

compytools.show_particle_correlations() → None: Show the available two-particle correlations for superfluids and their indices in tabulated form.

compytools.summarise(eospath: str, tables: list = ['params', 'thermo', 'compo', 'micro'], prefix: str = 'eos') → None

Print to screen tables that summarise the quantities that are available for interpolation by the CompOSE Fortran routines.

Parameters:

eospath – Path to the CompOSE tables
tables – Provide a summary of the available quantities associated with a given table.
prefix – File name prefix for the CompOSE table names.