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 76: Liblvls__SpColl__new()
- Line 94: Liblvls__Species__new()
- Line 103: Liblvls__Species__free()
- Line 104: Liblvls__SpColl__free()
- Line 114: Liblvls__Level__new()
- Line 121: Liblvls__Level__updateProperty()
- Line 134: Liblvls__Species__addLevel()
- Line 150: Liblvls__Level__updateTransitionData()
- Line 165: Liblvls__SpColl__addSpecies()
- Line 171: Liblvls__SpColl__writeToXmlFile()
- Line 76: Liblvls__SpColl__new()
- Line 94: Liblvls__Species__new()
- Line 103: Liblvls__Species__free()
- Line 104: Liblvls__SpColl__free()
- Line 114: Liblvls__Level__new()
- Line 121: Liblvls__Level__updateProperty()
- Line 134: Liblvls__Species__addLevel()
- Line 150: Liblvls__Level__updateTransitionData()
- Line 165: Liblvls__SpColl__addSpecies()
- Line 171: 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 64: Liblvls__SpColl__new_from_xml()
- Line 81: Liblvls__SpColl__getProperty()
- Line 85: Liblvls__Property__getValue()
- Line 103: Liblvls__SpColl__iterateSpecies()
- Line 115: Liblvls__SpColl__getNumberOfSpecies()
- Line 122: Liblvls__SpColl__free()
- Line 145: Liblvls__Species__getProperty()
- Line 151: Liblvls__Species__getName()
- Line 152: Liblvls__Species__getNumberOfLevels()
- Line 64: Liblvls__SpColl__new_from_xml()
- Line 81: Liblvls__SpColl__getProperty()
- Line 85: Liblvls__Property__getValue()
- Line 103: Liblvls__SpColl__iterateSpecies()
- Line 115: Liblvls__SpColl__getNumberOfSpecies()
- Line 122: Liblvls__SpColl__free()
- Line 145: Liblvls__Species__getProperty()
- Line 151: Liblvls__Species__getName()
- Line 152: 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.1/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 67: Liblvls__SpColl__new_from_xml()
- Line 80: Liblvls__SpColl__getSpecies()
- Line 84: Liblvls__SpColl__free()
- Line 100: Liblvls__Species__getNumberOfLevels()
- Line 130: Liblvls__Species__getName()
- Line 143: Liblvls__Species__iterateLevels()
- Line 163: Liblvls__Level__getProperty()
- Line 169: Liblvls__Level__getEnergy()
- Line 171: Liblvls__get_energy_units()
- Line 173: Liblvls__Level__getMultiplicity()
- Line 174: Liblvls__Property__getValue()
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 62: Liblvls__SpColl__new_from_xml()
- Line 65: Liblvls__SpColl__free()
- Line 86: Liblvls__SpColl__iterateSpecies()
- Line 111: Liblvls__Species__getName()
- Line 112: 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 62: Liblvls__SpColl__new_from_xml()
- Line 76: Liblvls__SpColl__getSpecies()
- Line 80: Liblvls__SpColl__free()
- Line 95: Liblvls__Species__computePartitionFunction()
- Line 62: Liblvls__SpColl__new_from_xml()
- Line 76: Liblvls__SpColl__getSpecies()
- Line 80: Liblvls__SpColl__free()
- Line 95: 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__iterateLevels()
- Line 160: Liblvls__Level__computeBoltzmannFactor()
- Line 162: Liblvls__Level__getEnergy()
- Line 166: Liblvls__Level__getMultiplicity()
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 73: Liblvls__SpColl__new_from_xml()
- Line 81: Liblvls__SpColl__getSpecies()
- Line 85: Liblvls__SpColl__free()
- Line 93: 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 80: Liblvls__SpColl__new_from_xml()
- Line 88: Liblvls__SpColl__getSpecies()
- Line 92: Liblvls__SpColl__free()
- Line 100: Liblvls__Species__getNumberOfLevels ()
- Line 126: Liblvls__Species__getLevelByIndex()
- Line 134: 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 76: Liblvls__SpColl__new_from_xml()
- Line 82: Liblvls__SpColl__getSpecies()
- Line 89: Liblvls__Species__computeRateMatrix()
- Line 105: 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 85: Liblvls__new_from_xml()
- Line 88: Liblvls__free()
- Line 92: Liblvls__new()
- Line 94: Liblvls__SpColl__updateFromXml()
- Line 95: Liblvls__getSpColl()
- Line 100: Liblvls__updateZonesFromXml()
- Line 110: Liblvls__getZone()
- Line 134: Liblvls__SpColl__getSpecies()
- Line 170: Liblvls__Species__iterateLevels()
- Line 198: Liblvls__Level__getIndex()
- Line 199: Liblvls__Level__getEnergy()
- Line 200: Liblvls__Zone__getLevelProbability()
- Line 85: Liblvls__new_from_xml()
- Line 88: Liblvls__free()
- Line 92: Liblvls__new()
- Line 94: Liblvls__SpColl__updateFromXml()
- Line 95: Liblvls__getSpColl()
- Line 100: Liblvls__updateZonesFromXml()
- Line 110: Liblvls__getZone()
- Line 134: Liblvls__SpColl__getSpecies()
- Line 170: Liblvls__Species__iterateLevels()
- Line 198: Liblvls__Level__getIndex()
- Line 199: Liblvls__Level__getEnergy()
- Line 200: 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 91: Liblvls__new_from_xml()
- Line 94: Liblvls__free()
- Line 103: Liblvls__getZone()
- Line 118: Liblvls__Zone__getProperty()
- Line 123: Liblvls__Property__getValue()
- Line 132: Liblvls__SpColl__getSpecies()
- Line 133: Liblvls__getSpColl()
- Line 200: Liblvls__Species__computeRateMatrix()
- Line 210: Liblvls__Zone__computeFlowVector()
- Line 222: Liblvls__Zone__getProbabilities()
- Line 225: Liblvls__Zone__updateProbabilities()
- Line 270: Liblvls__Species__iterateLevels()
- Line 300: Liblvls__Zone__getLevelProbability()
- Line 304: Liblvls__Zone__getLevelProbabilityChange()
- Line 356: Liblvls__Species__computePartitionFunction()
- Line 400: Liblvls__Level__getIndex()
- Line 401: Liblvls__Level__getEnergy()
- Line 405: 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 119: Liblvls__new_from_xml()
- Line 122: Liblvls__free()
- Line 133: Liblvls__SpColl__getSpecies()
- Line 134: Liblvls__getSpColl()
- Line 152: Liblvls__getNumberOfZones()
- Line 161: Liblvls__iterateZones()
- Line 259: Liblvls__Zone__getProperty()
- Line 264: Liblvls__Property__getValue()
- Line 352: Liblvls__Species__getNumberOfLevels()
- Line 492: Liblvls__Zone__computeFlowVector()
- Line 510: Liblvls__Species__computeRateMatrix()
- Line 578: Liblvls__Species__iterateLevels()
- Line 616: Liblvls__Level__getIndex()
- Line 631: Liblvls__Zone__getLevelProbability()
- Line 715: Liblvls__Zone__getProbabilities()
- Line 727: Liblvls__Zone__updateProbabilities()
- Line 834: Liblvls__Zone__getLevelProbabilityChange()
- Line 921: Liblvls__Zone__getLabel()
- Line 949: Liblvls__Species__computePartitionFunction()
- Line 992: Liblvls__Level__getEnergy()
- Line 996: 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 76: Liblvls__new_from_xml()
- Line 79: Liblvls__free()
- Line 83: Liblvls__getSpColl()
- Line 89: Liblvls__SpColl__iterateSpecies()
- Line 99: Liblvls__writeToXmlFile()
- Line 118: Liblvls__Level__getMultiplicity()
- Line 145: Liblvls__Level__getEnergy()
- Line 211: Liblvls__Species__getProperty()
- Line 212: Liblvls__Property__getValue()
- Line 219: Liblvls__Species__iterateLevels()
- Line 304: Liblvls__Level__computeEinsteinCoefficients()
- Line 323: Liblvls__Level__getProperty()
- Line 371: 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 86: Liblvls__new_from_xml()
- Line 88: Liblvls__getSpColl()
- Line 94: Liblvls__getZone()
- Line 101: Liblvls__Zone__getProperty()
- Line 108: Liblvls__Property__getValue()
- Line 116: Liblvls__SpColl__getSpecies()
- Line 120: Liblvls__SpColl__free()
- Line 128: Liblvls__Species__getNumberOfLevels ()
- Line 150: Liblvls__Species__getLevelByIndex()
- Line 157: Liblvls__Species__computeRatesForTransition()
- Line 189: Liblvls__Species__setTransitionRatesFunction()
- Line 221: Liblvls__Species__clearTransitionRatesFunction()
- Line 222: Liblvls__free()
- Line 244: Liblvls__Level__getProperty()
- Line 263: Liblvls__Level__getMultiplicity()
- Line 275: 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
