Fix parsing of string-based dimensions in OpenFOAM files (closes #332)

[Copilot]

Adds support for parsing string-based dimension units like [ Pa ] in OpenFOAM files, fixing the parsing exception that occurred when loading files containing fvExpressionField functionObjects.

Problem

The parser previously only supported numeric dimension sets like [1 -1 -2 0 0 0 0] but failed when encountering string-based units:

from foamlib import FoamFile

# This worked fine
FoamFile.loads("[1 -1 -2 0 0 0 0]")  # ✓ Returns DimensionSet

# This caused a ParseException
FoamFile.loads("[ Pa ]")  # ✗ ParseException: Expected ']', found 'Pa'

This prevented parsing of OpenFOAM controlDict files containing fvExpressionField functions:

functions
{
    test
    {
        type        exprField;
        libs        (fieldFunctionObjects);
        field       pTotal;
        expression  "p + 0.5*(rho*magSqr(U))";
        dimensions  [ Pa ];  // This line caused the parsing to fail
    }
}

Solution

Extended the _DIMENSIONS parser to handle both numeric and string-based dimensions:

• Numeric dimensions: [1 -1 -2 0 0 0 0] → Returns DimensionSet (unchanged)
• String dimensions: [ Pa ] → Returns "Pa" as requested by the user
• Complex units: [Pa mm^2 s^-2] → Returns "Pa mm^2 s^-2"

Added a new StringDimensionSet class to properly handle string-based dimensions in Dimensioned objects while maintaining backward compatibility.

Changes

• Parser: Extended _DIMENSIONS to accept both numeric and string-based units
• Types: Added StringDimensionSet class and updated Dimensioned constructor
• Tests: Added comprehensive test coverage for the new functionality
• API: Made StringDimensionSet available in the FoamFile namespace

Examples

from foamlib import FoamFile

# String dimensions now work
assert FoamFile.loads("[ Pa ]") == "Pa"
assert FoamFile.loads("[kg m s^-2]") == "kg m s^-2"

# Numeric dimensions still work as before
dim = FoamFile.loads("[1 -1 -2 0 0 0 0]")
assert dim == FoamFile.DimensionSet(mass=1, length=-1, time=-2)

# Complex controlDict files now parse successfully
controlDict = '''
functions
{
    pressureField
    {
        type        exprField;
        dimensions  [ Pa ];
        expression  "p + 101325";
    }
}
'''
result = FoamFile.loads(controlDict)
assert result["functions"]["pressureField"]["dimensions"] == "Pa"

The fix maintains full backward compatibility while enabling foamlib to handle the broader range of OpenFOAM files that use string-based dimension specifications.

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.