sevnpy.sevn.Star

Bases: object

The class Star is used to initialise a star and evolve it using the SEVN backend.

Initilisation

The basic parameter used to initialise the star are the zero-age-main-seqeunce mass Mzams and Z. These two values identify a unique interpolating track (see the SEVN userguide) for the evolution. The user need also to define the initial age of the star (set by defaul to “zams”). In addition, the used can set the initial stellar rotation, the snmodel used to create the stellar remnant. The user can also decide to modify the stadandard property of the interpolating track setting the current value of the total mass and mass of the cores. In addition to a normal H-star, the parameter star_flag can be used to intialise a pureHe star (in this case the Mzams value is the mass of the star at the beginning of the core helium burning), or a remnant such as a black hole, a neutron star or a whith dwarf (in this case Mzams represents the mass of the remnant). See the __init__() method for additional details.

The Star can also be initialised from the current properties of another star using the class method from_star(). Similarly a star can create a new Star instance from the current properties using the method to_star()

Any instance of the class Star needs to be created within an initialised SEVNmanager, otherwise an error is raised, example:

>>> from sevnpy.sevn import Star, SEVNmanager
>>> s=Star(10,0.02) # !ERROR, SEVNmanager is not initialised yet
>>> SEVNmanager.init()
>>> s=Star(10,0.02) # !OK, SEVNmanager is initiliased

When a Star instance is created it get the SEVNparameters from the current SEVNmanager initialisation. The Star evolution methods can be call only within the same SEVNmanager session, is the SEVNmanager is re-intialised any further evolution will raise an error, e.g.

>>> from sevnpy.sevn import Star, SEVNmanager
>>> # OK!
>>> SEVNmanager.init()
>>> s=Star(10,0.02)
>>> s.evolve()
>>> SEVNmanager.close()
>>> # Error!
>>> SEVNmanager.init({"ce_alpha:2"})
>>> s.evolve() #Error, the SEVNmanager has been reinitialised with respect to the Star initialisation

Get the stellar properties

The stellar properties are stored in an internal evolution table reporting the star properties at each time step. After the initilisation the evolution table contains one single row storing the initial stellar properties. The methods getp() and getp_array() can be used to retrieve the stellar properties as a pandas DataFrame and a numpy array, respectively. As a shortchut the getp() method can be called directly using the [] operator on the class instance, e.g.

>>> s=Star(10,0.02)
>>> s["Mass"] #return the Mass column from the current evolved Dataframe
>>> s["Worldtime","Mass","Radius"] #return the Worldtime,Mass and Radius columns from the  current evolved Dataframe

Single stellar evolution

The main purpose of the class Star is to faciliate the call of the SEVN evolution backend. this is done through the methods evolve() and evolve_for():

evolve(): Evolve the Star from the initial age (the one set at the initilisation), up to
a given time in input. During the evolution, the internal evolution table is filled with properties at each timestep. Each time the method is called, the evolve_table will be overwritten.

evolve_for(): Evolve the Star for an amount of time in input starting from the current
properties of the star, e.g. the last row in the evolution table. This method do not overwrite the evolution table rather it appends the new value to it.

When the star is evolved, the log messages (see SEVN documentation) are also internally store. To retrieve it use the property log(). Same as for the evolution table, each call to evolve() ovewrites the log, while calls to evolve_for() append their log messages.

Remnant

It is possibile to retreive directly the property of the remnant generated by the Star using the method get_remnant(). Internally a complete evolution will be performed, but whitout updating or overwriting the evolution table, therefore the Star status will not be changed. The method returns a DataFrame with all the properties of the remnant.

Methods

__init__

Initialise a Star instance.

evolve

Main evolve function.

evolve_for

Evolve the star from the current status for a given time interval.

from_star

Construct a new Star instance from the current state (i.e. the last points in the current evolution dataframe) of a Star in input.

get_SN_kick

Get the info about the SN kick velocities.

get_remnant

Get the property of the remnant.

getp

Return the stellar properties as a Pandas DataFrame.

getp_array

Return the stellar properties as a numpy array.

look_at_track

The method returns the properties of the interpolating tracks followed by the star at a given time t.

reinit

Use this method to re-initialise the star changing the initial properties, except for Mzams and Z.

to_star

Create a new Star instance from the current state (i.e. the last points in the current evolution dataframe).

property ID: int: ID identifier of this object.

property Mzams: float: Zero-age-main-sequence mass used to initialise the star [Msun]

property SEVNmanager_ID: int: Return the ID of the SEVNmanager associated with this Star at the Star initialisation

property Zmet: float: Stellar metallicity in input

__getitem__(item)[source]: Same as getp() but with mode set to “all” and t is None

Initialise a Star instance. During the initialisation, the evolve table will be filled with one single row containing the initial Stellar properties.

Parameters:

Mzams – Zero-age-main-sequence mass of the star (or better of the interpolating track) [Msun]
Z – Metallicity of the star (or better of the interpolating track)
spin – Initial stellar spin, i.e. the ratio between the rotational angular velocity and the critical angular velocity
tini –
Initial age of the star to initialise, the options are:
- age number, a float in Myr
- phase initialisation, initialise the star at a given phase, using the string:
  - zams: Zero age main sequence
  - tams: Terminal main sequence
  - shb: shell H burning
  - cheb: core helium burning
  - tcheb: terminal core helium burning
  - sheb: shel He burning
- percentage phase initialisation, using the string %<P>:<IDphase> where <P> is the percentage of the phase, and <IDphase> is the integer ID depending on the phase:
  - 1: zams
  - 2: tams
  - 3: shb
  - 4: cheb
  - 5: tcheb
  - 6: sheb
  so, for example to initialise the Star at 48% of the cheb phase: %48:4
snmodel – SEVN snmodel to use to transform a Star to a remnant (see the SEVN userguide)
star_flag –
String that defines the type of Star:
- H: initialise an Hydrogen star
- HE: initialise a pureHe star (use the pureHe trakcs, see the SEVN userguide)
- HEWD: initialise a Helium White Dwarf remnant with mass equal to Mzams
- COWD: initialise a Carbon-Oxygen White Dwarf remnant with mass equal to Mzams
- ONEWD: initialise a Oxygen-Neon White Dwarf remnant with mass equal to Mzams
- NS: initialise a Neutron Star with mass equal to Mzams
- BH: initialise a Black Hole with mass equal to Mzams
rseed – Random seed to be used in the stellar evolution, if None a random seen will be automatically generated
ID – ID of the Star, if None a ID will be automatically assigned
Mass –

Use this value to modify the initial Mass of the star [Msun].
If None the Mass will be the one from the interpolating track. If star_flag=”HE”, to modify the total mass use Mass instead of MHE
MHE – Use this value to modify the initial helium core mass (MHE) of the star [Msun]. If None MHE will be the one from the interpolating track. MHE can be not None only if Mass is not None. It cannot be larger than Mass, if equal to Mass a pureHe star will be initialised (forcing the star_model to be “HE”).
MCO – Use this value to modify the initial carbon-oxygen core mass (MCO) of the star [Msun]. If None MCO will be the one from the interpolating track. MCO can be not None only if MHE is not None. It cannot be larger than MHE.
Radius – Use this value to modify the initial value of the stellar radius [Rsun].

Note

If you want to initialise a pureHe star with a custom initial mass use the star_flag=”HE” and set the initial mass with the parameter Mass (not MHE) E.g. to initialise a pureHE star following the interpolating track with Zams mass 30 Msun, Z =0.01 but with initial Mass 25 Msun (instead of 30 Msun).

>>> s=Star(Mzams=30, Z=0.01, tini="cheb", star_flag="HE", Mass=30)

Raises:: ValueError – If the hierarchy of the mass in input is not satisfied (Mass, MHE, MCO), a mass type cannot be not None if the precedent mass type is None. The error is raised also if the mass is larger than the preceded mass type

__repr__()[source]: Return repr(self).

__weakref__: list of weak references to the object

evolve(tend: str | float | int = 'end')[source]

Main evolve function. The star is evolved from their initial age (set at the initialisation) to the value in input.

Warning

Each time the evolve function is called, the past evolution of the Star is overwritten. If you want to continue the evolution from the current Star state use the method evolve_for()

Parameters:: tend – Stopping time of the simulation, can be a number in Myr or the word end. If end, the evolution will stop when a remnant is generated

evolve_for(dt: float | int)[source]

Evolve the star from the current status for a given time interval.

Parameters:: dt – Evolution time interval [Myr]

Examples

It is possible to use evolve_for to perform a step-by-step stellar evolution directly in Python. For example assume that we want to evolve a star for 10 Myr and get the properties each 1 Myr

>>> from sevnpy.sevn import SEVNmanager, Star
>>> import pandas as pd
>>> SEVNmanager.init()
>>> s1=Star(10,0.02)
>>> res_df = s1.getp(mode="last") #Store initial properties
>>> t=0
>>> dt=1
>>> while t<10:
>>>     s1.evolve_for(dt)
>>>     res_df = pd.concat(res_df, s1.getp(mode="last"))
>>>     t+=dt
>>> SEVNmanager.close()

property evolve_table: DataFrame: Return the pandas dataframe containing the table with the stellar properties and their evolution

classmethod from_star(star: Star, ID: int | None = None, rseed: int | str | None = 'same') → Star[source]

Construct a new Star instance from the current state (i.e. the last points in the current evolution dataframe) of a Star in input

Parameters:

star – An instance of class Star. The new instance will be created using the current properties of star, i.e., the properties in the last row of the evolution dataframe.
ID – The ID of the new star, if None automatically generate one from a static ID counter
rseed – The random seed of the new star, if equal to the string same get the random seed from star

Returns:

new_star – a new instance of the class Star

Return type:

Star

get_SN_kick() → Dict[str:Any][source]

Get the info about the SN kick velocities.

Returns:

SNkick_properties –

A Dictionary containing the following keys:

SNtime: the time of the SN explosion (Worldtime)

Vkick: a numpy array containing the three Cartesian component of the kick (the axes orientation are arbitrary)

Warning

If a SN never exploded in the current evolution table, SNtime will be equal to nan and the three components of the Vkick will be nan too

Return type:

Dictionary

get_remnant() → DataFrame[source]

Get the property of the remnant. This method retrieve the properties of the remnant produced by evolving the star from the properties set at the star initialization, therefore it neglect the current status of the star.

Returns:: remnant – A Pandas DataFrame containing the remnant properties
Return type:: pandas DataFrame

Note

Even if the method will internally evolve the star, the results of this evolution will not be stored in the class attribute, but only returned by the method

getp(properties: str | ListLikeType | None = None, mode: str = 'all', t: Number | ListLikeType | None = None) → pd.DataFrame[source]

Return the stellar properties as a Pandas DataFrame.

Parameters:

properties – single property name or list of property names (see SEVN documentation for the property names). If None return all the available properties.
mode –
Set the return type:
- all: return all the timesteps for the stellar evolution
- last: return just the current Stellar properties (last row form the evolution tables)
- first: return the initial stellar properties, i.e. the properties set at the initialisation
t – If not None, overwrite the mode property and return the properties at time specified by the input value(s) In order to return the values at time not stored in the evolution table, the proeprties are interpolated linearly

Returns:

star_properties – A pandas dataframe containing the values of the properties chosen in input

Return type:

pandas DataFrame

Raises:

RuntimeError – If the evolution table is empty

Examples

>>> s = Star(10,0.02)
>>> s.evolve()
>>> dfevolve  = s.getp(mode="all") #Get the complete evolution table
>>> dfevolve  = s.getp(mode="last") #Get all the current properties
>>> t = np.linspace(0.1,10)
>>> dfevolve  = s.getp(properties=["Worldtime","Mass","Radius"], t=t) #Get the evolution of time mass and radius
>>> #at given t

Warning

Use the t option wisely. The interpolation consists on a simple 1D interpolation, so it is not comparable with the detailed interpolation implemente in SEVN. THerefore, although the SEVN adaptive timestep catches all the important changes during the evolution do not bindly rely on the results obtain from this method when t is used (if t=None, the results will be robust since they are the one derived by SEVN directly),

getp_array(properties: str | ListLikeType | None = None, mode: str = 'all', t: Number | ListLikeType | None = None) → np.ndarray[np.float][source]

Return the stellar properties as a numpy array.

Parameters:

properties – single property name or list of property names (see SEVN documentation for the property names). If None return all the available properties.
mode –
Set the return type:
- all: return all the timesteps for the stellar evolution
- last: return just the current Stellar properties (last row form the evolution tables)
- first: return the initial stellar properties, i.e. the properties set at the initialisation
t – If not None, overwrite the mode property and return the properties at time specified by the input value(s) In order to return the values at time not stored in the evolution table, the proeprties are interpolated linearly

Returns:

star_properties – A numpy array containing the values of the properties chosen in input. The shape depends on the input data and mode option:

If mode=”all” or t is not None, 2D array with the is equal to NxC, where N is the number of row in the evolved dataframe and C are the number of properties in input.

if mode=”last” or mode=”first”, 1D array with length=C, where C are the number of properties in input.

Return type:

numpy array

Raises:

RuntimeError – If the evolution table is empty

Examples

>>> s = Star(10,0.02)
>>> s.evolve()
>>> dfevolve  = s.getp_array(mode="all") #Get the complete evolution table
>>> dfevolve  = s.getp_array(mode="last") #Get all the current properties
>>> t = np.linspace(0.1,10)
>>> dfevolve  = s.getp_array(properties=["Worldtime","Mass","Radius"], t=t) #Get the evolution of time mass and radius
>>> #at given t

Warning

Use the t option wisely. The interpolation consists on a simple 1D interpolation, so it is not comparable with the detailed interpolation implemente in SEVN. THerefore, although the SEVN adaptive timestep catches all the important changes during the evolution do not bindly rely on the results obtain from this method when t is used (if t=None, the results will be robust since they are the one derived by SEVN directly),

property log: str: Log created during the stellar evolution

look_at_track(t: str | float | int) → DataFrame[source]

The method returns the properties of the interpolating tracks followed by the star at a given time t. Since this will just consider the interpolating track, the initialisation properties Mass, MHE and MCO will not be considered.

Parameters:: t – Time in Myr at which look for the properties of the interpolating track
Returns:: star_properties – A Pandas DataFrame containing the properties of the interpolating tracks at time t. If the time t is larger than the stellar lifetime, the properties of the generated remnant is returned (see get_remnant())
Return type:: pandas DataFrame

Warning

The time inserted in this method refers to the Localtime, while the time used in evolver() and evolve_for() refers to the Worldtime

property name: float: Unique identifier of this object.

property pnames: List: List of names of available properties

Use this method to re-initialise the star changing the initial properties, except for Mzams and Z. If you need to change Mzams and Z create a new star.

Parameters:

spin – Initial stellar spin, i.e. the ratio between the rotational angular velocity and the critical angular velocity
tini –
Initial age of the star to initialise, the options are:
- age number, a float in Myr
- phase initialisation, initialise the star at a given phase, using the string:
  - zams: Zero age main sequence
  - tams: Terminal main sequence
  - shb: shell H burning
  - cheb: core helium burning
  - tcheb: terminal core helium burning
  - sheb: shel He burning
- percentage phase initialisation, using the string %<P>:<IDphase> where <P> is the percentage of the phase, and <IDphase> is the integer ID depending on the phase:
  - 1: zams
  - 2: tams
  - 3: shb
  - 4: cheb
  - 5: tcheb
  - 6: sheb
  so, for example to initialise the Star at 48% of the cheb phase: %48:4
snmodel – SEVN snmodel to use to transform a Star to a remnant (see the SEVN userguide)
star_flag –
String that defines the type of Star:
- H: initialise an Hydrogen star
- HE: initialise a pureHe star (use the pureHe trakcs, see the SEVN userguide)
- HEWD: initialise a Helium White Dwarf remnant with mass equal to Mzams
- COWD: initialise a Carbon-Oxygen White Dwarf remnant with mass equal to Mzams
- ONEWD: initialise a Oxygen-Neon White Dwarf remnant with mass equal to Mzams
- NS: initialise a Neutron Star with mass equal to Mzams
- BH: initialise a Black Hole with mass equal to Mzams
rseed – Random seed to be used in the stellar evolution, if None a random seen will be automatically generated
ID – ID of the Star, if None a ID will be automatically assigned
Mass –

Use this value to modify the initial Mass of the star [Msun].
If None the Mass will be the one from the interpolating track. If star_flag=”HE”, to modify the total mass use Mass instead of MHE
MHE – Use this value to modify the initial helium core mass (MHE) of the star [Msun]. If None MHE will be the one from the interpolating track. MHE can be not None only if Mass is not None. It cannot be larger than Mass, if equal to Mass a pureHe star will be initialised (forcing the star_model to be “HE”).
MCO – Use this value to modify the initial carbon-oxygen core mass (MCO) of the star [Msun]. If None MCO will be the one from the interpolating track. MCO can be not None only if MHE is not None. It cannot be larger than MHE.
Radius – Use this value to modify the initial value of the stellar radius [Rsun].

property rseed: int: Random seed used in the evolution

property snmodel: str: SEVN model used to pass from a Star to a remnant (see the SEVN documentation)

property star_flag: str: Stellar star flag based on the current properties (e.g. the last entry of the evolved table).

property tables_info: Dict[str:Union[str, float]]: Get a dictionary with the info of the loaded stellar tables (paths and minimum/maximum Zams - Z values)

property tlife: float: Star lifetime based on the Mzams and Z in input [Myr]

to_star(ID: int | None = None, rseed: int | str | None = 'same') → Star[source]

Create a new Star instance from the current state (i.e. the last points in the current evolution dataframe)

Parameters:

star – An instance of class Star. The new instance will be created using the current properties of star, i.e., the properties in the last row of the evolution dataframe.
ID – The ID of the new star, if None automatically generate one from a static ID counter
rseed – The random seed of the new star, if equal to the string same get the random seed from star

Returns:

new_star – a new instance of the class Star

Return type:

Star

property used_sevnParams: Dict[str:Union[float, str, bool]]: Dictionary containing the SEVN parameters used during the stellar evolution