Handling SKIRT text input/output files. More...

Functions
def	_indexForDescriptionInHeader (spec, header)
	This helper function searches the header metadata for a column with a description containing the specified string. More...

def	_representsInteger (value)
	This helper function returns true is the specified value can be converted to an integer, and False otherwise. More...

def	getColumnDescriptions (path)
	This function reads the header of a SKIRT column text file, and returns a list of the column descriptions, in order of occurrence. More...

def	getQuantityFromFile (path, trigger, header)
	This function extracts a numeric value from a text file such as a SKIRT log file or a file produced by SKIRT's ConvergenceInfoProbe class. More...

def	loadColumns (path, columns=None)
	This function loads data from a SKIRT column text file, using the metadata in the file's header to assign appropriate units to each column, and optionally, to locate columns by name. More...

def	saveColumns (path, quantities, units, descriptions, *title=None, fmt="%1.9e")
	This function writes data to a SKIRT column text file, generating the metadata in the file's header from the information provided to the function, and automatically converting the data to the specified units. More...

Detailed Description

Handling SKIRT text input/output files.

This module offers functions for reading information from SKIRT text output files (including column text files, log file and convergence reports) and for writing SKIRT text input files (column text files).

Function Documentation

◆ _indexForDescriptionInHeader()

def pts.simulation.text._indexForDescriptionInHeader	(	spec,
		header
	)

private

This helper function searches the header metadata for a column with a description containing the specified string.

If there is exactly one such column, the function returns its zero-based index. Otherwise, it raises an error.

◆ _representsInteger()

def pts.simulation.text._representsInteger ( value )

private

This helper function returns true is the specified value can be converted to an integer, and False otherwise.

◆ getColumnDescriptions()

def pts.simulation.text.getColumnDescriptions ( path )

This function reads the header of a SKIRT column text file, and returns a list of the column descriptions, in order of occurrence.

If the specified file does not have a column header in SKIRT format, the function returns an empty list. The file path is interpreted as described for the pts.utils.absPath() function.

◆ getQuantityFromFile()

def pts.simulation.text.getQuantityFromFile	(	path,
		trigger,
		header
	)

This function extracts a numeric value from a text file such as a SKIRT log file or a file produced by SKIRT's ConvergenceInfoProbe class.

The value is returned as an astropy quantity with appropriate units, assuming that a valid unit string has been found in the text file.

The file path is interpreted as described for the pts.utils.absPath() function. The text line containing the value is located by the trigger (a text string that must occur on a line before the one containing the value) and the header (a text string that must occur on the line containing the field). In fact, the trigger can consist of multiple subtriggers, separated by forward slashes, that must be triggered in sequence before the function starts looking for the header. If no conforming line is found, the function raises an error.

If the selected line has a section between parentheses at the end, this section (including parentheses) is removed. Then the line is split in segments on white space. If the last segment is a valid representation of a floating point number, this number is returned as a dimensionless quantity. Otherwise, the last two segments represent the value and the unit string, respectively. If there are problems converting these representations, the function raises an error.

For example, the following call will return the total gridded dust mass from a spatial grid convergence file:

getQuantityFromFile("xxx_convergence.dat", "Dust/Total mass", "Gridded")

and the following call will return the total metallic mass for the first particle medium from a log file:

getQuantityFromFile("xxx_log.txt", "ParticleMedium", "Total metallic mass")

◆ loadColumns()

def pts.simulation.text.loadColumns	(	path,
		columns = `None`
	)

This function loads data from a SKIRT column text file, using the metadata in the file's header to assign appropriate units to each column, and optionally, to locate columns by name.

Note: The specified file must have a column header in SKIRT format, because the information in the header is used to determine the appropriate units for each column. If the file does not have a conforming column header, use the numpy.loadtxt() function directly.

The file path is interpreted as described for the pts.utils.absPath() function.

The columns to be loaded can be specified in one of the following ways:

A sequence (list or tuple) of integers specifying zero-based column indices.
A single string including a comma-separated list of one-based column indices and/or description fragments; each fragment must be contained in exactly one column description in the file header.
None or omitted: causes all columns to be loaded.

The function always returns a list of astropy quantities, even if only one column has been loaded. The units for each item are derived from the metadata in the file header. If the file contains a single row, each item in the returned list is a scalar astropy quantity. Otherwise each item in the list is an astropy quantity array, and all arrays have the same length.

◆ saveColumns()

def pts.simulation.text.saveColumns	(		path,
			quantities,
			units,
			descriptions,
		*	title = `None`,
			fmt = `"%1.9e"`
	)

This function writes data to a SKIRT column text file, generating the metadata in the file's header from the information provided to the function, and automatically converting the data to the specified units.

The function expects the following arguments:

path: the file path to the output file, interpreted as described for the pts.utils.absPath() function.
quantities: a sequence of astropy quantity arrays of the same length, one for each column (if the output has only a single row, each item in sequence is a scalar astropy quantity).
units: a string containing a comma-separated list of valid SKIRT unit strings.
descriptions: a string containing a comma-separated list of quantity descriptions.
title: an optional title string written as the first line of the file; default is no title
fmt: an optional format string; the default format is "%1.9e".

The arguments must specify the same number of quantities, units, and descriptions. The units and descriptions will appear in the header of the output file. The quantities are converted to the requested units before being written to the file.

Functions