Functions
	load_module (str name, Path path)
	Load a repository script as an importable module.

	schema_leaves (dict schema)
	Yield every key path a schema accepts that is not itself a nested mapping.

list	uncovered_inputs (core)
	Name every solver-facing input with no recorded physical dimension.

str	dimension_name (core, dimension)
	Name a dimension triple by its constant in the conductor core.

dict	physical_inputs (core)
	Every input that carries a physical dimension, as the input index lists it.

dict	compiled_field_dimensions ()
	Field name to `(catalog, FIELD_DIM_* suffix)` for every compiled entry.

str	page_section (str heading)
	One `@section` body of page 19.

dict	documented_rows (str heading)
	Rows of the first table in a section: first column to second and third.

int	main ()
	Fail when an input lacks a dimension or an index disagrees with the code.

Variables
	REPO_ROOT = Path(__file__).resolve().parents[2]

str	CORE = REPO_ROOT / "picurv_cli" / "core.py"

str	IC_GENERATOR = REPO_ROOT / "generators" / "ic.gen"

str	EULERIAN_CATALOG = REPO_ROOT / "src" / "field_catalog.c"

str	PARTICLE_CATALOG = REPO_ROOT / "src" / "particle_field_catalog.c"

str	PAGE = REPO_ROOT / "docs" / "pages" / "19_Nondimensionalization.md"

dict	SOLVER_INPUT_SCHEMAS

dict	DEDICATED_TABLE_SURFACES

dict	BUILTIN_IC_GENERATORS = {"zero", "constant", "streamwise_constant", "poiseuille"}

	ENTRY_RE = re.compile(r"\b(?:FIELD_ENTRY\|FIELD_COORDINATE_ENTRY\|PARTICLE_FIELD_ENTRY)\‍(")

	DIMENSION_RE = re.compile(r"FIELD_DIM_(\w+)")

	NAME_RE = re.compile(r'"([^"]+)"')

	INDEX_ROW_RE = re.compile(r"^\\|\s`([^`]+)`\s\\|\s(\w+)\s\\|\s`?(\w+)`?\s\\|", re.M)

Function Documentation

◆ load_module()

audit_units.load_module	(	str	name,
		Path	path
	)

Load a repository script as an importable module.

Parameters

[in]	name	Module name to register.
[in]	path	Source path of the script.

Returns: Loaded module object.

Definition at line 58 of file audit_units.py.

def load_module(name: str, path: Path):
    """!
    @brief Load a repository script as an importable module.
    @param[in] name Module name to register.
    @param[in] path Source path of the script.
    @return Loaded module object.
    """
    loader = importlib.machinery.SourceFileLoader(name, str(path))
    spec = importlib.util.spec_from_loader(name, loader)
    module = importlib.util.module_from_spec(spec)
    loader.exec_module(module)
    return module
 
 

Here is the caller graph for this function:

◆ schema_leaves()

audit_units.schema_leaves ( dict schema )

Yield every key path a schema accepts that is not itself a nested mapping.

A path mapped to None accepts arbitrary keys and is yielded as a leaf: its contents are covered as a whole or by a dedicated table. A list's children are keyed under path + ("[]",), so any path prefixing an entry is interior.

Parameters

[in] schema Key schema mapping parent paths to allowed key sets.

Returns: Generator of key-path tuples.

Definition at line 72 of file audit_units.py.

def schema_leaves(schema: dict):
    """!
    @brief Yield every key path a schema accepts that is not itself a nested mapping.
    @details A path mapped to `None` accepts arbitrary keys and is yielded as a leaf: its
             contents are covered as a whole or by a dedicated table. A list's children
             are keyed under `path + ("[]",)`, so any path prefixing an entry is interior.
    @param[in] schema Key schema mapping parent paths to allowed key sets.
    @return Generator of key-path tuples.
    """
    interiors = {
        parent[:length]
        for parent, keys in schema.items() if keys is not None
        for length in range(1, len(parent) + 1)
    }
    for parent, keys in schema.items():
        for key in keys or ():
            path = parent + (key,)
            if path not in interiors:
                yield path
 
 

Here is the caller graph for this function:

◆ uncovered_inputs()

list audit_units.uncovered_inputs ( core )

Name every solver-facing input with no recorded physical dimension.

Parameters

[in] core Loaded conductor core.

Returns: Dotted names of uncovered inputs; empty when complete.

Definition at line 93 of file audit_units.py.

def uncovered_inputs(core) -> list:
    """!
    @brief Name every solver-facing input with no recorded physical dimension.
    @param[in] core Loaded conductor core.
    @return Dotted names of uncovered inputs; empty when complete.
    """
    problems = []
    for role, schema_name in SOLVER_INPUT_SCHEMAS.items():
        for path in schema_leaves(getattr(core, schema_name)):
            full = (role,) + path
            if full in DEDICATED_TABLE_SURFACES:
                continue
            try:
                core.input_quantity(full)
            except KeyError:
                problems.append(".".join(full))
 
    accepted = set(core._DEPRECATED_BC_PARAM_ALIASES)
    for spec in core.BC_HANDLER_SPECS.values():
        accepted |= spec["required_params"] | spec["optional_params"]
    problems.extend(f"boundary_conditions[].params.{key}"
                    for key in sorted(accepted - set(core.BC_PARAM_QUANTITIES)))
 
    generators = BUILTIN_IC_GENERATORS | core._PYTHON_INITIAL_CONDITION_PROVIDERS
    problems.extend(f"initial_conditions.generator {name}"
                    for name in sorted(generators ^ set(core.IC_PARAM_QUANTITIES)))
    ic_gen = load_module("audit_units_ic_gen", IC_GENERATOR)
    provider_params = {
        "spectral_random_velocity": core.SPECTRAL_RANDOM_VELOCITY_PARAMS,
        "channel_spectral_velocity": ic_gen.WALL_SPECTRAL_PARAMS,
        "duct_spectral_velocity": ic_gen.WALL_SPECTRAL_PARAMS,
    }
    for generator, keys in provider_params.items():
        roots = {name.split(".", 1)[0] for name in core.IC_PARAM_QUANTITIES.get(generator, {})}
        problems.extend(f"initial_conditions.params.{key} ({generator})" for key in sorted(set(keys) - roots))
    return problems
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

◆ dimension_name()

str audit_units.dimension_name	(	core,
		dimension
	)

Name a dimension triple by its constant in the conductor core.

Parameters

[in]	core	Loaded conductor core.
[in]	dimension	`(length, velocity, density)` exponents.

Returns: Constant name, e.g. VELOCITY.

Definition at line 131 of file audit_units.py.

def dimension_name(core, dimension) -> str:
    """!
    @brief Name a dimension triple by its constant in the conductor core.
    @param[in] core Loaded conductor core.
    @param[in] dimension `(length, velocity, density)` exponents.
    @return Constant name, e.g. `VELOCITY`.
    """
    for name in ("DIMENSIONLESS", "LENGTH", "VELOCITY", "TIME", "WAVENUMBER", "VOLUME_FLUX",
                 "DIFFUSIVITY", "PRESSURE", "DENSITY", "DYNAMIC_VISCOSITY"):
        if getattr(core, name) == dimension:
            return name
    raise ValueError(f"dimension {dimension} has no named constant")
 
 

Here is the caller graph for this function:

◆ physical_inputs()

dict audit_units.physical_inputs ( core )

Every input that carries a physical dimension, as the input index lists it.

Dimensionless and non-quantity inputs are omitted: there is nothing to convert. Payload inputs whose dimension follows their content are listed with dimension PAYLOAD.

Parameters

[in] core Loaded conductor core.

Returns: Mapping of documented input name to (dimension name, conversion site).

Definition at line 145 of file audit_units.py.

def physical_inputs(core) -> dict:
    """!
    @brief Every input that carries a physical dimension, as the input index lists it.
    @details Dimensionless and non-quantity inputs are omitted: there is nothing to
             convert. Payload inputs whose dimension follows their content are listed
             with dimension `PAYLOAD`.
    @param[in] core Loaded conductor core.
    @return Mapping of documented input name to `(dimension name, conversion site)`.
    """
    rows = {}
 
    def record(name, quantity):
        """!
        @brief Add one input to the index when it carries something to convert.
        @param[in] name Documented input name.
        @param[in] quantity `(dimension, site)` entry.
        """
        dimension, site = quantity
        if site in ("", "passthrough"):
            return
        if dimension is not None and dimension == core.DIMENSIONLESS:
            return
        rows[name] = ("PAYLOAD" if dimension is None else dimension_name(core, dimension), site)
 
    for path, quantity in core.INPUT_QUANTITIES.items():
        record(f"{path[0]}.yml: " + ".".join(path[1:]), quantity)
    for key, quantity in core.BC_PARAM_QUANTITIES.items():
        record(f"case.yml: boundary_conditions[].params.{key}", quantity)
    for generator, table in core.IC_PARAM_QUANTITIES.items():
        for key, quantity in table.items():
            record(f"case.yml: initial_conditions.params.{key} ({generator})", quantity)
    return rows
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

◆ compiled_field_dimensions()

dict audit_units.compiled_field_dimensions ( )

Field name to (catalog, FIELD_DIM_* suffix) for every compiled entry.

Returns: Mapping of canonical field names to their catalog and dimension.

Exceptions

ValueError when an entry carries no dimension argument.

Definition at line 179 of file audit_units.py.

def compiled_field_dimensions() -> dict:
    """!
    @brief Field name to `(catalog, FIELD_DIM_* suffix)` for every compiled entry.
    @return Mapping of canonical field names to their catalog and dimension.
    @throws ValueError when an entry carries no dimension argument.
    """
    fields = {}
    for catalog, path in (("Eulerian", EULERIAN_CATALOG), ("particle", PARTICLE_CATALOG)):
        text = path.read_text(encoding="utf-8")
        body = text[text.index("gFieldCatalog" if catalog == "Eulerian" else "gParticleFieldCatalog"):]
        for match in ENTRY_RE.finditer(body):
            depth, index = 1, match.end()
            while depth:
                depth += {"(": 1, ")": -1}.get(body[index], 0)
                index += 1
            entry = body[match.end():index - 1]
            name = NAME_RE.search(entry).group(1)
            dimension = DIMENSION_RE.search(entry)
            if dimension is None:
                raise ValueError(f"{catalog} field '{name}' has no FIELD_DIM_* argument")
            fields[(catalog, name)] = dimension.group(1)
    return fields
 
 

Here is the caller graph for this function:

◆ page_section()

str audit_units.page_section ( str heading )

One @section body of page 19.

Parameters

[in] heading Section anchor to extract.

Returns: Section text up to the next section.

Definition at line 203 of file audit_units.py.

def page_section(heading: str) -> str:
    """!
    @brief One `@section` body of page 19.
    @param[in] heading Section anchor to extract.
    @return Section text up to the next section.
    """
    text = PAGE.read_text(encoding="utf-8")
    start = text.index(f"@section {heading}")
    following = text.find("@section", start + 1)
    return text[start: following if following != -1 else len(text)]
 
 

Here is the caller graph for this function:

◆ documented_rows()

dict audit_units.documented_rows ( str heading )

Rows of the first table in a section: first column to second and third.

Parameters

[in] heading Section anchor.

Returns: Mapping of backticked first-column text to the next two cells.

Definition at line 215 of file audit_units.py.

def documented_rows(heading: str) -> dict:
    """!
    @brief Rows of the first table in a section: first column to second and third.
    @param[in] heading Section anchor.
    @return Mapping of backticked first-column text to the next two cells.
    """
    return {(first, second): third
            for first, second, third in INDEX_ROW_RE.findall(page_section(heading))}
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

◆ main()

int audit_units.main ( )

Fail when an input lacks a dimension or an index disagrees with the code.

Returns: Process status code.

Definition at line 225 of file audit_units.py.

def main() -> int:
    """!
    @brief Fail when an input lacks a dimension or an index disagrees with the code.
    @return Process status code.
    """
    core = load_module("audit_units_core", CORE)
    problems = [f"no recorded dimension: {name}" for name in uncovered_inputs(core)]
 
    inputs = physical_inputs(core)
    documented_inputs = {name: (dimension, site)
                         for (name, dimension), site in documented_rows("p19_inputs_sec").items()}
    for name in sorted(set(inputs) - set(documented_inputs)):
        problems.append(f"input index: '{name}' is physical but not listed")
    for name in sorted(set(documented_inputs) - set(inputs)):
        problems.append(f"input index: '{name}' is listed but records nothing to convert")
    for name in sorted(set(inputs) & set(documented_inputs)):
        if inputs[name] != documented_inputs[name]:
            problems.append(f"input index: '{name}' records {inputs[name]}, page says {documented_inputs[name]}")
 
    fields = compiled_field_dimensions()
    documented_fields = {(catalog, name): dimension
                         for (name, catalog), dimension in documented_rows("p19_fields_sec").items()}
    for key in sorted(set(fields) - set(documented_fields)):
        problems.append(f"field index: {key[0]} field '{key[1]}' is not listed")
    for key in sorted(set(documented_fields) - set(fields)):
        problems.append(f"field index: {key[0]} field '{key[1]}' is not in the compiled catalog")
    for key in sorted(set(fields) & set(documented_fields)):
        if fields[key] != documented_fields[key]:
            problems.append(f"field index: {key[1]} is FIELD_DIM_{fields[key]}, page says {documented_fields[key]}")
 
    if problems:
        print("Units rule or its published indexes do not match the code:", file=sys.stderr)
        for problem in problems:
            print(f"  {problem}", file=sys.stderr)
        print("\nRecord a new input in picurv_cli/core.py INPUT_QUANTITIES (or BC_PARAM_QUANTITIES /\n"
              "IC_PARAM_QUANTITIES), give a new field a FIELD_DIM_* argument, and update the\n"
              "indexes in docs/pages/19_Nondimensionalization.md.", file=sys.stderr)
        return 1
    print(f"Units audit passed: every solver-facing input records a dimension; {len(inputs)} "
          f"physical inputs and {len(fields)} catalogued fields match page 19. Whether each "
          "conversion is performed is checked by the ingress tests and smoke run, not here.")
    return 0
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

Variable Documentation

◆ REPO_ROOT

audit_units.REPO_ROOT = Path(__file__).resolve().parents[2]

Definition at line 26 of file audit_units.py.

◆ CORE

str audit_units.CORE = REPO_ROOT / "picurv_cli" / "core.py"

Definition at line 27 of file audit_units.py.

◆ IC_GENERATOR

str audit_units.IC_GENERATOR = REPO_ROOT / "generators" / "ic.gen"

Definition at line 28 of file audit_units.py.

◆ EULERIAN_CATALOG

str audit_units.EULERIAN_CATALOG = REPO_ROOT / "src" / "field_catalog.c"

Definition at line 29 of file audit_units.py.

◆ PARTICLE_CATALOG

str audit_units.PARTICLE_CATALOG = REPO_ROOT / "src" / "particle_field_catalog.c"

Definition at line 30 of file audit_units.py.

◆ PAGE

str audit_units.PAGE = REPO_ROOT / "docs" / "pages" / "19_Nondimensionalization.md"

Definition at line 31 of file audit_units.py.

◆ SOLVER_INPUT_SCHEMAS

dict audit_units.SOLVER_INPUT_SCHEMAS

Initial value:

=  {
    "case": "_CASE_SCHEMA",
    "solver": "_SOLVER_SCHEMA",
    "monitor": "_MONITOR_SCHEMA",
    "post": "_POST_SCHEMA",
}

Definition at line 35 of file audit_units.py.

◆ DEDICATED_TABLE_SURFACES

dict audit_units.DEDICATED_TABLE_SURFACES

Initial value:

=  {
    ("case", "boundary_conditions", "[]", "params"),
    ("case", "boundary_conditions", "[]", "[]", "params"),
    ("case", "properties", "initial_conditions", "params"),
}

Definition at line 43 of file audit_units.py.

◆ BUILTIN_IC_GENERATORS

dict audit_units.BUILTIN_IC_GENERATORS = {"zero", "constant", "streamwise_constant", "poiseuille"}

Definition at line 50 of file audit_units.py.

◆ ENTRY_RE

audit_units.ENTRY_RE = re.compile(r"\b(?:FIELD_ENTRY|FIELD_COORDINATE_ENTRY|PARTICLE_FIELD_ENTRY)\‍(")

Definition at line 52 of file audit_units.py.

◆ DIMENSION_RE

audit_units.DIMENSION_RE = re.compile(r"FIELD_DIM_(\w+)")

Definition at line 53 of file audit_units.py.

◆ NAME_RE

audit_units.NAME_RE = re.compile(r'"([^"]+)"')

Definition at line 54 of file audit_units.py.

◆ INDEX_ROW_RE

audit_units.INDEX_ROW_RE = re.compile(r"^\|\s*`([^`]+)`\s*\|\s*(\w+)\s*\|\s*`?(\w+)`?\s*\|", re.M)

Definition at line 55 of file audit_units.py.

Functions

Variables

Function Documentation

◆ load_module()

◆ schema_leaves()

◆ uncovered_inputs()

◆ dimension_name()

◆ physical_inputs()

◆ compiled_field_dimensions()

◆ page_section()

◆ documented_rows()

◆ main()

Variable Documentation

◆ REPO_ROOT

◆ CORE

◆ IC_GENERATOR

◆ EULERIAN_CATALOG

◆ PARTICLE_CATALOG

◆ PAGE

◆ SOLVER_INPUT_SCHEMAS

◆ DEDICATED_TABLE_SURFACES

◆ BUILTIN_IC_GENERATORS

◆ ENTRY_RE

◆ DIMENSION_RE

◆ NAME_RE

◆ INDEX_ROW_RE