PolytropicStarModel#

class pisces.models.stars.polytropes.PolytropicStarModel(filepath: str | Path, *args, **kwargs)[source]#

Spherical polytropic stellar structure model.

This model represents a self-gravitating, spherically symmetric star in hydrostatic equilibrium, governed by a polytropic equation of state:

\[P = K \rho^{1 + 1/n}\]

where \(n\) is the polytropic index and \(K\) is a constant determined by core conditions.

The stellar structure is computed by solving the Lane-Emden equation:

\[\frac{1}{\xi^2} \frac{d}{d\xi} \left( \xi^2 \frac{d\theta}{d\xi} \right) = -\theta^n\]

where \(\theta(\xi)\) is the dimensionless density and \(\xi\) is the dimensionless radius.

Fields#

The following physical fields are computed and stored in the model:

Polytropic Star Model Fields#
Field Name	Description	Symbol
`radii`	Radial coordinate grid	\(r\)
`Theta`	Lane-Emden solution function	\(\Theta(\xi)\)
`density`	Mass density profile	\(\rho(r)`\)
`pressure`	Pressure profile	\(P(r)\)
`temperature`	Temperature profile	\(T(r)\)
`mass`	Enclosed mass profile	\(M(<r)\)
`potential`	Gravitational potential	\(\Phi(r)\)
`gravitational_field`	Gravitational acceleration	\(g(r) = -\frac{d\Phi}{dr}\)

Metadata#

The following pieces of metadata are computed and stored in the model:

Polytropic Star Model Metadata#
Field Name	Description	Symbol
`K_constant`	Polytropic constant	\(K\)
`alpha_constant`	Lane-Emden scale length	\(\alpha\)
`stellar_radius`	Radius at truncation point	\(R_\star\)
`total_mass`	Final enclosed mass	\(M_\star\)
`polytropic_index`	Polytropic index	\(n\)
`core_density`	Central density	\(\rho_c\)
`core_temperature`	Central temperature	\(T_c\)
`mean_molecular_weight`	Mean molecular weight	\(\mu\)
`date_created`	Timestamp of model creation	\(t_{\mathrm{create}}\)
`__model_class__`	Model class name	\(\mathrm{ModelClass}\)

Methodology#

The model can be constructed in one of two ways:

Core Density + Core Temperature

Hint

This mode is available through from_density_and_temperature().

Specify the central density \(\rho_c\) and central temperature \(T_c\).
Use these to compute the polytropic constant \(K\) and scale length \(\alpha\).
Solve the Lane-Emden equation for the given index \(n\).
Use \(\theta(\xi)\) to compute physical profiles:
- Density: \(\rho(r) = \rho_c \theta^n\)
- Pressure: \(P(r) = K \rho^{1 + 1/n}\)
- Temperature: from ideal gas law
- Enclosed mass via: \(M(<r) = \int_0^r 4\pi r^2 \rho(r) \, dr\)
- Potential: using total mass and gravitational integration

Total Mass + Radius

Hint

This mode is available through from_mass_and_radius().

Specify the total stellar mass \(M_{\rm tot}\) and radius \(R\).
Solve Lane-Emden equation to obtain \(\xi_{\rm max}\) and compute:

\[\alpha = \frac{R}{\xi_{\rm max}}\]
Use Lane-Emden integral to solve for core density:

\[\rho_c = \frac{M_{\rm tot}}{4\pi \alpha^3 \int_0^{\xi_{\rm max}} \theta^n \xi^2 d\xi}\]
Compute central temperature via hydrostatic equilibrium and ideal gas law:

\[T_c = \rho_c \cdot \frac{4\pi \mu m_p G \alpha^2}{(n+1) k_B}\]
Pass results to density+temperature constructor to build the model.

Assumptions#

Spherical symmetry: all fields are radial functions.
Polytropic equation of state: gas follows \(P = K \rho^{1 + 1/n}\).
Hydrostatic equilibrium: neglects rotation, magnetic fields, or turbulence.
Ideal gas law: used to relate temperature, pressure, and density.
Fixed mean molecular weight: assumed constant throughout the star.

Methods

`__init__`(filepath, args, *kwargs)	Load a Pisces model from an existing HDF5 file.
`add_field`(name[, element_shape, units, ...])	Add a new physical field to the model.
`add_profile`(name, profile[, overwrite])	Add a new analytic profile to the model.
`compute_parameters_from_mass_and_radius`(...)	Compute the central density and temperature of a polytropic star from its mass and radius.
`copy_field`(old_name, new_name)	Create a duplicate of an existing field under a new name.
`copy_profile`(old_name, new_name)	Create a duplicate of an existing profile under a new name.
`from_components`(filepath, grid, fields, ...)	Create and save a Pisces model from in-memory components.
`from_density_and_temperature`(filename, ...)	Construct a polytropic star model from core density and core temperature.
`from_mass_and_radius`(filename, mass, radius)	Construct a polytropic star model from its total mass and radius.
`generate_particles`(filename, num_particles)	Convert this galaxy cluster model into a particle dataset.
`get_active_hooks`([names])	Return all active hook classes mixed into the model.
`get_all_hooks`([names])	Return all hook classes mixed into the model, regardless of activation status.
`get_field`(name)	Retrieve a physical field by name.
`get_hook_class`(hook_name)	Return the hook class associated with a given hook name.
`get_hook_description`(hook_cls)	Return the human-readable description for a given hook class.
`get_hook_name`(hook_cls)	Return the symbolic name for a given hook class.
`get_profile`(name)	Retrieve an analytic profile by name.
`has_hook`(hook)	Check if a given hook is mixed into the model (regardless of activation status).
`list_fields`()	List all physical fields currently stored in the model.
`list_profiles`()	List all analytic profiles currently stored in the model.
`remove_field`(name)	Remove a physical field from the model.
`remove_profile`(name)	Remove an analytic profile from the model.
`rename_field`(old_name, new_name)	Rename an existing field in the model.
`rename_profile`(old_name, new_name)	Rename an existing profile in the model.

Attributes

`active_grid_axes`	List of active axes in the model's grid.
`config`	Model-specific configuration settings.
`coordinate_system`	The coordinate system of the model's grid.
`fields`	Model field buffers.
`grid`	The spatial grid of the model.
`handle`	The open HDF5 file handle.
`logger`	Logger interface for this model.
`metadata`	Model metadata dictionary.
`path`	The path to the model's HDF5 file.
`profiles`	Model profile objects.