Warning: This is no longer the latest available version of this module. Please see the releases page for the most recent version. The Webnucleo group strongly recommends the use of the latest version of any of its online modules.
Documentation from the file
Table of Contents
-
User-Supplied Routines
-
Routines
| Structures |
|---|
Name: Liblvls__LevelDescription: Liblvls__Level is a structure that stores data about a particular level. The contents of Liblvls__Level are not made public by the API but rather are accessed through the API routines. |
|
|
Name: Liblvls__SpeciesDescription: Liblvls__Species is a structure that stores data about a particular species. The structure is primarily composed of a hash of Liblvls__Level structures. The contents of Liblvls__Species are not made public by the API but rather are accessed through the API routines. |
|
|
Name: Liblvls__SpCollDescription: Liblvls__SpColl is a structure that stores data about a collection of species. The structure is primarily composed of a hash of Liblvls__Species structures. The contents of Liblvls__SpColl are not made public by the API but rather are accessed through the API routines. |
|
|
Name: Liblvls__ZoneDescription: Liblvls__Zone is a structure that stores data about the probabilities of levels of species in a zone. A zone is labelled by three strings. If zone labels are not provided by the user, zones are labelled ( "n", "0", "0" ) where n is an integer that increments for each zone added to the Liblvls structure, starting with zero. Any missing labels will be filled in with "0". For example, if two zones are provided without labels, the first zone would be given labels ( "0", "0", "0" ), and the second would be given labels ( "1", "0", "0" ). A Liblvls__Zone structure also contains a pointer to the Liblvls__SpColl structure. A Liblvls structure thus contains data that can change with each timestep in a calculation (species level probabilities) along with data that are fixed. The contents of Liblvls__Zone are not made public by the API but rather are accessed through the API routines. |
|
|
Name: LiblvlsDescription: Liblvls is a structure that stores data about level systems of species in a multi-zone system. It is composed of a Liblvls__SpColl structure and a hash of Liblvls__Zone structures. The contents of Liblvls are not made public by the API but rather are accessed through the API routines. |
|
|
| User-Supplied Routines |
|---|
Name: Liblvls__Level__iterateFunction()Description: User-supplied routine to be applied during an iteration over the levels in a species. Syntax:
int
Liblvls__Level__iterateFunction(
Liblvls__Level *self,
void *p_user_data
);
Input:
User's routine must return 1 to continue or 0 to stop. The user's routine must not modify self, that is, the pointer to the input Liblvls__Level structure. |
|
|
Name: Liblvls__Level__transitionRatesFunction()Description: Optional user-supplied routine to calculate transition rates between two levels. Syntax:
int
Liblvls__Level__transitionRatesFunction(
Liblvls__Level *p_upper_level,
Liblvls__Level *p_lower_level,
double d_temperature,
double *p_up_rate,
double *p_down_rate,
void *p_user_data
);
Input:
User's routine must return 1 on success or 0 on failure. The user's routine must not modify any Liblvls__Level pointer passed in as an argument. |
|
|
Name: Liblvls__Species__iterateFunction()Description: User-supplied routine to be applied during an iteration over the species in a species collection. Syntax:
int
Liblvls__Species__iterateFunction(
Liblvls__Species *self,
void *p_user_data
);
Input:
User's routine must return 1 to continue or 0 to stop. The user's routine must not modify self, that is, the pointer to the input Liblvls__Species structure. |
|
|
Name: Liblvls__Zone__iterateFunction()Description: User-supplied routine to be applied during an iteration over the zones. Syntax:
int
Liblvls__Zone__iterateFunction(
Liblvls__Zone *self,
void *p_user_data
);
Input:
User's routine must return 1 to continue or 0 to stop. The user's routine must not modify self, that is, the pointer to the input Liblvls__Zone structure. |
|
|
| Routines |
|---|
Name: Liblvls__Level__computeBoltzmannFactor()Description: Routine to compute the Boltzmann factor for a given level at the input temperature. Syntax:
double
Liblvls__Level__computeBoltzmannFactor(
Liblvls__Level *self,
double d_temperature
);
Input:
Routine returns a double containing the Boltzmann factor for the given level at the input temperature. If the level is not found or the temperature is not valid (< 0), error handling is invoked. Example: Print the Boltzmann factor for Liblvls__Level *p_level at 100,000 K:
printf(
"Boltzmann factor = %e\n",
Liblvls__Level__computeBoltzmannFactor(
p_level, 100000.
)
);
|
|
|
Name: Liblvls__Level__computeEinsteinCoefficients()Description: Routine to compute the Einstein Coefficients for transitions from a given level to another. Syntax:
void
Liblvls__Level__computeEinsteinCoefficients(
Liblvls__Level *p_upper_level,
Liblvls__Level *p_lower_level,
double *p_a_ij,
double *p_b_ij,
double *p_b_ji
);
Input:
p_he4_i =
Liblvls__SpColl__getSpecies( p_my_species, "he4i" );
if( p_he4_i ) {
p_level_i = Liblvls__Species__getLevel( p_he4_i, 2 );
p_level_j = Liblvls__Species__getLevel( p_he4_i, 1 );
Liblvls__Level__computeEinsteinCoefficients(
p_level_i, p_level_j, &d_aij, &d_bij, &d_bji
);
printf(
"A_ij = %e (per second)\n", d_aij
);
printf(
"B_ij = %e (seconds per erg)\n", d_bij
);
printf(
"B_ji = %e (seconds per erg)\n", d_bji
);
}
|
|
|
Name: Liblvls__Level__getEnergy()Description: Routine to retrieve the energy (in specified units) of a given level. Syntax:
double
Liblvls__Level__getEnergy(
Liblvls__Level *self, int i_units
);
Input:
A double giving the energy (in the chosen units) of the desired level. If the level or the input unit is not valid, error handling is invoked. Example: Print the energy (in eV) of the fifth level of doubly ionized 12C (stored as c12iii) in the species collection p_my_species:
p_c12_iii =
Liblvls__SpColl__getSpecies( p_my_species, "c12iii" );
if( p_c12_iii ) {
p_level = Liblvls__Species__getLevelByIndex( p_c12_iii, 4 );
if( p_level ) {
printf(
"Energy (eV) = %e\n",
Liblvls__Level__getEnergy( p_level, EV )
);
}
}
|
|
|
Name: Liblvls__Level__getIndex()Description: Routine to retrieve the index of a given level. Syntax:
unsigned int
Liblvls__Level__getIndex(
Liblvls__Level *self
);
Input:
An unsigned int giving the index of the desired level. If the level is not valid, error handling is invoked. Example: Retrieve the index of the Liblvls__Level *p_level:
i_level = Liblvls__Level__getIndex( p_level );
|
|
|
Name: Liblvls__Level__getMultiplicity()Description: Routine to retrieve the multiplicity of a given level. Syntax:
unsigned int
Liblvls__Level__getMultiplicity(
Liblvls__Level *self
);
Input:
An unsigned int giving the multiplicity of the desired level. If the level is not valid, error handling is invoked. Example: Print the multiplicity of the ground state of neutral 16O (stored as o16i) in the species collection p_my_species (assuming levels are correctly sorted in terms of energy):
p_o16_i =
Liblvls__SpColl__getSpecies( p_my_species, "o16i" );
if( p_o16_i ) {
p_level = Liblvls__Species__getLevelByIndex( p_o16_i, 0 );
if( p_level ) {
printf(
"Multiplicity = %d\n",
Liblvls__Level__getMultiplicity( p_level )
);
}
}
|
|
|
Name: Liblvls__Level__getProperty()Description: Routine to retrieve property information for a level. Syntax:
Liblvls__Property *
Liblvls__Level__getProperty(
Liblvls__Level *self,
const char *s_property_name
);
Input:
Upon return, the requested property has been retrieved. If the property is not found, NULL is returned. Example: Retrieve a property named "parity" from level my_level:
p_property =
Liblvls__Level__getProperty(
my_level, "parity"
);
|
|
|
Name: Liblvls__Level__new()Description: Routine to create a new level. Syntax:
Liblvls__Level *
Liblvls__Level__new(
double d_energy,
unsigned int i_multiplicity
);
Input:
Routine returns a pointer to a new level. If memory cannot be allocated, error handling is invoked. Example: Create a level with energy 104.03 keV, and multiplicity of 3:
p_new_level =
Liblvls__Level__new( 104.03, 3 );
|
|
|
Name: Liblvls__Level__updateProperty()Description: Routine to update a user-defined property for a level. Syntax:
void
Liblvls__Level__updateProperty(
Liblvls__Level *self,
const char *s_name,
const char *s_type,
const char *s_value
);
Input:
Upon successful return, the data for the property has been either added (if the data for the property didn't previously exist) or updated (if the property did previously exist). If the level to which the property is attached is not valid, error handling is invoked. Example: Update the level p_level to include an integer parity stored in the string named s_parity:
Liblvls__Level__updateProperty(
p_level, "parity", "int", s_parity
);
|
|
|
Name: Liblvls__Level__updateTransitionData()Description: Routine to update the data for a transition from a level. Syntax:
void
Liblvls__Level__updateTransitionData(
Liblvls__Level *self,
double d_to_energy,
unsigned int i_to_multiplicity,
double d_A
);
Input:
Upon successful return, the data for the transition has been either added (if the data for the transition didn't previously exist) or updated (if the data did previously exist). If the level from which the transition starts is not valid, error handling is invoked. The transition will be created or updated even if the target level is invalid. Example: Update the Einstein A coefficient for the transition from the level p_level to the level with energy 100. keV, multiplicity 3, with the new rate 1.e13:
Liblvls__Level__updateTransitionData(
p_level, 100., 3, 1.e13
);
|
|
|
Name: Liblvls__Property__getType()Description: Routine to retrieve the type of a property. Syntax:
const char *
Liblvls__Property__getType(
Liblvls__Property *self
);
Input:
The function returns a string containing the type of data in the Liblvls__Property struct. Example: Retrieve the data type of the parity for the level my_level:
p_property =
Liblvls__Level__getProperty(
my_level, "parity"
);
s_type =
Liblvls__Property__getType(
p_property
);
|
|
|
Name: Liblvls__Property__getValue()Description: Routine to retrieve the value of a property. Syntax:
const char *
Liblvls__Property__getValue(
Liblvls__Property *self
);
Input:
The function returns a string containing the value stored in the Liblvls__Property struct. The caller can then parse the string to extract the needed information. Example: Retrieve the parity (an integer) for the level my_level:
p_property =
Liblvls__Level__getProperty(
my_level, "parity"
);
i_parity =
atoi(
Liblvls__Property__getValue(
p_property
)
);
|
|
|
Name: Liblvls__Property__new()Description: Routine to create a new property. Syntax:
Liblvls__Property *
Liblvls__Property__new(
const char *s_type,
const char *s_value
);
Input:
Routine returns a pointer to a new Liblvls__Property struct. If memory cannot be allocated, error handling is invoked. Example: Create a property of integer type with a value stored in s_value:
p_new_property =
Liblvls__Property__new( "integer", s_value );
|
|
|
Name: Liblvls__SpColl__addSpecies()Description: Routine to add a species to a species collection. Syntax:
void
Liblvls__SpColl__addSpecies(
Liblvls__SpColl *self,
Liblvls__Species *p_species
);
Input:
Upon successful return, the species has been added to the collection. If the species cannot be added error handling is invoked. Example: Create a species c12ii (singly-ionized c12) and add it to the collection p_my_collection:
p_c12ii =
Liblvls__Species__new( "c12ii" );
Liblvls__SpColl__addSpecies( p_my_collection, p_c12ii );
|
|
|
Name: Liblvls__SpColl__free()Description: Routine to free the memory allocated for a Liblvls__SpColl structure. Syntax:
void
Liblvls__SpColl__free
Liblvls__SpColl *self
);
Input:
Upon successful return, the memory for the species collection structure has been freed. Example: Free the memory previously allocated for the Liblvls__SpColl structure p_my_collection:
Liblvls__SpColl__free( p_my_collection );
|
|
|
Name: Liblvls__SpColl__getNumberOfSpecies()Description: Routine to get the number of species in a Liblvls__SpColl structure. Syntax:
size_t
Liblvls__SpColl__getNumberOfSpecies(
Liblvls__SpColl *self
);
Input:
A size_t giving the number of species in the Liblvls__SpColl structure. Example: Print the number of species in p_my_species:
printf(
"Number of species = %d\n",
Liblvls__SpColl__getNumberOfSpecies( p_my_species )
);
|
|
|
Name: Liblvls__SpColl__getProperty()Description: Routine to retrieve property information for a species collection. Syntax:
Liblvls__Property *
Liblvls__SpColl__getProperty(
Liblvls__SpColl *self,
const char *s_property_name
);
Input:
Upon return, the requested property has been retrieved. If the property is not found, NULL is returned. Example: Retrieve a property named "group_name" from species collection my_spcoll:
p_property =
Liblvls__SpColl__getProperty(
my_spcoll, "group_name"
);
|
|
|
Name: Liblvls__SpColl__getSpecies()Description: Routine to retrieve a species from a species collection. Syntax:
Liblvls__Species *
Liblvls__SpColl__getSpecies(
Liblvls__SpColl *self,
const char *s_species
);
Input:
A pointer to the Liblvls__Species structure for the desired species. If the species cannot be found, the routine returns NULL. Example: Retrieve the pointer to the Liblvls__Species structure for neutral 4He (he4i) from the Liblvls__SpColl structure p_my_species:
p_he4_i =
Liblvls__SpColl__getSpecies(
p_my_species, "he4i"
);
|
|
|
Name: Liblvls__SpColl__is_valid_input_xml()Description: Routine to check an input species collection xml file against the schema for validity. Syntax:
int
Liblvls__SpColl__is_valid_input_xml(
const char *s_xml_filename
);
Input:
Returns 1 for a valid xml input file, 0 for invalid input, and prints an error if the schema file is invalid or unable to be read over the web. Example: Validate the input xml file "species_collection.xml":
if( Liblvls__SpColl__is_valid_input_xml( "species_collection.xml" ) ) {
printf( "Valid xml input!\n" );
}
|
|
|
Name: Liblvls__SpColl__iterateSpecies()Description: Iterate through the species in a given species collection and apply the user-supplied iterate function. Syntax:
void
Liblvls__SpColl__iterateSpecies(
Liblvls__SpColl *self,
Liblvls__Species__iterateFunction pf_func,
void *p_user_data
);
Input:
The routine iterates through the species and applies the user-supplied routine to each. If any input is invalid, error handling is invoked. Example: Iterate through the species in Liblvls__SpColl p_my_spcoll and apply the function my_iterate_function using the extra data in p_user_data:
Liblvls__SpColl__iterateSpecies(
p_my_spcoll,
(Liblvls__Species__iterateFunction) my_iterate_function,
p_user_data
);
|
|
|
Name: Liblvls__SpColl__new()Description: Routine to create a new Liblvls__SpColl structure. Syntax:
Liblvls__SpColl *Liblvls__SpColl__new( );
Output:A pointer to a new Liblvs__SpColl structure. Example: Create the Liblvls__SpColl structure p_my_species:
p_my_species = Liblvls__SpColl__new( );
|
|
|
Name: Liblvls__SpColl__new_from_xml()Description: Routine to read in level data from an xml file and store them into a Liblvls data structure. Duplicate entries for a given species in the xml file will be overwritten in the returned structure. Syntax:
Liblvls__SpColl *
Liblvls__SpColl__new_from_xml(
const char *s_xml_filename,
const char *s_xpath_suffix
);
Input:
A pointer to a Liblvls__SpColl structure containing the level data. Example: Store the level data in levels.xml to p_species_collection:
p_species_collection =
Liblvls__SpColl__new_from_xml( "levels.xml", NULL );
|
|
|
Name: Liblvls__SpColl__updateFromXml()Description: Routine to update a pre-existing Liblvls__SpColl structure with data from an xml file. Replaces existing species data and adds data about new species. Syntax:
void
Liblvls__SpColl__updateFromXml(
Liblvls__SpColl *self,
const char *s_xml_filename,
const char *s_xpath_suffix
);
Input:
For a valid Liblvls__SpColl structure and a valid input data xml file, the routine updates the structure with the data in the input data file. If the routine cannot allocate enough memory or if the xpath expression is invalid, error handling is invoked. Example: Update p_species_collection with the data stored in levels.xml:
Liblvls__SpColl__updateFromXml( p_species_collection, "levels.xml", NULL );
|
|
|
Name: Liblvls__SpColl__updateProperty()Description: Routine to update a user-defined property for a species collection. Syntax:
void
Liblvls__SpColl__updateProperty(
Liblvls__SpColl *self,
const char *s_name,
const char *s_type,
const char *s_value
);
Input:
Upon successful return, the data for the property has been either added (if the data for the property didn't previously exist) or updated (if the property did previously exist). If the species collection to which the property is attached is not valid, error handling is invoked. Example: Update the species collection p_spcoll to include an integer group number stored in the string named s_group_number:
Liblvls__SpColl__updateProperty(
p_spcoll, "group_number", "integer", s_group_number
);
|
|
|
Name: Liblvls__SpColl__writeToXmlFile()Description: Output a Liblvls__SpColl structure to an xml file. Syntax:
void
Liblvls__SpColl__writeToXmlFile(
Liblvls__SpColl *self,
const char *s_xml_filename
);
Input:
Upon successful return, the contents of the collection of species have been written to an xml file. If the input is invalid, Liblvls error handling is invoked. Example: Dump the contents of Liblvls_SpColl *p_sp_coll to the xml file my.xml:
Liblvls__SpColl__writeToXmlFile( p_sp_coll, "my.xml" );
|
|
|
Name: Liblvls__Species__addLevel()Description: Routine to add a level to a species. Syntax:
void
Liblvls__Species__addLevel(
Liblvls__Species *self,
Liblvls__Level *p_level
);
Input:
Upon successful return, the level has been added to the species. If the level cannot be added error handling is invoked. Example: Create a level with energy 50 keV and multiplicity 3, and add it to p_species:
p_new_level =
Liblvls__Level__new( 50., 3 ).
Liblvls__Species__addLevel( p_species, p_new_level );
|
|
|
Name: Liblvls__Species__clearTransitionRatesFunction()Description: Routine to clear the transition rates function for a species. Syntax:
void
Liblvls__Species__clearTransitionRatesFunction(
Liblvls__Species *self
);
Input:
Liblvls__Species__clearTransitionRatesFunction(
p_species
);
|
|
|
Name: Liblvls__Species__computePartitionFunction()Description: Routine to retrieve the partition function for a species at the specified temperature (in K). Syntax:
double
Liblvls__Species__computePartitionFunction(
Liblvls__Species *self,
double d_temperature
);
Input:
A double giving the partition function. If the species is invalid or if the temperature is negative, error handling is invoked. Example: Print the partition function for neutral 1H (stored in the species collection Liblvls__SpColl *p_my_species as h1i) at 20,000 K:
p_h1_i =
Liblvls__SpColl__getSpecies( p_my_species, "h1i" );
if( p_h1_i ) {
printf(
"Partition function at 20,000 K = %e\n",
Liblvls__Species __computePartitionFunction( p_h1i, 20000. )
);
}
|
|
|
Name: Liblvls__Species__computeRateMatrix()Description: Routine to compute the rate matrix for a species at a specified temperature. Syntax:
WnMatrix *
Liblvls__Species__computeRateMatrix(
Liblvls__Species *self,
double d_temperature,
void *p_user_rate_data
);
Input:
Routine returns the rate matrix in native WnMatrix format. If the species is not found or the temperature is not valid (< 0), error handling is invoked. Example: Return the rate matrix for neutral 1H (stored as h1i in the species collection p_my_collection) at 15,000 K with no extra data:
p_matrix =
Liblvls__Species__computeRateMatrix(
Liblvls__SpColl_getSpecies( p_my_collection, "h1i" ),
15000.,
NULL
);
|
|
|
Name: Liblvls__Species__computeRatesForTransition()Description: Routine to retrieve the rates for transitions from a given level to another using a rate calculation specified by the species. Syntax:
void
Liblvls__Species__computeRatesForTransition(
Liblvls__Species *self
Liblvls__Level *p_upper_level,
Liblvls__Level *p_lower_level,
double d_temperature,
double *p_up_rate,
double *p_down_rate,
void *p_user_data
);
Input:
p_he4_i =
Liblvls__SpColl__getSpecies( p_my_species, "he4i" );
if( p_he4_i ) {
p_level_i = Liblvls__Species__getLevel( p_he4_i, 2 );
p_level_j = Liblvls__Species__getLevel( p_he4_i, 1 );
Liblvls__Level__computeRatesForTransition(
p_my_species,
p_level_i,
p_level_j,
35000.,
&d_up_rate,
&d_down_rate,
NULL
);
printf(
"rate up = %e (per second)\n", d_up_rate
);
printf(
"rate down = %e (per second)\n", d_down_rate
);
}
|
|
|
Name: Liblvls__Species__free()Description: Routine to free the memory allocated for a Liblvls__Species structure. Syntax:
void
Liblvls__Species__free
Liblvls__Species *self
);
Input:
Upon successful return, the memory for the species structure has been freed. Example: Free the memory previously allocated for the Liblvls__Species structure p_species:
Liblvls__Species__free( p_species );
|
|
|
Name: Liblvls__Species__getLevel()Description: Routine to retrieve a level from a species. Syntax:
Liblvls__Level *
Liblvls__Species__getLevel(
Liblvls__Species *self,
double d_energy,
unsigned int i_multiplicity
);
Input:
A pointer to the Liblvls__Level structure for the desired level. If the level cannot be found, the routine returns NULL. Example: Retrieve the pointer p_level to the level in neutral 4He (he4i) with energy 21010 keV, and multiplicity 1 in the Liblvls__SpColl structure p_my_species:
p_he4_i =
Liblvls__SpColl__getSpecies(
p_my_species, "he4i"
);
p_level =
Liblvls__Species__getLevel(
p_he4_i, 21010., 1
);
|
|
|
Name: Liblvls__Species__getLevelByIndex()Description: Routine to retrieve a level from a species. Syntax:
Liblvls__Level *
Liblvls__Species__getLevelByIndex(
Liblvls__Species *self,
unsigned int i_level
);
Input:
A pointer to the Liblvls__Level structure for the desired level. If the level cannot be found, the routine returns NULL. Example: Retrieve the pointer p_level to the fourth level in neutral 4He (he4i) in the Liblvls__SpColl structure p_my_species:
p_he4_i =
Liblvls__SpColl__getSpecies(
p_my_species, "he4i"
);
p_level =
Liblvls__Species__getLevelByIndex(
p_he4_i, 3
);
|
|
|
Name: Liblvls__Species__getName()Description: Routine to return the name of a species. Syntax:
const char *
Liblvls__Species__getName(
Liblvls__Species *self
);
Input:
Routine returns a string containing the name of the species. If the species is not found, error handling is invoked. Example: Print the name of the species p_species:
printf(
"The name of the species is %s\n",
Liblvls__Species__getName( p_species )
);
|
|
|
Name: Liblvls__Species__getNumberOfLevels()Description: Routine to get the number of levels in a Liblvls__Species structure. Syntax:
size_t
Liblvls__Species__getNumberOfLevels(
Liblvls__Species *self
);
Input:
A size_t giving the number of levels in the Liblvls__Species structure. Example: Print the number of levels in triply-ionized 56Fe (fe56iv) in the species collection p_my_species:
p_fe56_iv =
Liblvls__SpColl__getSpecies(
p_my_species, "fe56iv"
);
if( p_fe56_iv ) {
printf(
"Number of levels in fe56iv = %d\n",
Liblvls__Species__getNumberOfLevels( p_fe56_iv )
);
}
|
|
|
Name: Liblvls__Species__getProperty()Description: Routine to retrieve property information for a species. Syntax:
Liblvls__Property *
Liblvls__Species__getProperty(
Liblvls__Species *self,
const char *s_property_name
);
Input:
Upon return, the requested property has been retrieved. If the property is not found, NULL is returned. Example: Retrieve a property called "atomic_number" from species my_species:
p_property =
Liblvls__Species__getProperty(
my_species, "atomic_number"
);
|
|
|
Name: Liblvls__Species__iterateLevels()Description: Iterate through the levels and apply the user-supplied iterate function. Syntax:
void
Liblvls__Species__iterateLevels(
Liblvls__Species *self,
Liblvls__Level__iterateFunction pf_func,
void *p_user_data
);
Input:
The routine iterates through the levels and applies the user-supplied routine to each. If any input is invalid, error handling is invoked. Example: Iterate through the levels in p_my_species and apply the function my_iterate_function and the extra data in p_user_data:
Liblvls__Species__iterateLevels(
p_my_species,
(Liblvls__Level__iterateFunction) my_iterate_function,
p_user_data
);
|
|
|
Name: Liblvls__Species__new()Description: Routine to create a new species. Syntax:
Liblvls__Species *
Liblvls__Species__new(
const char *s_species_name
);
Input:
Routine returns a pointer to a new species. If memory cannot be allocated, error handling is invoked. Example: Create the species c12ii (singly-ionized carbon-12):
p_c12_ii = Liblvls__Species__new( "c12ii" );
|
|
|
Name: Liblvls__Species__removeLevel()Description: Routine to remove a level from a species. Syntax:
void
Liblvls__Species__removeLevel(
Liblvls__Species *self,
Liblvls__Level *p_level
);
Input:
Upon successful return, the level has been removed from the species. If any input is invalid, or if the level cannot be removed, error handling is invoked. Example: Remove the level with energy 50 keV and multiplicity 3 from the species stored in p_species:
p_level = Liblvls__Species__getLevel( p_species, 50., 3 );
Liblvls__Species__removeLevel( p_species, p_level );
|
|
|
Name: Liblvls__Species__setTransitionRatesFunction()Description: Routine to set the optional user-supplied transition rates function for a species. Syntax:
void
Liblvls__Species__setTransitionRatesFunction(
Liblvls__Species *self,
Liblvls__Level__rateFunction pf_user_function
);
Input:
Liblvls__Species__setTransitionRatesFunction(
p_species,
(Liblvls__Level__transitionRatesFunction) my_rate_function
);
|
|
|
Name: Liblvls__Species__updateLevelEnergy()Description: Routine to self-consistently update the energy of a level in a given species. Syntax:
void
Liblvls__Species__updateLevelEnergy(
Liblvls__Species *self,
Liblvls__Level *p_level,
double d_new_energy
);
Input:
Liblvls__Species__updateLevelEnergy(
p_species,
p_level,
53.
);
|
|
|
Name: Liblvls__Species__updateLevelMultiplicity()Description: Routine to self-consistently update the multiplicity of a level in a given species. Syntax:
void
Liblvls__Species__updateLevelMultiplicity(
Liblvls__Species *self,
Liblvls__Level *p_level,
unsigned int i_new_multiplicity
);
Input:
Liblvls__Species__updateLevelMultiplicity(
p_species,
p_level,
5
);
|
|
|
Name: Liblvls__Species__updateProperty()Description: Routine to update a user-defined property for a species. Syntax:
void
Liblvls__Species__updateProperty(
Liblvls__Species *self,
const char *s_name,
const char *s_type,
const char *s_value
);
Input:
Upon successful return, the data for the property has been either added (if the data for the property didn't previously exist) or updated (if the property did previously exist). If the species to which the property is attached is not valid, error handling is invoked. Example: Update the species p_species to include an integer atomic number stored in the string named s_atomic_number:
Liblvls__Species__updateProperty(
p_species, "atomic_number", "int", s_atomic_number )
);
|
|
|
Name: Liblvls__Zone__computeFlowVector()Description: Routine to compute the flow vector for a particular species in a given zone at the input temperature. The elements of this vector are the net flow (flow in - flow out) into each level. Syntax:
gsl_vector *
Liblvls__Zone__computeFlowVector(
Liblvls__Zone *self,
Liblvls__Species *p_species,
double d_temperature,
void *p_user_rate_data
);
Input:
Routine returns a pointer to the flow vector (a gsl_vector). If the zone or species is not found or the temperature is not valid (< 0), error handling is invoked. Example: Return the flow vector for levels in singly-ionized 4He (stored as he4ii in the species collection p_my_collection) at 25,000 K in zone p_zone with no extra data:
p_flow_vector =
Liblvls__Zone__computeFlowVector(
p_zone,
Liblvls__SpColl_getSpecies( p_my_collection, "he4ii" ),
25000.,
NULL
);
|
|
|
Name: Liblvls__Zone__free()Description: Routine to free the memory allocated for a Liblvls__Zone structure. Syntax:
void
Liblvls__Zone__free
Liblvls__Zone *self
);
Input:
Upon successful return, the memory for the zone structure has been freed. Example: Free the memory previously allocated for the Liblvls__Zone structure p_my_zone:
Liblvls__Zone__free( p_my_zone );
|
|
|
Name: Liblvls__Zone__getLabel()Description: Routine to retrieve a label for the given zone. Syntax:
const char *
Liblvls__Zone__getLabel(
Liblvls__Zone *self,
int i_label
);
Input:
Routine returns a string giving the requested label. If the zone or label is invalid, error handling is invoked. Example: Print the third label of Liblvls__Zone *p_zone:
printf(
"Third label = %s\n",
Liblvls__Zone__getLabel( p_zone, 3 )
);
|
|
|
Name: Liblvls__Zone__getLevelProbability()Description: Routine to retrieve the probability for a level in a particular species in a particular zone. Syntax:
double
Liblvls__Zone__getLevelProbability(
Liblvls__Zone *self,
Liblvls__Species *p_species,
Liblvls__Level *p_level
);
Input:
Routine returns the current population probability for the given level in the input species and zone or zero if the level, species, or zone is not found. Example: Return the probability of p_level in the p_species in the p_zone:
d_probability =
Liblvls__Zone__getLevelProbability(
p_zone, p_species, p_level
);
|
|
|
Name: Liblvls__Zone__getLevelProbabilityChange()Description: Routine to retrieve the change in the probability for a level in a particular species in a particular zone over the last time step of evolution. Syntax:
double
Liblvls__Zone__getLevelProbabilityChange(
Liblvls__Zone *self,
Liblvls__Species *p_species,
Liblvls__Level *p_level
);
Input:
Routine returns the change in the population probability for the given level in the input species and zone over the last timestep or zero if the level, species, or zone is not found. Example: Return the change in the population probability of p_level in p_species in p_zone:
d_probability_change =
Liblvls__Zone__getLevelProbabilityChange(
p_zone, p_species, p_level
);
|
|
|
Name: Liblvls__Zone__getProbabilities()Description: Routine to retrieve the probability for an entire species in a particular zone. Syntax:
gsl_vector *
Liblvls__Zone__getProbabilities(
Liblvls__Zone *self,
Liblvls__Species *p_species
);
Input:
Routine returns the current population probabilities for all levels in the input species and zone or NULL if the species or zone is not found. Example: Return the probability for all levels in p_species in p_zone:
p_probabilities =
Liblvls__Zone__getProbabilities(
p_zone,
p_species
);
|
|
|
Name: Liblvls__Zone__getProperty()Description: Routine to retrieve property information for a zone. Syntax:
Liblvls__Property *
Liblvls__Zone__getProperty(
Liblvls__Zone *self,
const char *s_property_name
);
Input:
Upon return, the requested property has been retrieved. If the property is not found, NULL is returned. Example: Retrieve a property named "temperature" from zone my_zone:
p_property =
Liblvls__Zone__getProperty(
my_zone, "temperature"
);
|
|
|
Name: Liblvls__Zone__updateLevelProbability()Description: Routine to update the probability and probability change over the last timestep for a level in a particular species in a particular zone. Syntax:
int
Liblvls__Zone__updateLevelProbability(
Liblvls__Zone *self,
Liblvls__Species *p_species,
Liblvls__Level *p_level,
double d_probability,
double d_probability_change
);
Input:
Routine returns 0 if the update succeeded and -1 in case of error. Example: Update the probability and probability change of p_level in p_species in p_zone. The new value of the probability is 1.e-5 and the change is 2.e-7:
if(
Liblvls__Zone__updateLevelProbability(
p_zone, p_species, p_level, 1.e-5, 2.e-7
) == 0
) {
fprintf( stdout, "Update succeeded!\n" );
}
|
|
|
Name: Liblvls__Zone__updateProbabilities()Description: Routine to update the probability and probability change over the last timestep for an entire species in a particular zone. Syntax:
void
Liblvls__Zone__updateProbabilities(
Liblvls__Zone *self,
Liblvls__Species *p_species,
gsl_vector *p_probability,
gsl_vector *p_probability_change
);
Input:
On successful return, the level probabilities have been updated. If updates fail, error handling is invoked. Example: Update the probabilities and probability changes of p_species in p_zone. The new values for the probabilities are stored in p_probabilities and the probability changes are stored in p_probability_changes:
Liblvls__Zone__updateProbabilities(
p_zone,
p_species,
p_probabilities,
p_probability_changes
);
|
|
|
Name: Liblvls__Zone__updateProperty()Description: Routine to update a user-defined property for a zone. Syntax:
void
Liblvls__Zone__updateProperty(
Liblvls__Zone *self,
const char *s_name,
const char *s_type,
const char *s_value
);
Input:
Upon successful return, the data for the property has been either added (if the data for the property didn't previously exist) or updated (if the property did previously exist). If the zone to which the property is attached is not valid, error handling is invoked. Example: Update the zone p_zone to include a double temperature stored in the string named s_temperature:
Liblvls__Zone__updateProperty(
p_zone,
"temperature",
"double",
s_temperature
);
|
|
|
Name: Liblvls__free()Description: Routine to free the memory allocated for a Liblvls structure. Syntax:
void
Liblvls__free
Liblvls *self
);
Input:
Upon successful return, the memory for the Liblvls structure has been freed. Example: Free the memory previously allocated for the Liblvls structure p_my_zones:
Liblvls__free( p_my_zones );
|
|
|
Name: Liblvls__getNumberOfZones()Description: Routine to get the number of zones in a Liblvls structure. Syntax:
size_t
Liblvls__getNumberOfZones(
Liblvls *self
);
Input:
A size_t giving the number of zones. Example: Print the number of zones in p_my_liblvls:
printf(
"Number of zones = %d\n",
Liblvls__getNumberOfZones( p_my_liblvls )
);
|
|
|
Name: Liblvls__getSpColl()Description: Routine to retrieve a species collection from a Liblvls structure. Syntax:
Liblvls__SpColl *
Liblvls__getSpColl(
Liblvls *self
);
Input:
Routine returns the pointer to the species collection. Example: Return the species collection from p_my_liblvls:
p_collection =
Liblvls__getSpColl( p_my_liblvls );
|
|
|
Name: Liblvls__getZone()Description: Routine to retrieve a zone from a Liblvls structure. Syntax:
Liblvls__Zone *
Liblvls__getZone(
Liblvls *self,
char *s_label_1,
char *s_label_2,
char *s_label_3
);
Input:
Routine returns the pointer to desired zone or NULL if the zone is not found. Example: Return the zone with labels 0, 1, 2 from Liblvls structure p_my_liblvls:
s_1 = "0";
s_2 = "1";
s_3 = "2";
p_zone = Liblvls__getZone( p_my_liblvls, s_1, s_2, s_3 );
|
|
|
Name: Liblvls__get_energy_units()Description: Routine to return the energy units flag. Syntax:
int
Liblvls__get_energy_units(
const char *s_units
);
Input:
d_energy =
Liblvls__Level__getEnergy(
p_level,
Liblvls__get_energy_units( "eV" )
);
|
|
|
Name: Liblvls__is_valid_input_xml()Description: Routine to check an input liblvls xml file against the schema for validity. Syntax:
int
Liblvls__is_valid_input_xml(
const char *s_xml_filename
);
Input:
Returns 1 for a valid xml input file, 0 for invalid input, and prints an error if the schema file is invalid or unable to be read over the web. Example: Validate the input xml file "liblvls.xml":
if( Liblvls__is_valid_input_xml( "liblvls.xml" ) ) {
printf( "Valid xml input!\n" );
}
|
|
|
Name: Liblvls__is_valid_zone_input_xml()Description: Routine to check an input zone xml file against the schema for validity. Syntax:
int
Liblvls__is_valid_zone_input_xml(
const char *s_xml_filename
);
Input:
Returns 1 for a valid xml input file, 0 for invalid input, and prints an error if the schema file is invalid or unable to be read over the web. Example: Validate the input xml file "zone_data.xml":
if( Liblvls__is_valid_zone_input_xml( "zone_data.xml" ) ) {
printf( "Valid xml input!\n" );
}
|
|
|
Name: Liblvls__iterateZones()Description: Iterate through the zones in a Liblvls structure and apply the user-supplied iterate function. The function is applied to the zones in alphabetical order by zone labels. Syntax:
void
Liblvls__iterateZones(
Liblvls *self,
Liblvls__Zone__iterateFunction pf_func,
void *p_user_data
);
Input:
The routine iterates through the zones and applies the user-supplied routine to each. If any input is invalid, error handling is invoked. Example: Iterate through the zones in p_my_liblvls and apply the function my_iterate_function and the extra data in p_user_data:
Liblvls__iterateZones(
p_my_liblvls,
(Liblvls__Zone__iterateFunction) my_iterate_function,
p_user_data
);
|
|
|
Name: Liblvls__new()Description: Routine to create a new Liblvls structure. Syntax:
Liblvls *Liblvls__new( );
Output:A pointer to a new Liblvs structure. Example: Create the Liblvls structure p_my_levels:
p_my_levels = Liblvls__new( );
|
|
|
Name: Liblvls__new_from_xml()Description: Routine to read in level data from an xml file and store them into a Liblvls data structure. Syntax:
Liblvls *
Liblvls__new_from_xml(
const char *s_xml_filename,
const char *s_xpath_suffix
);
Input:
A pointer to a Liblvls structure. Example: Store the level and zone data in levels.xml to p_my_liblvls:
p_my_liblvls = Liblvls__new_from_xml( "levels.xml", NULL );
|
|
|
Name: Liblvls__updateZonesFromXml()Description: Syntax:
void
Liblvls__updateZonesFromXml(
Liblvls *self,
const char *s_xml_filename,
const char *s_xpath_suffix
);
Input:
On successful return the zone data have been updated with the zone data contained in the input xml file. If the file is not found, error handling is invoked. Example: Update the zone data in p_liblvls with the data in zones.xml:
Liblvls__updateZonesFromXml(
p_liblvls,
"zones.xml",
NULL
);
|
|
|
Name: Liblvls__writeToXmlFile()Description: Output a Liblvls structure to an xml file. Syntax:
void
Liblvls__writeToXmlFile(
Liblvls *self,
const char *s_xml_filename
);
Input:
Upon successful return, the contents of the structure have been written to an xml file. If the input is invalid, Liblvls error handling is invoked. Example: Dump the contents of Liblvls *p_liblvls to the xml file my.xml:
Liblvls__writeToXmlFile( p_liblvls, "my.xml" );
|
|
|
