| 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. |
Name: Liblvls__compare_function()Description: User-supplied routine to be applied during an iteration of levels, species, or zones. Syntax:
int
Liblvls__compare_function(
const void *p_data_1,
const void *p_data_2
);
Input:
User's routine must return -1 if datum 1 is less than datum 2, 0 if the two data are equal, and 1 if datum 1 is greater than datum 2. If this routine is not set, the default function is used. |
| 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. The B coefficients are defined in terms of the mean intensity (that is, the rate per state for stimulated absorption or emission is B times the mean intensity). 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 (cm^2 steradian per erg per s)\n", d_bij
);
printf(
"B_ji = %e (cm^2 steradian per erg per s)\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__clearSpeciesCompareFunction()Description: Restore the default function to be applied during a level iteration. Syntax:
void
Liblvls__SpColl__clearSpeciesCompareFunction(
Liblvls__SpColl *self
);
Input:
Upon successful return, the data compare function for the levels in the species has been restored to the default function. If any input is invalid, error handling is invoked. Example: Clear the comparison function for the levels in p_my_species:
Liblvls__SpColl__clearSpeciesCompareFunction(
p_species
);
|
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. If a species comparison function is not set, 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__removeSpecies()Description: Routine to remove a species from a species collection. Syntax:
int
Liblvls__SpColl__addSpecies(
Liblvls__SpColl *self,
Liblvls__Species *p_species
);
Input:
Routine returns 1 (true) if the remove succeeded and 0 (false) if it did not. Upon successful return, the species has been removed from the collection. If the input collection or species is not valid, error handling is invoked. Example: Remove p_species from the collection p_my_collection:
if( !Liblvls__SpColl__removeSpecies( p_my_collection, p_species ) )
{
fprintf( stderr, "Species removal failed.\n" );
exit( EXIT_FAILURE );
}
|
Name: Liblvls__SpColl__setSpeciesCompareFunction()Description: Set the comparison function to be applied during a species iteration. Syntax:
void
Liblvls__SpColl__setSpeciesCompareFunction(
Liblvls__SpColl *self,
Liblvls__compare_function pf_func
);
Input:
Upon successful return, the data compare function for the species in the collection has been set to the input function. If any input is invalid, error handling is invoked. Example: Set the level comparison function for p_my_spcoll to species_compare:
Liblvls__SpColl__setSpeciesCompareFunction(
p_my_spcoll,
(Liblvls__compare_function) species_compare
);
|
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__clearLevelCompareFunction()Description: Restore the default function to be applied during a level iteration. Syntax:
void
Liblvls__Species__clearLevelCompareFunction(
Liblvls__Species *self
);
Input:
Upon successful return, the data compare function for the levels in the species has been restored to the default function. If any input is invalid, error handling is invoked. Example: Clear the comparison function for the levels in p_my_species:
Liblvls__Species__clearLevelCompareFunction(
p_species
);
|
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 currently set level index. 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__extractLevelSubset()Description: Routine to extract a level subset from a species. Syntax:
Liblvls__Species *
Liblvls__Species__new(
const Liblvls__Species *self
const char *s_level_xpath
);
Input:
Routine returns a pointer to a new species. The new species has all the properties of the input species but the levels in the new species are restricted to those determined by the XPath expression. If the input species is not valid, or if the new species cannot be allocated, error handling is invoked. Examples: Get a full copy of p_species:
p_copy = Liblvls__Species__extractLevelSubset( p_species, NULL );
Get a copy of p_species but only with levels with energy between
2 MeV and 5 MeV (convert to keV):
p_subset =
Liblvls__Species__extractLevelSubset(
p_species,
"[properties/energy >= '2000' and properties/energy <= 5000']"
);
|
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. If a level comparison function is not set, levels are iterated according to their currently set 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__setLevelCompareFunction()Description: Set the comparison function to be applied during a level iteration. Syntax:
void
Liblvls__Species__setLevelCompareFunction(
Liblvls__Species *self,
Liblvls__compare_function pf_func
);
Input:
Upon successful return, the data compare function for the levels in the species has been set to the input function. If any input is invalid, error handling is invoked. Example: Set the level comparison function for p_my_species to level_compare:
Liblvls__Species__setLevelCompareFunction(
p_my_species,
(Liblvls__compare_function) level_compare
);
|
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__sortLevels()Description: Sort the levels in a species. Syntax:
void
Liblvls__Species__sortLevels(
Liblvls__Species *self
);
Input:
Upon successful return, the levels in the species have been sorted according to the currently set level comparison function for the species. Example: Sort the levels in p_my_species:
Liblvls__Species__sortLevels(
p_species
);
|
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__Species__updateXmlEinsteinCoefficientFormat()Description: Update the format code for XML output of Einstein A coefficients for a transitions in species. Syntax:
void
Liblvls__Species__updateXmlEinsteinCoefficientFormat(
Liblvls__Species *self,
const char * s_einstein_coeff_format
);
Input:
On successful return, the format code for Einstein A coefficients to XML has been updated. If the input species is invalid, Liblvls error handling is invoked. Example: Update the level XML output format for Einstein coefficients for p_species to %.4e:
Liblvls__Species__updateXmlEinsteinCoefficientFormat(
p_species,
"%.4e"
);
|
Name: Liblvls__Species__updateXmlLevelEnergyFormat()Description: Update the format code for XML output of level energies for a species. Syntax:
void
Liblvls__Species__updateXmlLevelEnergyFormat(
Liblvls__Species *self,
const char * s_energy_format
);
Input:
On successful return, the format code for level energy output to XML has been updated. If the input species is invalid, Liblvls error handling is invoked. Example: Update the level XML output format for level energy for p_species to %.4e:
Liblvls__Species__updateXmlLevelEnergyFormat(
p_species,
"%.4e"
);
|
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__copy()Description: Copy a Liblvls__Zone. Syntax:
Liblvls__Zone *
Liblvls__Zone__copy(
const Liblvls__Zone *self
);
Input:
Routine returns a copy of the input zone. If the input is invalid, Liblvls error handling is invoked. Example: Copy p_zone:
p_copy = Liblvls__Zone__copy( p_zone );
|
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__new()Description: Routine to create a new zone. Syntax:
Liblvls__Zone *
Liblvls__Zone__new(
Liblvls__SpColl *p_spcoll,
const char *s_label_1,
const char *s_label_2,
const char *s_label_3
);
Input:
Routine returns a pointer to a new zone. If memory cannot be allocated, error handling is invoked. Example: Create the zone with labels "x1", "y1", and "z1":
p_zone =
Liblvls__Zone__new(
p_my_species_collection,
"x1",
"y1",
"z1"
);
|
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__addZone()Description: Routine to add a zone to a Liblvls structure. Syntax:
int
Liblvls__addZone(
Liblvls *self,
Liblvls__Zone *p_zone
);
Input:
Routine returns 1 (true) if the addition succeeded or 0 (false) if not. Upon successful return, the zone has been added. If input is invalid, error handling is invoked. Example: Add p_zone to p_my_liblvls:
if( Liblvls__addZone( p_my_liblvs, p_zone ) )
fprintf( stdout, "Addition succeeded.\n" );
|
Name: Liblvls__clearZoneCompareFunction()Description: Restore the default function to be applied during a zone iteration. Syntax:
void
Liblvls__clearZoneCompareFunction(
Liblvls *self
);
Input:
Upon successful return, the data compare function for the zones has been restored to the default function. If any input is invalid, error handling is invoked. Example: Clear the comparison function for the zones in p_liblvls:
Liblvls__clearZoneCompareFunction(
p_species
);
|
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. If a zone comparison function is not set, 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__relabelZone()Description: Relabel a zone in a liblvls structure. Syntax:
int
Liblvls__relabelZone(
Liblvls *self,
Liblvls__Zone *p_zone,
const char *s_new_label_1,
const char *s_new_label_2,
const char *s_new_label_3
);
Input:
Routine returns 1 (true) if the relabeling was successful and 0 (false) if not. On successful return, the zone has the new labels. If the input is invalid, Liblvls error handling is invoked. Example: Relabel p_zone in p_my_liblvls from "x1", "y1', "z1" to "x2", "y2", "z2":
p_zone = Liblvls__getZone( p_liblvls, "x1", "y1", "z1" );
if(
!Liblvls__relabelZone(
p_liblvls,
p_zone,
"x2",
"y2",
"z2"
)
)
fprintf( stderr, "Couldn't relabel zone.\n" );
|
Name: Liblvls__removeZone()Description: Routine to remove a zone to a Liblvls structure. Syntax:
int
Liblvls__removeZone(
Liblvls *self,
Liblvls__Zone *p_zone
);
Input:
Routine returns 1 (true) if the removal succeeded or 0 (false) if not. Upon successful return, the zone has been removed. If input is invalid, error handling is invoked. Example: Remove p_zone from p_my_liblvls:
if( !Liblvls__removalZone( p_my_liblvs, p_zone ) )
fprintf( stdout, "Removal failed.\n" );
|
Name: Liblvls__setZoneCompareFunction()Description: Set the comparison function to be applied during a zone iteration. Syntax:
void
Liblvls__setZoneCompareFunction(
Liblvls *self,
Liblvls__compare_function pf_func
);
Input:
Upon successful return, the data compare function for the zones in the species has been set to the input function. If any input is invalid, error handling is invoked. Example: Set the zone comparison function for p_liblvls to zone_compare:
Liblvls__setZoneCompareFunction(
p_liblvls,
(Liblvls__compare_function) level_compare
);
|
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" );
|
Name: Liblvls__writeZoneDataToXmlFile()Description: Output Liblvls zone data to an xml file. Syntax:
void
Liblvls__writeZoneDataToXmlFile(
const Liblvls *self,
const char *s_xml_filename
);
Input:
Upon successful return, the zone data have been written to an xml file. If the input is invalid, Liblvls error handling is invoked. Example: Dump the zone data Liblvls *p_liblvls to the xml file my_zones.xml:
Liblvls__writeZoneDataToXmlFile( p_liblvls, "my_zones.xml" );
|