CoolDwarf.star package

Submodules

CoolDwarf.star.sphere module

sphere.py

This module contains the VoxelSphere class, which represents a 3D voxelized sphere model for a star. The VoxelSphere class provides methods for computing various physical properties of the star, including its radius, enclosed mass, energy flux, and more.

The VoxelSphere class uses an equation of state (EOS) for the star, which can be inverted to compute pressure and temperature grids. It also provides methods for updating the energy of the star and recomputing its state.

The module imports several utility functions and constants from the CoolDwarf package, as well as classes for handling errors related to energy conservation and non-convergence.

All units are in non log space cgs unless otherwise specified.

Dependencies

  • numpy

  • tqdm

  • torch

  • cupy

  • pandas

  • scipy.interpolate

  • CoolDwarf.utils.math

  • CoolDwarf.utils.const

  • CoolDwarf.utils.format

  • CoolDwarf.EOS

  • CoolDwarf.model

  • CoolDwarf.err

Classes

  • VoxelSphere: Represents a 3D voxelized sphere model for a star.

Functions

  • default_tol: Returns a dictionary of default numerical tolerances for the cooling model.

Exceptions

  • EnergyConservationError: Raised when there is a violation of energy conservation.

  • NonConvergenceError: Raised when a computation fails to converge.

  • VolumeError: Raised when the volume error is greater than the tolerance.

  • ResolutionError: Raised when the resolution is insufficient.

Example Usage

>>> from CoolDwarf.star import VoxelSphere
>>> from CoolDwarf.utils.plot import plot_3d_gradients, visualize_scalar_field
>>> from CoolDwarf.utils import setup_logging
>>> from CoolDwarf.EOS import get_eos
>>> from CoolDwarf.opac import KramerOpac
>>> from CoolDwarf.EOS.invert import Inverter

>>> import numpy as cp
>>> import matplotlib.pyplot as plt

>>> setup_logging(debug=True)

>>> EOS = get_eos("EOS/TABLEEOS_2021_Trho_Y0292_v1", "CD21")
>>> opac = KramerOpac(0.7, 0.02)
>>> sphere = VoxelSphere(8e31, "BrownDwarfMESA/BD_TEST.mod", EOS, opac, radialResolution=50, altitudinalResolition=10, azimuthalResolition=20)
>>> sphere.evolve(maxTime=3.154e+7, dt=86400)
>>> print(f"Surface Temp: {sphere.surface_temperature_profile}")
class CoolDwarf.star.sphere.VoxelSphere(mass, model, EOS, opac, pressureRegularization=1e-05, radialResolution=10, azimuthalResolition=10, altitudinalResolition=10, t0=0, X=0.75, Y=0.25, Z=0, tol={'maxEChange': 0.0001, 'relax': 1e-06, 'volCheck': 0.01}, modelFormat='mesa', alpha=1.901, mindt=0.1, cfl_factor=0.5, imodelOut=False, imodelOutCadence=1000, imodelOutCadenceUnit='s', fmodelOut=True, outputDir='.')

Bases: object

A class to represent a 3D voxelized sphere model for a star.

Raises:
EnergyConservationError

If there is a violation of energy conservation.

NonConvergenceError

If a computation fails to converge.

Attributes:
CONSTdict

A dictionary of physical constants.

massfloat

Returns the mass grid for the star.

modelstr

The name of the stellar model to use.

modelFormatstr

The format of the stellar model. Default is ‘mesa’. May also be ‘dsep’.

EOSEOS

The equation of state for the star.

opacOpac

The opacity of the star.

pressureRegularizationfloat

A regularization parameter for the pressure computation.

radialResolutionint

The number of radial divisions in the voxelized sphere.

azimuthalResolutionint

The number of azimuthal divisions in the voxelized sphere.

t0float

The initial time of the star.

Xfloat

The hydrogen mass fraction of the star.

Yfloat

The helium mass fraction of the star.

Zfloat

The metal mass fraction of the star.

alphafloat

The mixing length parameter.

mindtfloat

The minimum timestep for the star.

cfl_factorfloat

The Courant-Friedrichs-Lewy factor for the star.

toldict

A dictionary of numerical tolerances for the cooling model. Keys are ‘relax’ and ‘maxEChange’. Default is {‘relax’: 1e-6, ‘maxEChange’: 1e-4, ‘volCheck’: 1e-2}. Relax is the relaxation parameter for the energy update. MaxEChange is the maximum fractional change in energy allowed per timestep. volCheck is the maximum fractional error in volume allowed.

Methods

Cp([delta_t])

Computes the specific heat capacity of the star at constant pressure.

as_dict()

Returns a dictionary representation of the star. Returns ------- dict: A dictionary representation of the star.

as_pandas()

Returns a pandas DataFrame representation of the star. Returns ------- pandas.DataFrame: A DataFrame representation of the star.

evolve([maxTime, dt, pbar, callback, cbc, cargs])

Evolves the star over a specified time period using a specified timestep.

inject_surface_energy(energy, theta0, phi0, ...)

Injects energy into the star at a specified coordinate subtending some solid angle.

save(filename)

Save to a binary file format.

timestep([userdt])

Computes a timestep for the star based on the CFL condition or the user-specified timestep.
CONST = {'G': 6.6743e-08, 'R': 83145000.0, 'a': 7.5646e-15, 'c': 29979245800.0, 'h': 6.626196e-27, 'kB': 1.3807e-16, 'mH': 1.00784, 'mHe': 4.002602, 'sigma': 5.670374419e-05}
Cp(delta_t: float = 1)

Computes the specific heat capacity of the star at constant pressure.

Parameters:
delta_tfloat, optional

A small change in temperature for computing the specific heat capacity. Default is 1e-5.

Returns:
xp.ndarray: The specific heat capacity of the star at constant pressure.
property age

Returns the age of the star. Returns ——-

float: The age of the star.

as_dict()

Returns a dictionary representation of the star. Returns ——-

dict: A dictionary representation of the star.

as_pandas()

Returns a pandas DataFrame representation of the star. Returns ——-

pandas.DataFrame: A DataFrame representation of the star.

property cfl_dt: float

Computes the timestep based on the Courant-Friedrichs-Lewy (CFL) condition.

Returns:
float: The timestep based on the CFL condition.
property convective_energy_flux: Tuple[ndarray, ndarray, ndarray]

Computes the convective energy flux in the radial, azimuthal, and altitudinal directions. We take a mixing length theory approach to compute the convective energy flux.

The convective enertgy flux for some coordinate direction is given by: Fconv = (1/2) * rho * Cp * v * (TGrad - ad) where rho is the density, Cp is the specific heat capacity, v is the convective velocity along that coordinate axis, TGrad is the temperature gradient along that coordinte axis, and ad is the adiabatic gradient.

Returns:
tuple: A tuple of 3D arrays representing the convective energy flux in the radial, azimuthal, and altitudinal directions.
The arrays are in the form of (FconvR, FconvTheta, FconvPhi).
property convective_overturn_timescale: Tuple[ndarray, ndarray, ndarray]

Computes the convective overturn timescale in the radial, azimuthal, and altitudinal directions. The convective overturn timescale is given by the mixing length divided by the convective velocity.

Returns:
tuple: A tuple of 3D arrays representing the convective overturn timescale in the radial, azimuthal, and altitudinal directions.
The arrays are in the form of (tauR, tauTheta, tauPhi).
property convective_velocity: Tuple[ndarray, ndarray, ndarray]

Computes the convective velocity in the radial, azimuthal, and altitudinal directions. The convective velocity is given by the mixing length divided by two times the square root of the product of the gravitational acceleration and the difference between the adiabatic gradient and the temperature gradient.

Returns:
tuple: A tuple of 3D arrays representing the convective velocity in the radial, azimuthal, and altitudinal directions.
The arrays are in the form of (vR, vTheta, vPhi).
property dEdt: ndarray

Computes the time derivative of the energy for the star.

Returns:
xp.ndarray: The time derivative of the energy for the star.
property density: ndarray

Returns the density grid for the star. Returns ——-

xp.ndarray: The density grid for the star.

property enclosed_mass

Computes the enclosed mass of the star as a function of radius.

Returns:
interp1d: A 1D interpolation function for the enclosed mass.
property energy: ndarray

Returns the energy grid for the star.

property energy_flux: Tuple[Tuple[ndarray, ndarray, ndarray], Tuple[ndarray, ndarray, ndarray]]

Computes the energy flux in the radial, azimuthal, and altitudinal directions.

Returns:
tuple: A tuple of 3D arrays representing the energy flux in the radial, azimuthal, and altitudinal directions.
The arrays are in the form of ((fluxR, fluxTheta, fluxPhi), (fluxR, fluxTheta, fluxPhi)).
property evolutionary_steps

Returns the number of evolutionary steps taken by the star. Returns ——-

int: The number of evolutionary steps taken by the star.

evolve(maxTime: float = 31540000.0, dt: float = 86400, pbar=False, callback=<function VoxelSphere.<lambda>>, cbc=1, cargs: tuple = ())

Evolves the star over a specified time period using a specified timestep.

Parameters:
maxTimefloat, optional

The maximum time to evolve the star. Default is 3.154e+7.

dtfloat, optional

The timestep to use for the evolution. Default is 86400.

pbarbool, optional

Display a progress bar for the evolution. Default is False.

callbackfunction, optional

A callback function to call at each timestep. Default is a function that does nothing. Function will be called after each timestep. The star object will be passed as an argument. The function signature must be callback(star, *args).

cbcint, optional

The cadence at which to call the callback function. 1 meaning every time step. 2 would be every other timestep and so on…

cargstuple, optional

Additional arguments to pass to the callback function.

property flux_divergence: Tuple[Tuple[ndarray, ndarray, ndarray], Tuple[ndarray, ndarray, ndarray]]

Computes the divergence of the energy flux in the radial, azimuthal, and altitudinal directions.

Returns:
tuple: A tuple of 3D arrays representing the divergence of the energy flux in the radial, azimuthal, and altitudinal directions.
The arrays are in the form of ((delFConvR, delFConvTheta, delFConvPhi), (delFRadR, delFRadTheta, delFRadPhi)).
property gradRadEr: Tuple[ndarray, ndarray, ndarray]

Computes the radiative energy gradient.

Returns:
tuple: A tuple of 3D arrays representing the radiative energy gradient in the radial, azimuthal, and altitudinal directions.
The arrays are in the form of (delErR, delErTheta, delErPhi).
property gradT: Tuple[ndarray, ndarray, ndarray]

Computes the temperature gradients in the radial, azimuthal, and altitudinal directions.

Returns:
tuple: A tuple of 3D arrays representing the temperature gradients in the radial, azimuthal, and altitudinal directions.
The arrays are in the form of (tGradR, tGradTheta, tGradPhi).
property gravitational_acceleration: ndarray

Computes the gravitational acceleration for the star. If the mass grid is zero at a given grid point, the gravitational acceleration is set to infinity to deal with the singularity at r=0.

Returns:
xp.ndarray: The gravitational acceleration for the star.
inject_surface_energy(energy, theta0, phi0, omega)

Injects energy into the star at a specified coordinate subtending some solid angle.

Parameters:
energyfloat

The energy to inject into the star. This must be given in no log cgs units.

theta0float

The azimuthal coordinate of the injection point.

phi0float

The altitudinal coordinate of the injection point.

omegafloat

The solid angle subtended by the injection point.

property mass: ndarray

Returns the mass grid for the star. Returns ——-

xp.ndarray: The mass grid for the star.

property mixing_length: ndarray

Computes the mixing length for the star.

Returns:
xp.ndarray: The mixing length for the star.
property pressure: ndarray

Returns the pressure grid for the star. Returns ——-

xp.ndarray: The pressure grid for the star.

property pressure_scale_height: ndarray

Computes the pressure scale height for the star.

Returns:
xp.ndarray: The pressure scale height for the star.
property radiative_energy_flux: Tuple[ndarray, ndarray, ndarray]

Computes the radiative energy flux in the radial, azimuthal, and altitudinal directions.

Returns:
tuple: A tuple of 3D arrays representing the radiative energy flux in the radial, azimuthal, and altitudinal directions.
The arrays are in the form of (fluxRadR, fluxRadTheta, fluxRadPhi).
property radius

Returns the radius of the star.

Returns:
float: The radius of the star.
save(filename: str) → bool

Save to a binary file format. Currently the model format is being defined in the joplin notebook I am using to keep track of development.

Parameters:
filenamestr

The filename to save the star to.

Returns:
bool: A flag indicating if the save was successful.
property surface_temperature_profile: ndarray

Computes the surface temperature profile for the star.

Returns:
xp.ndarray: The surface temperature profile for the star.
property temperature: ndarray

Returns the temperature grid for the star.

Returns:
xp.ndarray: The temperature grid for the star.
timestep(userdt: float = inf) → float

Computes a timestep for the star based on the CFL condition or the user-specified timestep. The actual timestep used is the minimum of the CFL timestep and the user-specified timestep, and this will be returned.

The energy of the star is then updated based on the computed timestep. Following this, the energy is used to invert the EOS and update the temperature and density grids. The energy conservation is checked, and if the energy change is greater than the maximum energy change tolerance, the timestep is halved and the energy, temperature, density, and pressure grids are reset to their initial values.

When the energy conservation is satisfied, the evolutionary step is incremented, and the time is updated based on the the acutal timestep used. The timestep is then returned.

Parameters:
userdtfloat, optional

The user-specified timestep. Default is xp.inf.

Returns:
float: The actual timestep used for the star.
Raises:
EnergyConservationError

If there is a violation of energy conservation.

NonConvergenceError

If the model fails to converge after a certain number of timesteps.

Examples

>>> star = VoxelSphere(...)
>>> star.timestep()
CoolDwarf.star.sphere.default_tol()

Returns a dictionary of default numerical tolerances for the cooling model.

Returns:
dict: A dictionary of default numerical tolerances for the cooling model.
Keys are ‘relax’, ‘maxEChange’, and ‘volCheck’.

Module contents