The SKIRT project
advanced radiative transfer for astrophysics
Public Member Functions | Private Attributes | List of all members
pts.simulation.skifile.SkiFile Class Reference

An instance of the SkiFile class represents a particular existing SKIRT parameter file (ski file). More...

Public Member Functions

def __init__ (self, skiFilePath)
 The constructor loads the contents of the specified ski file into a new SkiFile instance. More...
 
def getBoolAttribute (self, xpath, attribute)
 This function returns a Boolean attribute value as a true Python Boolean value. More...
 
def getFloatAttribute (self, xpath, attribute)
 This function returns a numeric attribute value (representing a dimensionless quantity) as a floating point number. More...
 
def getIntAttribute (self, xpath, attribute)
 This function returns a numeric attribute value as an integer number. More...
 
def getQuantityAttribute (self, xpath, attribute)
 This function returns an attribute value representing a physical quantity with given units as an astropy scalar quantity. More...
 
def getQuantityListAttribute (self, xpath, attribute)
 This function returns an attribute value representing a list of comma-separated physical quantities with given units as an astropy quantity array. More...
 
def getStringAttribute (self, xpath, attribute)
 This function returns an attribute value or element tag as a string. More...
 
def getStringAttributes (self, xpath, attribute)
 This function returns a list including the string values of a particular attribute for a number of elements. More...
 
def instrumentNames (self)
 This function returns the names of the instruments in the instrument system as a list of strings, in their order of appearance in the ski file. More...
 
def isOligo (self)
 This function returns True if the simulation mode is oligochromatic, False if it is panchromatic. More...
 
def numPrimaryPackets (self)
 This function returns the number of photon packets launched per simulation segment for primary sources. More...
 
def probeNames (self)
 This function returns the names of the probes in the probe system as a list of strings, in their order of appearance in the ski file. More...
 
def saveTo (self, saveFilePath)
 This function saves the (possibly updated) contents of the SkiFile instance into the specified file. More...
 
def setBoolAttribute (self, xpath, attribute, value)
 This function sets an attribute value from a Boolean value. More...
 
def setFloatAttribute (self, xpath, attribute, value)
 This function sets an attribute value representing a dimensionless quantity from a floating point number. More...
 
def setIntAttribute (self, xpath, attribute, value)
 This function sets an attribute value from an integer number. More...
 
def setNumPrimaryPackets (self, value)
 This function sets the number of photon packets launched per simulation segment for primary sources. More...
 
def setQuantityAttribute (self, xpath, attribute, value, skirtUnit=None)
 This function sets an attribute value representing a physical quantity with given units. More...
 
def setStringAttribute (self, xpath, attribute, value)
 This function sets an attribute value from a string. More...
 
def skiFilePath (self)
 This function returns the absolute file path of the ski file represented by this SkiFile instance. More...
 
def transformIf (self, condition, templates)
 This function applies an XSLT transform to the ski file if an XPath condition evaluates to true. More...
 

Private Attributes

 _path
 
 _tree
 

Detailed Description

An instance of the SkiFile class represents a particular existing SKIRT parameter file (ski file).

There are functions to read information from the ski file, and to adjust specific items in its contents. The class offers two types of functions.

Updates made to a SkiFile instance do not affect the underlying file; use the saveto() function to save the updated contents of a SkiFile instance to another file (or to replace the original file if so desired). A SkiFile class instance is always constructed from an existing ski file; creating a new ski file from scratch is not supported. To create a new ski file, start SKIRT in interactive mode (without any arguments).

Constructor & Destructor Documentation

◆ __init__()

def pts.simulation.skifile.SkiFile.__init__ (   self,
  skiFilePath 
)

The constructor loads the contents of the specified ski file into a new SkiFile instance.

The file path is interpreted as described for the pts.utils.absPath() function. The filename extension of the ski file must be ".ski" or ".xml".

Member Function Documentation

◆ getBoolAttribute()

def pts.simulation.skifile.SkiFile.getBoolAttribute (   self,
  xpath,
  attribute 
)

This function returns a Boolean attribute value as a true Python Boolean value.

The string value is considered to represent True if it contains "true", "t", "yes", "y" or "1" (case insensitive), and False otherwise. The function arguments are the same as those for the getStringAttribute() function.

◆ getFloatAttribute()

def pts.simulation.skifile.SkiFile.getFloatAttribute (   self,
  xpath,
  attribute 
)

This function returns a numeric attribute value (representing a dimensionless quantity) as a floating point number.

The function arguments are the same as those for the getStringAttribute() function.

◆ getIntAttribute()

def pts.simulation.skifile.SkiFile.getIntAttribute (   self,
  xpath,
  attribute 
)

This function returns a numeric attribute value as an integer number.

The function arguments are the same as those for the getStringAttribute() function.

◆ getQuantityAttribute()

def pts.simulation.skifile.SkiFile.getQuantityAttribute (   self,
  xpath,
  attribute 
)

This function returns an attribute value representing a physical quantity with given units as an astropy scalar quantity.

If the attribute value does not include a unit string, the function raises an error. The function arguments are the same as those for the getStringAttribute() function.

◆ getQuantityListAttribute()

def pts.simulation.skifile.SkiFile.getQuantityListAttribute (   self,
  xpath,
  attribute 
)

This function returns an attribute value representing a list of comma-separated physical quantities with given units as an astropy quantity array.

If one of the attribute values does not include a unit string, or the values do not all use the same units, the function raises an error. The function arguments are the same as those for the getStringAttribute() function.

◆ getStringAttribute()

def pts.simulation.skifile.SkiFile.getStringAttribute (   self,
  xpath,
  attribute 
)

This function returns an attribute value or element tag as a string.

The first argument is an XPath expression relative to the document root that selects exactly one element. The second argument is an attribute name string or None. In the latter case, the element tag (corresponding to the SKIRT property or class name) is returned. If the element is not found, there are multiple elements, or the selected element does not have the specified attribute, an error is raised.

◆ getStringAttributes()

def pts.simulation.skifile.SkiFile.getStringAttributes (   self,
  xpath,
  attribute 
)

This function returns a list including the string values of a particular attribute for a number of elements.

The first argument is an XPath expression relative to the document root that selects one or more elements. The second argument is the attribute name (the attribute must be present for all selected elements). If the attribute argument is None, the element tags (corresponding to SKIRT class names) are returned instead. If no elements are found, the function returns an empty list. If one or more of the selected element does not have the specified attribute, an error is raised.

◆ instrumentNames()

def pts.simulation.skifile.SkiFile.instrumentNames (   self)

This function returns the names of the instruments in the instrument system as a list of strings, in their order of appearance in the ski file.

◆ isOligo()

def pts.simulation.skifile.SkiFile.isOligo (   self)

This function returns True if the simulation mode is oligochromatic, False if it is panchromatic.

◆ numPrimaryPackets()

def pts.simulation.skifile.SkiFile.numPrimaryPackets (   self)

This function returns the number of photon packets launched per simulation segment for primary sources.

◆ probeNames()

def pts.simulation.skifile.SkiFile.probeNames (   self)

This function returns the names of the probes in the probe system as a list of strings, in their order of appearance in the ski file.

◆ saveTo()

def pts.simulation.skifile.SkiFile.saveTo (   self,
  saveFilePath 
)

This function saves the (possibly updated) contents of the SkiFile instance into the specified file.

The file path is interpreted as described for the pts.utils.absPath() function. The filename extension of the file must be ".ski" or ".xml". Saving to and thus replacing the ski file from which this SkiFile instance was originally constructed is allowed, but often not the intention.

◆ setBoolAttribute()

def pts.simulation.skifile.SkiFile.setBoolAttribute (   self,
  xpath,
  attribute,
  value 
)

This function sets an attribute value from a Boolean value.

The function arguments are the same as those for the setStringAttribute() function, except that the value argument is interpreted as a Python Boolean.

◆ setFloatAttribute()

def pts.simulation.skifile.SkiFile.setFloatAttribute (   self,
  xpath,
  attribute,
  value 
)

This function sets an attribute value representing a dimensionless quantity from a floating point number.

The function arguments are the same as those for the setStringAttribute() function, except that the value argument must be convertible to float.

◆ setIntAttribute()

def pts.simulation.skifile.SkiFile.setIntAttribute (   self,
  xpath,
  attribute,
  value 
)

This function sets an attribute value from an integer number.

The function arguments are the same as those for the setStringAttribute() function, except that the value argument must be convertible to int.

◆ setNumPrimaryPackets()

def pts.simulation.skifile.SkiFile.setNumPrimaryPackets (   self,
  value 
)

This function sets the number of photon packets launched per simulation segment for primary sources.

◆ setQuantityAttribute()

def pts.simulation.skifile.SkiFile.setQuantityAttribute (   self,
  xpath,
  attribute,
  value,
  skirtUnit = None 
)

This function sets an attribute value representing a physical quantity with given units.

The function arguments are the same as those for the setStringAttribute() function, except that the value argument must be an astropy scalar quantity with appropriate units, and that a skirt unit string can be specified (i.e. the units to be used in the ski file). If the skirtUnit argument is omitted, the skirt unit string is taken from the current attribute value. Thus, in this case, the attribute must already be present and include a unit string. In any case, the specified quantity is converted to the units used in the ski file before being written to the ski file.

◆ setStringAttribute()

def pts.simulation.skifile.SkiFile.setStringAttribute (   self,
  xpath,
  attribute,
  value 
)

This function sets an attribute value from a string.

The first argument is an XPath expression relative to the document root that selects exactly one element. The second argument is the attribute name. The third argument is the string value. If the element did not have an attribute with the specified name, it is added. If the element is not found or there are multiple elements, an error is raised.

◆ skiFilePath()

def pts.simulation.skifile.SkiFile.skiFilePath (   self)

This function returns the absolute file path of the ski file represented by this SkiFile instance.

◆ transformIf()

def pts.simulation.skifile.SkiFile.transformIf (   self,
  condition,
  templates 
)

This function applies an XSLT transform to the ski file if an XPath condition evaluates to true.

The first argument is a string specifying an XPath 1.0 expression to be evaluated in the context of the XML document representing the ski file; the expression value is converted to boolean according to XPath semantics. If the value is true, the XSLT 1.0 transform specified in the second argument is applied to the XML document, and the result replaces the original document. The second argument is a string containing one or more <xsl:template> elements that specify the changes to be applied to the document. The <xsl:stylesheet> element and the identity template are automatically added and must not be contained in the argument string. The function returns true if the transform was applied, and false if it was not (i.e. the document is unchanged).


The documentation for this class was generated from the following file: