SPICE: API

Models

MeshModel

IcosphereModel

Constants

spice.models.mesh_model.LOG_G_NAMES: List[str] = ['logg', 'loggs', 'log_g', 'log_gs', 'log g', 'log gs', 'surface gravity', 'surface gravities', 'surface_gravity', 'surface_gravities']

List of valid parameter names for surface gravity. If the parameter name is not in this list, the surface gravity will be calculated using the mass and center positions.

spice.models.mesh_model.DEFAULT_LOS_VECTOR: jnp.ndarray = [0., 1., 0.]

Default line-of-sight vector (from Y direction).

spice.models.mesh_model.DEFAULT_ROTATION_AXIS: jnp.ndarray = [0., 0., 1.]

Default rotation axis (Z axis).

spice.models.mesh_model.DEFAULT_MAX_PULSATION_MODE_PARAMETER: int = 3

Default maximum pulsation mode.

spice.models.mesh_model.DEFAULT_FOURIER_ORDER: int = 5

Default Fourier order for pulsations.

Helper Functions

calculate_log_gs(mass: float, d_centers: ArrayLike, rot_velocities: ArrayLike = 0.0)

Calculates surface gravity (log g) values for mesh elements based on mass, center positions and rotation velocities.

The surface gravity is calculated using:

\[\log g = \log \left(\frac{GM}{R^2} - \frac{v_{rot}^2}{R}\right) - \log(9.80665)\]

where: - G is the gravitational constant (in solar units) - M is the mass in solar masses - R is the radius at each mesh point in solar radii - v_rot is the rotation velocity in km/s - 9.80665 converts from solar surface gravity units to cgs units (cm/s^2)

Parameters:

  • mass – Mass of the star in solar masses

  • d_centers – Center positions of mesh elements relative to star center

  • rot_velocities – Rotation velocities of mesh elements in km/s, defaults to 0.0

Returns:

Array of log g values for each mesh element

Mesh Transformations

Transform Functions

transform(mesh: MeshModel, vector: Float[Array, '3']) → MeshModel

Transform the position of a mesh model based on a given vector.

This function applies a transformation to the mesh model’s position by updating its center with the provided vector. PHOEBE models are considered read-only within SPICE.

Parameters:

  • mesh – The mesh model to be transformed

  • vector – The vector by which the mesh’s position is to be updated

Returns:

The transformed mesh model with its position updated

Raises:

ValueError – If the mesh model is an instance of PhoebeModel

update_parameter(mesh: MeshModel, parameter: str | int | ArrayLike, parameter_values: Float[Array, 'n_mesh_elements n_parameters'], parameter_names: List[str] = None) → MeshModel

Update a specific parameter or set of parameters in the mesh model.

This function allows updating one or multiple parameters of the mesh model. It can handle parameter specification by name (string), index (integer), or an array-like of indices.

Parameters:

  • mesh – The mesh model to be updated

  • parameter – The parameter(s) to update - can be name, index or array of indices

  • parameter_values – The new value(s) for the specified parameter(s)

  • parameter_names – List of parameter names used for the model

Returns:

The updated mesh model

Raises:

ValueError – If parameter name not found or mesh is PhoebeModel

update_parameters(mesh: MeshModel, parameters: List[str] | List[int], parameter_values: Float[Array, 'n_mesh_elements n_parameters'], parameter_names: List[str] = None) → MeshModel

Update multiple parameters in the mesh model simultaneously.

More efficient than calling update_parameter multiple times when updating several parameters at once.

Parameters:

  • mesh – The mesh model to be updated

  • parameters – List of parameter names or indices to update

  • parameter_values – New values for the specified parameters

  • parameter_names – List of parameter names used for the model

Returns:

The updated mesh model

Raises:

ValueError – If parameter names not found or mesh is PhoebeModel

Rotation Functions

evaluate_rotation(mesh: MeshModel, t: float) → MeshModel

Evaluate the rotation of a mesh model at a specific time.

Updates the mesh model’s rotation parameters based on the given time.

Parameters:

  • mesh – The mesh model to evaluate rotation for

  • t – The time at which to evaluate the rotation (seconds)

Returns:

The mesh model with updated rotation parameters

Raises:

ValueError – If mesh is PhoebeModel

evaluate_body_orbit(m: MeshModel, orbital_velocity: float) → MeshModel

Evaluate the effects of an orbit on a mesh model.

Parameters:

  • m – Mesh model of an orbiting body

  • orbital_velocity – Orbital velocity in km/s

Returns:

Mesh model with updated parameters

Pulsation Functions

add_pulsations(m: MeshModel, m_orders: Float[Array, 'n_pulsations'], n_degrees: Float[Array, 'n_pulsations'], periods: Float[Array, 'n_pulsations'], fourier_series_parameters: Float[Array, 'n_pulsations n_terms 2'], pulsation_axes: Float[Array, 'n_pulsations 3'] = None, pulsation_angles: Float[Array, 'n_pulsations'] = None) → MeshModel

Adds multiple pulsation effects to a mesh model using spherical harmonics and Fourier series parameters.

Parameters:

  • m – The mesh model to add pulsation effects to

  • m_orders – Array of orders (m) of the spherical harmonics

  • n_degrees – Array of degrees (n) of the spherical harmonics

  • periods – Array of pulsation periods in seconds

  • fourier_series_parameters – Array of dynamic parameters for the Fourier series

  • pulsation_axes – Array of pulsation axes (defaults to rotation axis)

  • pulsation_angles – Array of pulsation angles (defaults to zero)

Returns:

The mesh model with updated pulsation parameters

Raises:

ValueError – If mesh is PhoebeModel or input arrays have inconsistent lengths

reset_pulsations(m: MeshModel) → MeshModel

Resets the pulsation parameters of a mesh model to non-pulsating model values.

Parameters:

m – The mesh model to reset pulsation parameters for

Returns:

The mesh model with pulsation parameters reset

Raises:

ValueError – If mesh is PhoebeModel

evaluate_pulsations(m: MeshModel, t: float) → MeshModel

Evaluates and updates the mesh model with pulsation effects at a specific time.

Calculates pulsation effects using Fourier series parameters for both static and dynamic components. Updates the mesh with calculated offsets and velocities.

Parameters:

  • m – The mesh model to evaluate pulsations for

  • t – The time at which to evaluate the pulsations

Returns:

The mesh model updated with pulsation effects

Raises:

ValueError – If mesh is PhoebeModel

Mesh View

Mesh View Functions

get_grid_spans(m1: MeshModel, m2: MeshModel, n_cells_array: ArrayLike) → ArrayLike

Calculate grid cell spans for different grid sizes.

For each number of cells in n_cells_array, calculates the span (width/height) of grid cells that would cover the projected area of both meshes. Returns the minimum of x and y spans to ensure square grid cells.

Parameters:

  • m1 – First mesh model with cast_vertices and faces

  • m2 – Second mesh model with cast_vertices and faces

  • n_cells_array – Array of different grid cell counts to try

Returns:

Array of grid cell spans corresponding to each n_cells value

get_mesh_view(mesh: MeshModel, los_vector: Float[Array, '3']) → MeshModel

Cast 3D vectors of centers and center velocities to the line-of-sight.

Parameters:

  • mesh – Properties to be cast (n, 3)

  • los_vector – LOS vector (3,)

Returns:

mesh with updated los_vector, mus, and los_velocities

visible_area(vertices1: Float[Array, 'n_vertices 3'], vertices2: Float[Array, 'n_vertices 3']) → Float[Array, 'n_vertices']

Calculate visible area between two sets of vertices.

Parameters:

  • vertices1 – First set of vertices

  • vertices2 – Second set of vertices

Returns:

Area of visible region

resolve_occlusion(m1: MeshModel, m2: MeshModel, grid: Grid) → MeshModel

Calculate the occlusion of m1 by m2.

Parameters:

  • m1 – occluded mesh model

  • m2 – occluding mesh model

  • grid – grid for calculation optimization

Returns:

m1 with updated visible areas

Spots

Spot Functions

add_spot(mesh: MeshModel, spot_center_theta: float, spot_center_phi: float, spot_radius: float, parameter_delta: float, parameter_index: int, smoothness: float = 1.0) → MeshModel

Add a spot to a mesh model based on spherical coordinates and smoothness parameters.

This function applies a modification to the mesh model’s parameters to simulate the presence of a spot. The spot is defined by its center (in spherical coordinates), its radius, and a differential parameter that quantifies the change induced by the spot. The smoothness parameter allows for a gradual transition at the spot’s edges.

Parameters:

  • mesh – The mesh model to which the spot will be added

  • spot_center_theta – The theta (inclination) coordinate of the spot’s center, in radians

  • spot_center_phi – The phi (azimuthal) coordinate of the spot’s center, in radians

  • spot_radius – The angular radius of the spot, in radians

  • parameter_delta – The difference in the parameter value to be applied within the spot

  • parameter_index – The index of the parameter in the mesh model that will be modified

  • smoothness – Factor controlling the smoothness of the spot’s edge, defaults to 1.0

Returns:

The modified mesh model with the spot applied

Raises:

ValueError – If mesh is a PhoebeModel

add_spots(mesh: MeshModel, spot_center_thetas: Float[Array, 'n_spots'], spot_center_phis: Float[Array, 'n_spots'], spot_radii: Float[Array, 'n_spots'], parameter_deltas: Float[Array, 'n_spots'], parameter_indices: Int[Array, 'n_spots'], smoothness: Float[Array, 'n_spots'] = None) → MeshModel

Add multiple spots to a mesh model based on spherical coordinates and smoothness parameters.

Parameters:

  • mesh – The mesh model to which the spots will be added

  • spot_center_thetas – Array of theta coordinates of spot centers, in radians

  • spot_center_phis – Array of phi coordinates of spot centers, in radians

  • spot_radii – Array of angular radii of spots, in radians

  • parameter_deltas – Array of parameter value differences for each spot

  • parameter_indices – Array of parameter indices to modify for each spot

  • smoothness – Array of edge smoothness factors for each spot

Returns:

The modified mesh model with all spots applied

Raises:

ValueError – If mesh is a PhoebeModel

add_spherical_harmonic_spot(mesh: MeshModel, m_order: Int | Float, n_degree: Int | Float, param_delta: Float, param_index: Float, tilt_axis: Float[Array, '3'] = None, tilt_degree: Float = None) → MeshModel

Add a spherical harmonic variation to a parameter of the mesh model.

Creates a spot-like feature using spherical harmonic function Y_n^m(θ,φ) to modify surface parameters.

Parameters:

  • mesh – The mesh model to modify

  • m_order – Order (m) of spherical harmonic, must be ≤ n_degree

  • n_degree – Degree (n) of spherical harmonic

  • param_delta – Maximum amplitude of parameter variation

  • param_index – Index of parameter to modify

  • tilt_axis – Optional axis for tilting the pattern

  • tilt_degree – Optional tilt angle in degrees

Returns:

Modified mesh model with spherical harmonic variation

Raises:

ValueError – If m_order > n_degree or mesh is PhoebeModel

add_spherical_harmonic_spots(mesh: MeshModel, m_orders: Float[Array, 'n_orders'], n_degrees: Float[Array, 'n_orders'], param_deltas: Float[Array, 'n_orders'], param_indices: Float[Array, 'n_orders'], tilt_axes: Float[Array, 'n_orders 3'] | None = None, tilt_angles: Float[Array, 'n_orders'] | None = None) → MeshModel

Add multiple spherical harmonic spots to a mesh model.

Parameters:

  • mesh – The mesh model to modify

  • m_orders – Array of m indices for spherical harmonics

  • n_degrees – Array of n indices for spherical harmonics

  • param_deltas – Array of modification strengths

  • param_indices – Array of parameter indices to modify

  • tilt_axes – Optional array of tilt axes for each spot

  • tilt_angles – Optional array of tilt angles in radians

Returns:

Modified mesh model with all harmonic spots

Raises:

ValueError – If mesh is PhoebeModel or tilt parameters mismatched