Python Resources

Pygacity exposes several objects (packages, classes, etc) that can be accessed by using a pythontex block in the document structure specified in your configuration file. All begin{pycode}…end{pycode} blocks will have access to these objects.

Default pythontex resources: setup and teardown

setup

The following objects are available if the document structure includes a pythontex block that imports the setup package resource. For example, to import these objects, include the following block in the document structure:

- pythontex:
  - setup

Packages:

  • yaml

  • random

  • logging

  • pickle

  • os

  • numpy as np

  • fractions as fr

Classes:

  • Namespace from argparse

  • Path from pathlib

  • AnswerSet from pygacity.generate.answerset

  • Picker from pygacity.generate.pick

  • FileCollector from pygacity.util.collectors

Modules:

  • pygacity.util.texutils as tu

Objects:

  • serial: the unique serial number for the current document copy being built (an integer)

  • serialstr: the formatted string representation of serial — a plain decimal string by default, or a zero-padded lowercase hexadecimal string when build.serial-hex is true (width controlled by build.serial-hex-digits). This is the same string used in output filenames.

  • serials: a list of all serial integers for the current build run, in the order they were generated. Useful for generating content that references or summarises all exam versions.

  • serialstrs: a list of the formatted string representations of all serials (same formatting rules as serialstr), in the same order as serials.

  • rng: the random number generator instance seeded using the document serial number. (The seed value from the configuration file is only used to generate the list of serial numbers; each document copy gets its own RNG seeded by its serial number.)

  • Pick: an instance of the Picker class that can be used to make random selections in a reproducible way across multiple document copies.

  • AnsSet: an instance of the AnswerSet class that can be used to store and retrieve answers generated during the build process.

  • logger: a logger instance that can be used to log messages during the build process; a user can include logger calls in their own begin{pycode}…end{pycode} code blocks to log messages to the build log. The name of the log file is by default pygacity_diagnostics.log and is located current working directory (not the build directory).

  • pythontexFC: an instance of the FileCollector class that can be used to collect files during the build process generated by user-defined pythontex blocks.

teardown

Several default actions are performed if the document structure includes a pythontex block that imports the teardown package resource. For example, to import these objects, include the following block in the document structure:

- pythontex:
  - teardown

Actions performed by the teardown resource include:

  1. removing the temporary matplotlib configuration directory (_mplconfig) created during the build process if the matplotlib resource was used.

  2. saving the AnsSet object to a pickle file in the build cache directory so that pygacity can read it when building the combined answer set document containing all answers for all document copies.

  3. saving any files collected using the pythontexFC object to a compressed archive file in the build directory for easy access after the build process is complete. Only files declared using the pythontexFC.append() method called within any \begin{pycode}...\end{pycode} blocks are saved here.

Typically, the teardown resource is included at the end of the document structure to ensure that all other pythontex code has been executed before these actions are performed.

Custom resources

matplotlib resource

In addition to the default objects described above, users can also import additional package resources by specifying them in a pythontex block in the document structure. For example, to import the matplotlib resource, include the following block in the document structure:

- pythontex:
  - matplotlib

This will import the matplotlib package and the pyplot module as usual:

import matplotlib
import matplotlib.pyplot as plt

The resource file also does some behind-the-scenes setup to ensure that matplotlib works correctly within the pythontex environment used by pygacity, primarily due to font path issues. It generates a _mplconfig directory in the build directory that contains a custom matplotlib configuration file used during the build process. It also sets the matplotlib backend to Agg to ensure compatibility with headless environments.

sandler resource

In addition to the default objects described above, users can also import the sandler package resource by specifying it in a pythontex block in the document structure. This resource wires in the sandlertools package, which provides a suite of utilities for generating problems and solutions based on Sandler’s Chemical, Biochemical, and Engineering Thermodynamics textbook.

- pythontex:
  - sandler

This imports the following objects for use in subsequent pycode blocks:

Classes:

  • PropertiesDatabase: A class for accessing thermodynamic property data.

  • SandlerSteamState as SANDLER: A class for representing the state of steam using the steam tables provided in Appendix III of the textbook.

  • SteamRequest: A class for specifying requests to generate blocks of steam table for explicit inclusion in documents.

  • Component, Reaction, and ChemEqSystem: Classes for representing chemical components, reactions, and chemical equilibrium systems, respectively.

  • CorrespondingStatesChartReader: A class for reading and interpreting corresponding states charts from the textbook.

  • GasConstant: A class for representing gas constant in various units.

  • IdealGasEOS, GeneralizedVDWEOS, and PengRobinsonEOS: Classes for representing various equations of state for gases and fluids.

Objects:

  • SteamTables: The full steam tables data from Appendix III of the textbook.

  • R_pv: the gas constant in units of bar-m3/(mol-K)

  • R: the gas constant in units of J/(mol-K)

  • CSReader: an instance of the CorrespondingStatesChartReader class for reading corresponding states charts.

  • STReq: an instance of the SteamRequest class for generating steam table blocks.

  • suphPavail: a list of pressures (in MPa) at which superheated steam table blocks are available in the textbook.

  • SandlerProps: an instance of the PropertiesDatabase class for accessing thermodynamic property data.

showsteamtables resource

In addition to the default objects described above, users can also import the showsteamtables package resource by specifying it in a pythontex block in the document structure. This resource wires in the showsteamtables package, which provides utilities for displaying steam tables in LaTeX documents.

- pythontex:
  - showsteamtables

This accesses teh STReq object and calls its .to_latex() method to generate LaTeX code for displaying steam tables in the document. Like teardown, it is typically included at the end of the document structure to ensure that all steam table requests have been processed and included in the document.