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. |
|
|
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. |
|
|
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. |
|
|
| 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(
const 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(
const 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:
size_t
Liblvls__Level__getIndex(
const Liblvls__Level *self
);
Input:
A size_t 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(
const 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:
const char *
Liblvls__Level__getProperty(
const Liblvls__Level *self,
const char *s_label1,
const char *s_label2,
const char *s_label3
);
Input:
If the property is found, a const char * pointing to the property is returned. If the property is not found, NULL is returned. Example: Retrieve a property named "parity" from level my_level:
s_parity =
Liblvls__Level__getProperty(
my_level, "parity", NULL, NULL
);
|
|
|
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:
int
Liblvls__Level__updateProperty(
Liblvls__Level *self,
const char *s_name,
const char *s_tag1,
const char *s_tag2,
const char *s_value
);
Input:
Routine returns true (1) if the property was successfully updated and false (0) if not. On 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 to be attached is not valid, error handling is invoked. Example: Update the level p_level to include an parity stored in the string named s_parity:
Liblvls__Level__updateProperty(
p_level,
"parity",
NULL,
NULL,
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__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(
const 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:
const char *
Liblvls__SpColl__getProperty(
const Liblvls__SpColl *self,
const char *s_label1,
const char *s_label2,
const char *s_label3
);
Input:
If the property is found, a const char * pointing to the property is returned. If the property is not found, NULL is returned. Example: Retrieve a property named "group_name" from species collection my_spcoll:
s_group_name =
Liblvls__SpColl__getProperty(
my_spcoll, "group_name", NULL, NULL
);
|
|
|
Name: Liblvls__SpColl__getSpecies()Description: Routine to retrieve a species from a species collection. Syntax:
Liblvls__Species *
Liblvls__SpColl__getSpecies(
const 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(
const 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. Species are iterated in alphabetical order according their names. 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:
int
Liblvls__SpColl__updateProperty(
Liblvls__SpColl *self,
const char *s_name,
const char *s_tag1,
const char *s_tag2,
const char *s_value
);
Input:
Routine returns true (1) if the property was successfully updated and false (0) if not. On 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 collection to which the property is to be attached is not valid, error handling is invoked. Example: Update the species collection p_spcoll to include a group number stored in the string named s_group_number:
Liblvls__SpColl__updateProperty(
p_spcoll,
"group_number",
NULL,
NULL,
s_group_number
);
|
|
|
Name: Liblvls__SpColl__writeToXmlFile()Description: Output a Liblvls__SpColl structure to an xml file. Syntax:
void
Liblvls__SpColl__writeToXmlFile(
const 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__computeLevelEquilibriumProbabilities()Description: Compute the equilibrium probabilities for a levels of a species for the input temperature. Syntax:
gsl_vector *
Liblvls__Species__computeLevelEquilbriumProbabilities(
Liblvls__Species *self,
double d_T
);
Input:
Returns a new gsl_vector containing the equilibrium probabilites for all levels in the species. The probabilities are located in the vector according to the level index (ground state with index 0). If any input is invalid, error handling is invoked. Example: Compute the equilibrium probabilities for all levels in p_species at 10,000 K:
p_equilibrium_probabilities =
Liblvls__Species__computeLevelEquilibriumProbabilities(
p_species,
1.e4
);
|
|
|
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(
const 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(
const Liblvls__Species *self,
size_t 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, 3L
);
|
|
|
Name: Liblvls__Species__getName()Description: Routine to return the name of a species. Syntax:
const char *
Liblvls__Species__getName(
const 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(
const 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:
const char *
Liblvls__Species__getProperty(
const Liblvls__Species *self,
const char *s_label1,
const char *s_label2,
const char *s_label3
);
Input:
If the property is found, a const char * pointing to the property is returned. If the property is not found, NULL is returned. Example: Retrieve a property called "atomic_number" from species my_species:
s_atomic_number =
Liblvls__Species__getProperty(
my_species, "atomic_number", NULL, NULL
);
|
|
|
Name: Liblvls__Species__iterateLevels()Description: Iterate through the levels and apply the user-supplied iterate function. Syntax:
void
Liblvls__Species__iterateLevels(
const 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. Levels are iterated according to their index. 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:
int
Liblvls__Species__removeLevel(
Liblvls__Species *self,
Liblvls__Level *p_level
);
Input:
Routine returns 1 (true) if removal successful and 0 (false) if not. 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:
int
Liblvls__Species__updateProperty(
Liblvls__Species *self,
const char *s_name,
const char *s_tag1,
const char *s_tag2,
const char *s_value
);
Input:
Routine returns true (1) if the property was successfully updated and false (0) if not. On 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 to be attached is not valid, error handling is invoked. Example: Update the species p_species to include an atomic number stored in the string named s_atomic_number:
Liblvls__Species__updateProperty(
p_species,
"atomic_number",
NULL,
NULL,
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(
const 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(
const Liblvls__Zone *self,
const Liblvls__Species *p_species,
const 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(
const Liblvls__Zone *self,
const Liblvls__Species *p_species,
const 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(
const Liblvls__Zone *self,
const 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:
const char *
Liblvls__Zone__getProperty(
const Liblvls__Zone *self,
const char *s_label1,
const char *s_label2,
const char *s_label3
);
Input:
If the property is found, a const char * pointing to the property is returned. If the property is not found, NULL is returned. Example: Retrieve a property with first label "temperature" from zone my_zone:
s_temperature =
Liblvls__Zone__getProperty(
my_zone, "temperature", NULL, NULL
);
|
|
|
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:
int
Liblvls__Zone__updateProperty(
Liblvls__Zone *self,
const char *s_name,
const char *s_tag1,
const char *s_tag2,
const char *s_value
);
Input:
Routine returns true (1) if the property was successfully updated and false (0) if not. On 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 to be attached is not valid, error handling is invoked. Example: Update the zone p_zone to include a temperature stored in the string named s_temperature:
if(
!(
Liblvls__Zone__updateProperty(
p_zone,
"temperature",
NULL,
NULL,
s_temperature
)
)
fprintf( stderr, "Update failed.\n" );
|
|
|
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(
const 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(
const 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(
const 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. Syntax:
void
Liblvls__iterateZones(
const 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. Zones are iterated in alphabetical order according to their labels. 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(
const 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" );
|
|
|
