Module ALI

Run the energy balance module concurrently with the ALI RT code.

The method iterates between EB and ALI, updating the temperature profile and level populations between different iterations.

ALI always starts first, so that the EB always has level populations to work with. Make sure the inputfile for ALI and for EB have the same initial T profile.

If more than one molecule is requested, ALI is ran for each molecule, then EB takes into account all molecules in one go, after which the method goes back to ALI for one molecule at a time.

Automatically updates the ALI inputfile with filename for the temperature input. Adds '_iter' to the ALI input filename and the level populations as well as temperature output files to help differentiate between the initial calculation and the iterations. Note that the .pop file is used by the EB, while ALI works with the .popiter file (that doesn't change name at all). They should give the same populations between iterations. The .popiter file is the one given in the ALI inputfile, while the .pop file is based on the inputfilename and is created at the end of an ALI run. The .pop filenames (one for every molecule) are the input for EB's pop keyword and must be set by the user in either an EB inputfile or as keyword in kwargs.

Input includes

• ALI input filename
• Number of iterations to run in ALI and EB (0 if convergence is needed)
• Less strict ALI convergence criterion for iterations 1 up to n-1
• Additional arguments for the ALI execution
• Additional keyword arguments for the temperature iteration (iterT)
• Additional args/kwargs for the EnergyBalance object initialisation

The EB input template is MCP by default, but a different template can be passed to kwargs. Anything defined in the EB input template can be redefined in args and kwargs as well as by passing fn to this function call, which points to the EB inputfile (not the template!).

Note that ALI iterations do not share information, while the EB keeps track of all previous iterations. At the end of the method, the EB object is returned in case you want to use it to check the different iterations after the calculation is done, including temperature, level populations, heating and cooling terms, etc.

In terms of initial populations, the user can specify whether to use TexGuess = -1 or TexGuess = 0.9, i.e. start from the pops calculated in the previous iteration (keep_pop on), or start from the standard initial conditions.

If you have an EnergyBalance object from a previous iteration or call to this function, you can also pass this, and the method will continue with that object instead. Make sure to adapt your iTmax and such to this object.

Parameters:

• afn (str/list[str]) - The inputfile name for ALI. One filename given as a string in case of one molecule, multiple filenames given as strings in a list in case of multiple molecules.
• ai (int) - The amount of iterations to do in the ALI calculation. Set to the default of 0 if you wish to let ALI converge to whatever convergence criterion set in the ALI input OR by the iter_conv keyword. This is not applicable to the first run of ALI.

  (default: 0)

• ei (int) - The amount of iterations to do in the temperature calculation during the energy balance. Set to the default of 0 if you wish to let the energy balance converge to whatever convergence criterion is determined for/by iterT. This is not applicable to the first run of EB (use imax in iterT_kwargs in that case). Cannot be 1.

  (default: 0)

• iTmax (int) - The maximum total number of iterations allowed for the EB. This is the sum of all iterations between ALI and EB, and so is different from imax in EB.iterT! It is primarily used to put an upper limit on the while loop of the ALI vs EB iteration.

  (default: 200)

• iter_conv (float) - The convergence criterion to use in ALI during iteration with the energy balance. Reverts to the requested value in the ALI inputfile at the end of the iteration. If more strict than the criterion given in the ALI inputfile this keyword is ignored. Default in case the same convergence criterion should be used as in the ALI inputfile during the iteration.

  (default: 0)

• runALIinit (bool) - Run the initial iteration of ALI. In some cases, this model is already calculated, in which case the code starts from the existing files.

  (default: 0)

• iter_texguess (float) - The TexGuess value for the iterations (ie not the first calculation, in which case the value is given in the inputfile). Typically this is 0.9 for standard initial conditions, but alternative could be -1 to start off from the populations calculated in the previous iteration.

  (default: 0.9)

• ALI_args (list[str]) - Additional arguments that are appended to the execute command separated by spaces. If a single string is given, only that string is added to the command. Default if no extra arguments are needed.

  (default: [])

• iterT_kwargs (dict) - Additional arguments for the energy balance temperature iteration. See method iterT in EnergyBalance for more information.

  (default: {})

• eb (EnergyBalance()) - An EnergyBalance object from a previous call. The method will simply continue with this object rather than making a new one. By default runALIinit will be off.

  (default: None)

Returns: EnergyBalance()

The EnergyBalance object is returned with all its properties.

Update the ALI inputfile with new information for the next iteration.

Parameters:

• fn (str) - The full original ALI inputfilename
• fnT (str) - The full filename of the temperature profile
• ai (int) - The amount of iterations to do in the ALI calculation. Set to the default of 0 if you wish to let ALI converge to whatever convergence criterion set in the ALI input OR by the iter_conv keyword.

  (default: 0)

• conv (float) - The convergence criterion to use in ALI during iteration with the energy balance. If more strict than the criterion given in the ALI inputfile this keyword is ignored. Default in case the same convergence criterion should be used as in the ALI inputfile during the iteration.

  (default: 0)

• texguess (float) - The TexGuess value for the iterations. Typically this is 0.9 for standard initial conditions, but alternative could be -1 to start off from the populations calculated in the previous iteration.

  (default: 0.9)

• fn_new (str) - The new (full) ALI inputfile name. Default if original is to be updated.

  (default: None)

Call the ALI executable for a given filename.

Note that the filename should be located in the ALI home folder (given in usr/Path.dat), and that the ouput of the code will given there as well.

This method changes the working directory to the ALI home folder.

Parameters:

• fn (str) - The full ALI inputfilename.
• args (list[str]) - Additional arguments that are appended to the execute command separated by spaces. If a single string is given, only that string is added to the command. Default if no extra arguments are needed.

  (default: [])

Retrieve data from an ALI inputfile.

Returns the line following the line that contains the given key.

Parameters:

• k (str) - The unique input key word for which the ALI inputfile is searched.
• data (list[str]) - The data, ie a file read by readFile with delimiter set to '' A filename must be given if data is None.

  (default: None)

• fn (str) - The ALI input filename. Only used if data is None.

  (default: None)

Returns: str

The line following the line that contains given key

Update an ALI inputfile with new information.

Takes an input key and value. The file is searched for the key, and the value is inserted on the next line.

The content is then returned. This method does not save the file.

Parameters:

• k (str) - The unique input key word for which the ALI inputfile is searched.
• v (str) - The value inserted on the next line after key. Must be a formatted string; no formatting is done here.
• data (list[str]) - The data, ie a file read by readFile with delimiter set to '' A filename must be given if data is None.

  (default: None)

• fn (str) - The ALI input filename. Only used if data is None.

  (default: None)

Returns: list[str]

The data as read from a file or as adapted from the original