Logging
PINSPEC provides a set of utility functions to print level-based log messages to the screen, as well as an output log file generated from each simulation. Using this logging capability is highly recommended, as it gives code output readability and keeps track of previous runs via a log file created as part of the output.
There are different levels of log messages, each with a particular tag:
- Level 0: DEBUG
- Level 1: INFO
- Level 2: NORMAL
- Level 3: SEPARATOR
- Level 4: HEADER
- Level 5: TITLE
- Level 6: WARNING
- Level 7: CRITICAL
- Level 8: RESULT
- Level 9: UNITTEST
- Level 10: ERROR
To print out information about the progression of the code to the screen, one might use the 'INFO' keyword. To format the logging level, or a section in the screen printout, the keywords 'NORMAL', 'SEPARATOR', 'HEADER', 'TITLE' can be used. An example of output format is shown below for messages with several tags:
!
##Setting the Log Level In order to view log messages, the log level should be set near the beginning of the file, using the constructor 'py_setlevel()'. The argument of py_setlevel is the keyword for the level, given above, surrounded by single quotes. Selecting a specific level ensures that any logging message tagged with that keyword will be printed along with any other messages with a higher logging level. For example, the following command,
py_setlevel('CRITICAL')
would cause all messages tagged with the keywords CRITICAL, RESULT, and ERROR to be printed to the screen and the log file.
##Creating Logging Messages Log messages can be created with the 'py_printf()' constructor. The first argument is the keyword that associates the level with the message, surrounded by single quotes. The second argument is the message, surrounded by single quotes:
py_printf('INFO', 'This is where I'd put my information')
Throughout the tutorial, examples will be shown including logging messages in order to encourage good record-keeping.
##Output Log File As mentioned earlier, after PINSPEC is run, a folder is created within the output folder titled 'log'. This folder contains a log file for each run, allowing users to examine different runs.