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.
This tutorial demonstrates how to use example codes in the liblvls distribution src/examples directory. The sample input files used in the tutorial are included in the distribution release and may be located in the data_pub directory.
Example 1: Read a level data ascii file and output to liblvls xml file.
liblvls routines demonstrated in example1.c are:
- Line 75: Liblvls__SpColl__new()
- Line 93: Liblvls__Species__new()
- Line 104: Liblvls__Species__updateProperty()
- Line 114: Liblvls__Species__free()
- Line 115: Liblvls__SpColl__free()
- Line 125: Liblvls__Level__new()
- Line 134: Liblvls__Level__updateProperty()
- Line 152: Liblvls__Species__addLevel()
- Line 168: Liblvls__Level__updateTransitionData()
- Line 183: Liblvls__SpColl__addSpecies()
- Line 189: Liblvls__SpColl__writeToXmlFile()
To run example1, type the following on the command line:
./example1 ../../data_pub/levels.txt ex1_output.xml
The result is ex1_output.xml
Example 2: Print out level data for species included in an XML file.
liblvls routines demonstrated in example2.c are:
- Line 69: Liblvls__SpColl__is_valid_input_xml()
- Line 88: Liblvls__SpColl__new_from_xml()
- Line 105: Liblvls__SpColl__getProperty()
- Line 127: Liblvls__SpColl__iterateSpecies()
- Line 139: Liblvls__SpColl__getNumberOfSpecies()
- Line 146: Liblvls__SpColl__free()
- Line 168: Liblvls__Species__getProperty()
- Line 174: Liblvls__Species__getName()
- Line 175: Liblvls__Species__getNumberOfLevels()
To run example2, type the following on the command line:
./example2 ../../data_pub/spcoll.xml > ex2_output.txt
The result is ex2_output.txt
It is also possible to retrieve the XML level data from a remote host over the web. For example, to retrieve the level data from the webnucleo server, type:
./example2 http://www.webnucleo.org/home/modules/liblvls/0.2/data_pub/spcoll.xml > ex2_output_web.txt
The result is ex2_output_web.txt
Example 3: Read in level data from an XML file, create a Liblvls structure, and print out data for the levels for a given species in the selected units.
liblvls routines demonstrated in example3.c are:
- Line 68: Liblvls__SpColl__new_from_xml()
- Line 81: Liblvls__SpColl__getSpecies()
- Line 85: Liblvls__SpColl__free()
- Line 101: Liblvls__Species__getNumberOfLevels()
- Line 108: Liblvls__Species__getLevelByIndex()
- Line 115: Liblvls__Species__removeLevel()
- Line 172: Liblvls__Species__getName()
- Line 185: Liblvls__Species__iterateLevels()
- Line 204: Liblvls__Level__getProperty()
- Line 209: Liblvls__Level__getEnergy()
- Line 211: Liblvls__get_energy_units()
- Line 213: Liblvls__Level__getMultiplicity()
To run example3, type the following on the command line:
./example3 ../../data_pub/spcoll.xml al26 keV > ex3_output.txt
The result is ex3_output.txt
It is possible to use liblvls for atomic or molecular level data as well as nuclear. For example, to view data for neutral helium (He I), type:
./example3 ../../data_pub/he_i.xml "He I" eV > ex3_output_atomic.txt
The result is ex3_output_atomic.txt
Example 4: Read in level data from an XML file, create a Liblvls structure, and compute the partition function for each species at the input temperature.
liblvls routines demonstrated in example4.c are:
- Line 61: Liblvls__SpColl__new_from_xml()
- Line 64: Liblvls__SpColl__free()
- Line 85: Liblvls__SpColl__iterateSpecies()
- Line 110: Liblvls__Species__getName()
- Line 111: Liblvls__Species__computePartitionFunction()
To run example4, type the following on the command line:
./example4 ../../data_pub/spcoll.xml 5.e8 > ex4_output.txt
The result is ex4_output.txt
Example 5: Read in level data from an XML file, create a Liblvls structure, and compute the partition function for the input species at a variety of temperatures.
liblvls routines demonstrated in example5.c are:
- Line 61: Liblvls__SpColl__new_from_xml()
- Line 75: Liblvls__SpColl__getSpecies()
- Line 79: Liblvls__SpColl__free()
- Line 94: Liblvls__Species__computePartitionFunction()
To run example5, type the following on the command line:
./example5 ../../data_pub/spcoll.xml al26 > ex5_output.txt
The result is ex5_output.txt
Example 6: Read in level data from an XML file, create a Liblvls structure, and compute the equilibrium probabilities for the input species at the input temperature.
liblvls routines demonstrated in example6.c are:
- Line 83: Liblvls__SpColl__new_from_xml()
- Line 92: Liblvls__SpColl__getSpecies()
- Line 96: Liblvls__SpColl__free()
- Line 118: Liblvls__Species__computePartitionFunction()
- Line 127: Liblvls__Species__computeLevelEquilibriumProbabilities()
- Line 132: Liblvls__Species__iterateLevels()
- Line 166: Liblvls__Level__computeBoltzmannFactor()
- Line 168: Liblvls__Level__getEnergy()
- Line 172: Liblvls__Level__getMultiplicity()
- Line 174: Liblvls__Level__getIndex()
To run example6, type the following on the command line:
./example6 ../../data_pub/spcoll.xml al26 1.5e9 > ex6_output.txt
The result is ex6_output.txt
Example 7: Read in level data from an XML file, create a Liblvls structure, and compute the Einstein coefficients between two levels for the given species.
liblvls routines demonstrated in example7.c are:
- Line 72: Liblvls__SpColl__new_from_xml()
- Line 80: Liblvls__SpColl__getSpecies()
- Line 84: Liblvls__SpColl__free()
- Line 92: Liblvls__Species__getNumberOfLevels ()
- Line 124: Liblvls__Species__getLevelByIndex()
- Line 133: Liblvls__Level__getEnergy()
- Line 146: Liblvls__Level__computeEinsteinCoefficients()
To run example7, type the following on the command line:
./example7 ../../data_pub/spcoll.xml al26 7 2 > ex7_output.txt
The result is ex7_output.txt
Example 8: Read in level data from an XML file, create a Liblvls structure, and compute the transition rates between two levels for the given species at the given temperature.
liblvls routines demonstrated in example8.c are:
- Line 79: Liblvls__SpColl__new_from_xml()
- Line 87: Liblvls__SpColl__getSpecies()
- Line 91: Liblvls__SpColl__free()
- Line 99: Liblvls__Species__getNumberOfLevels ()
- Line 127: Liblvls__Species__getLevelByIndex()
- Line 135: Liblvls__Species__computeRatesForTransition()
To run example8, type the following on the command line:
./example8 ../../data_pub/spcoll.xml al26 2.e9 7 2 > ex8_output.txt
The result is ex8_output.txt
Example 9: Read in level data from an XML file, create a Liblvls structure, and compute the rate matrix for the given species at the given temperature.
liblvls routines demonstrated in example9.c are:
- Line 75: Liblvls__SpColl__new_from_xml()
- Line 81: Liblvls__SpColl__getSpecies()
- Line 88: Liblvls__Species__computeRateMatrix()
- Line 104: Liblvls__SpColl__free()
To run example9, type the following on the command line:
./example9 ../../data_pub/spcoll.xml al26 1.e9 ex9_output.txt
The result is ex9_output.txt
Example 10: Read in level data from XML file(s), create a Liblvls structure, and print the input probabilities for a given species for a given zone.
liblvls routines demonstrated in example10.c are:
- Line 89: Liblvls__is_valid_input_xml()
- Line 98: Liblvls__SpColl__is_valid_input_xml()
- Line 105: Liblvls__is_valid_zone_input_xml()
- Line 121: Liblvls__new_from_xml()
- Line 124: Liblvls__free()
- Line 128: Liblvls__new()
- Line 130: Liblvls__SpColl__updateFromXml()
- Line 131: Liblvls__getSpColl()
- Line 136: Liblvls__updateZonesFromXml()
- Line 146: Liblvls__getZone()
- Line 170: Liblvls__SpColl__getSpecies()
- Line 206: Liblvls__Species__iterateLevels()
- Line 234: Liblvls__Level__getIndex()
- Line 235: Liblvls__Level__getEnergy()
- Line 236: Liblvls__Zone__getLevelProbability()
To run example10, type the following on the command line:
./example10 ../../data_pub/spcoll.xml ../../data_pub/zone_data.xml al26 1 0 0 > ex10_output.txt
The result is ex10_output.txt
The species collection and zone data XML files may be combined into a single liblvls input file. Use xsltproc (which you should have installed as described in the compile tutorial):
xsltproc --stringparam zone_doc ../data_pub/zone_data.xml ../../xsl_pub/merge.xsl ../../data_pub/spcoll.xml > ../../data_pub/levels.xml
The new liblvls XML input file may be used in place of the species collection and zone data files:
./example10 ../../data_pub/levels.xml al26 1 0 0 > ex10_output_combined.txt
The result is ex10_output_combined.txt
Example 11: Read in level data from an XML file, create a Liblvls structure, and evolve the level probabilities in the input zone for the input time, using the temperature given in the optional properties for the zone.
liblvls routines demonstrated in example11.c are:
- Line 89: Liblvls__new_from_xml()
- Line 92: Liblvls__free()
- Line 101: Liblvls__getZone()
- Line 117: Liblvls__Zone__getProperty()
- Line 128: Liblvls__SpColl__getSpecies()
- Line 129: Liblvls__getSpColl()
- Line 196: Liblvls__Species__computeRateMatrix()
- Line 206: Liblvls__Zone__computeFlowVector()
- Line 218: Liblvls__Zone__getProbabilities()
- Line 221: Liblvls__Zone__updateProbabilities()
- Line 266: Liblvls__Species__iterateLevels()
- Line 296: Liblvls__Zone__getLevelProbability()
- Line 300: Liblvls__Zone__getLevelProbabilityChange()
- Line 352: Liblvls__Species__computePartitionFunction()
- Line 396: Liblvls__Level__getIndex()
- Line 397: Liblvls__Level__getEnergy()
- Line 401: Liblvls__Level__computeBoltzmannFactor()
To run example11, type the following on the command line:
./example11 ../../data_pub/levels.xml al26 1. 2 0 0 > ex11_output.txt
The result is ex11_output.txt
Example 12: Run a multi-zone level probability evolution calculation for for the input species for the given duration and mixing time between zones, using the temperatures given in the optional properties for the zones.
liblvls routines demonstrated in example12.c are:
- Line 118: Liblvls__new_from_xml()
- Line 121: Liblvls__free()
- Line 132: Liblvls__SpColl__getSpecies()
- Line 133: Liblvls__getSpColl()
- Line 151: Liblvls__getNumberOfZones()
- Line 160: Liblvls__iterateZones()
- Line 260: Liblvls__Zone__getProperty()
- Line 348: Liblvls__Species__getNumberOfLevels()
- Line 488: Liblvls__Zone__computeFlowVector()
- Line 506: Liblvls__Species__computeRateMatrix()
- Line 574: Liblvls__Species__iterateLevels()
- Line 612: Liblvls__Level__getIndex()
- Line 630: Liblvls__Zone__getLevelProbability()
- Line 722: Liblvls__Zone__getProbabilities()
- Line 734: Liblvls__Zone__updateProbabilities()
- Line 841: Liblvls__Zone__getLevelProbabilityChange()
- Line 929: Liblvls__Zone__getLabel()
- Line 960: Liblvls__Species__computePartitionFunction()
- Line 1006: Liblvls__Level__getEnergy()
- Line 1010: Liblvls__Level__computeBoltzmannFactor()
To run example12, type the following on the command line:
./example12 ../../data_pub/levels.xml al26 1. 0.1 > ex12_output.txt
The result is ex12_output.txt
Example 13: Read in a liblvls input file and calculate transition rates for any down-transitions that do not exist in the file, then write this new data to an xml file.
liblvls routines demonstrated in example13.c are:
- Line 75: Liblvls__new_from_xml()
- Line 78: Liblvls__free()
- Line 82: Liblvls__getSpColl()
- Line 88: Liblvls__SpColl__iterateSpecies()
- Line 98: Liblvls__writeToXmlFile()
- Line 117: Liblvls__Level__getMultiplicity()
- Line 144: Liblvls__Level__getEnergy()
- Line 211: Liblvls__Species__getProperty()
- Line 218: Liblvls__Species__iterateLevels()
- Line 302: Liblvls__Level__computeEinsteinCoefficients()
- Line 323: Liblvls__Level__getProperty()
- Line 383: Liblvls__Level__updateTransitionData()
To run example13, type the following on the command line:
./example13 ../../data_pub/levels.xml ex13_output.xml
The result is ex13_output.xml
Example 14: Read in a liblvls input file and calculate the rates of photonic and collisional excitation between two provided levels using a temperature and hydrogen number density provided as optional zone properties.
liblvls routines demonstrated in example14.c are:
- Line 84: Liblvls__new_from_xml()
- Line 86: Liblvls__getSpColl()
- Line 92: Liblvls__getZone()
- Line 99: Liblvls__Zone__getProperty()
- Line 115: Liblvls__SpColl__getSpecies()
- Line 119: Liblvls__SpColl__free()
- Line 127: Liblvls__Species__getNumberOfLevels ()
- Line 151: Liblvls__Species__getLevelByIndex()
- Line 158: Liblvls__Species__computeRatesForTransition()
- Line 191: Liblvls__Species__setTransitionRatesFunction()
- Line 223: Liblvls__Species__clearTransitionRatesFunction()
- Line 224: Liblvls__free()
- Line 246: Liblvls__Level__getProperty()
- Line 267: Liblvls__Level__getMultiplicity()
- Line 279: Liblvls__Level__getEnergy()
To run example14, type the following on the command line:
./example14 ../../data_pub/CO_data.xml 11 0 3 0 0 > ex14_output.txt
The result is ex14_output.txt
