Skip to content

Repository Overview

.github

This directory contains Github specific information.

workflows

The workflows folder contains all the Github Actions scripts.

  • docs.yml: Publish the contents of /docs to https://xfds.pbd.tools
  • release.yml: When a new release is initiated, this will run the tests one more time and then publish the new version to PyPI
  • test.yml: Runs continuious integration tests.
    • Ensures all tests are passing
    • Determines how much of the code is covered by the tests
    • Checks that all the code is formatted using black
    • Lints the codebase for best practices and catching errors with flake8
    • Checks for security vulnerabilities with Safety
    • Checks that all functions are correctly annotated with mypy

.vscode

The .vscode folder contains configuration for using the VS Code editor. You do not need to use VS Code, but this project is set up assuming you are.

  • extensions.json: Recommended extensions from the VS Code Marketplace
  • settings.json: Configuration options.

docs

Code for the documentation hosted at https://xfds.pbd.tools.

Documentation is built on mkdocs and uses the Material Theme. You can include snippets from other files thanks to mdx_include.

examples

The examples directory show ways that xFDS can be used. Most of the examples are used in the documentation. Thanks to mdx-include, the code below includes /examples/variables/variables.fds. The documentation is configured to look in the examples directory when looking for files to include.

mdx_include syntax
{! hrrpua/hrrpua.fds !}
included file
{% set hrr = 1000 -%}
{% set area = 1.5 -%}
{% set depth = 0.2 -%}

&MESH XB=-2, 2, -2, 2, 0, 4, IJK=40, 40, 40/
&TIME T_END=30/
&REAC FUEL='PROPANE'/

{% set top = 0.2 %}
{% set side = area ** 0.5 %}
{% set r = (-side / 2)|round(4) %}
&SURF ID='BURNER', COLOR='RED', HRRPUA={{ (hrr / area)|round(2) }}/
&OBST XB={{ (-r, r, -r, r, top - depth, top)|xb }}/
&VENT XB={{ (-r, r, -r, r, top, top)|xb }}, SURF_ID='BURNER'/

src/xfds

This directory contains all the source code for the project.

Common Files

Thse files are files necesary to setup xFDS and pull the pieces together.

  • __init__.py: Generally empty except for the software version number.
  • cli.py: This file is the main entry point for the command line interface.
  • config.py: Default settings for commands.
  • core.py: Basic functions required by multiple commands.
  • errors.py: Custom error types to make tracebacks more helpful.
  • filters.py: Custom Jinja filters useful for creating models.
  • log.py: Functions for printing information out to the terminal.
  • units.py: Module for defining custom units and managing unit conversion.

Command Specific Files

Files that start with an underscore (_) contain the logic for all the xFDS subcommands.

Tests

xFDS uses pytest to ensure things are working as expected.

  • data: Example data for tests
  • integration: Tests for ensuring xFDS works together as a whole.
  • unit: Tests for individual pieces of code.
  • conftest.py: Fixtures used across the test suite.

Project Configuration Files

  • .flake8: configuration for linting
  • .gitignore : Tell Git which files to ignore.
  • .pre-commit-config.yaml: Checks to perform before committing code.
  • docker-compose.yml: Spins up docker container to develop these docs. Mkdocs will crash sometimes when editing mkdocs.yml, so Docker will restart the server automatically.
  • justfile: Common tasks for developing xFDS.
  • LICENSE: Defines permissions for xFDS.
  • mkdocs.yml: Configuration for documentation.
  • mypy.ini: Configuration for static type checking.
  • noxfile.py: Rules for testing xFDS on multiple versions of Python. These are checked with every push to the repo.
  • poetry.lock: Pre-computed information for what packages xFDS needs.
  • pyproject.toml: xFDS Pacakge configuration and metadata.
  • README.md: High level info for the project.