Fortran code generation

Fortran code generation for thermodynamic models.

This module turns a DiffPlz instance into a free-form Fortran subroutine that evaluates the original function together with all its available derivatives.

The generated subroutine takes the independent variables (mole numbers n, volume V, pressure P, temperature T), the model parameters, and returns the function value and the derivatives as intent (out) arguments, for example:

subroutine f(n, V, T, f, dfdT, dfdV, dfdn)
  implicit none
  integer, intent(in) :: nc
  real(8), intent(in) :: n(:)
  real(8), intent(in) :: V, T
  real(8), intent(out) :: f, dfdT, dfdV
  real(8), intent(out) :: dfdn(:)
  ...
end subroutine

Summations produced with sum_components() are expanded into explicit do loops and the Kronecker deltas handled by DiffPlz become if/else blocks. Internal functions created with idx_function() (and their derivatives) are exposed as extra input arguments by default; pass strict=True to raise an error instead.

to_fortran(diff: Any, derivatives: Any = None, name: str | None = None, subroutine_name: str | None = None, *, integer_args: Iterable[str] | None = None, module_symbols: Iterable[str] | None = None, symmetric_params: Iterable[str] | None = (), stats: dict[str, Any] | None = None, options: CodegenOptions | None = None, strict: bool = False, optional_derivatives: bool = False, array_cse: bool = True, share: bool = True, share_sums: bool | None = None, scalar_cse: bool | None = None, param_symmetry: bool = False, hessian_symmetry: bool = False, cse_backend: CseBackend | str = 'thermodiff', sum_alpha: bool = False, array_pad: int = 0, hoist_invariants: bool = False, chain_rule: bool = False, hoist_loops: bool = False, sum_free_alpha: bool = False, fuse_temps: bool = False, nest_sums: bool = False, split_sqrt: bool = False, split_sums: bool = False, nest_shared: bool = False, sym_matvec: bool = False, col_major: bool = False, pair_cse: bool = False, pair_rates: bool = False, sum_transpose: bool = False, sep_sums: SepSumsMode | bool | str = False, sym_rank3: bool = False, nest_general: bool = False, sym_sum2: bool = False, cse_expensive: bool = False, fuse_loops: bool = False, nested_nodes: bool = False, sym_perm: bool = False, fuse_guard: bool = False, nest_cost: bool = False, comp_fuse: bool = False, fuse_outer: bool = False, fuse_libm_guard: bool = False, keep_libm_tables: bool = False, diag_table: bool = False, sib_fuse: bool = False, dummy_canon: bool = False, float_canon: bool = False, contiguous_args: bool = False, table_layout: bool = False, lowrank_hess: LowrankHessMode | bool | str = False, drop_pair_tables: bool = False, share_elementwise: bool = False, scalar_chain: ScalarChainMode | bool | str = False, split_affine: bool = False, split_acc: int | bool = False) → str[source]

Generate a Fortran subroutine for a DiffPlz instance.

The behaviour options can be given as a CodegenOptions (options), as the legacy keywords documented below, or both. The resolved options are validated on every call: options that the generator would silently ignore for the chosen combination are disabled and reported in one UserWarning (see CodegenOptions.validate()). For ready-made option sets use CodegenOptions.from_preset("standard").

Parameters:
  • diff (DiffPlz) – The differentiated thermodynamic expression.

  • derivatives (str or list of str, optional) – Derivatives to emit, for example ["dT", "dV", "dn"]. Both the friendly names and the derivative attributes (["dt", "dv", "dni"]) are accepted, as well as the groups all, none, first and second (see thermodiff.derivatives.resolve_derivatives()). By default every non-zero derivative computed by diff is emitted.

  • name (str, optional) – Base name used for the generated variables. Defaults to the name attribute of diff.

  • subroutine_name (str, optional) – Name of the generated subroutine. Defaults to the base name.

  • strict (bool, optional) – When True, raise a ValueError if the expression contains internal functions or unresolved derivatives instead of exposing them as input arguments. By default False.

  • integer_args (list of str, optional) – Names of extra arguments that must be declared as integer, intent(in) (for example, extra dimensions).

  • module_symbols (list of str, optional) – Names that are provided by a use statement of the enclosing module. They are neither declared as arguments nor included in the subroutine signature.

  • optional_derivatives (bool, optional) – When True, every output - the function value included - is declared as a Fortran optional argument and computed only when the caller passes it. A shared temporary is skipped whenever none of the outputs that need it is present, so calling the subroutine with a subset of the outputs also skips the work.

  • array_cse (bool, optional) – When True (the default), index-dependent sub-expressions that several outputs share are materialised into array temporaries computed a single time (see _indexed_cse()). Only sub-expressions of rank up to two are materialised, because a larger temporary costs more than it saves. Disable the pass to obtain the plain, fully inlined expressions.

  • share (bool, optional) – When True (the default), summations and common scalar sub-expressions shared by several outputs are computed a single time as internal temporaries (_share_sums() and _common_scalar_cse()). Set it to False to disable both sharing passes: every output is then emitted from its own fully inlined expressions and repeated summations are re-evaluated per output. The benchmark variant “V1 none” is array_cse=False, share=False; “V2 partial” is array_cse=False; “V3 full” is array_cse=True. The flag only changes the generated body: the signature, the declaration block and the output order are identical for every setting.

  • stats (dict, optional) – When given, it is filled in place with generation statistics: operation_count (sympy.count_ops summed over the final output expressions and over the body of every shared temporary), operation_count_tool (the exact tool/options used) and n_temporaries (number of shared temporaries emitted). The count is a symbolic-operation count of the final expressions, not a runtime estimate.

  • share_sums (bool, optional) – Fine-grained control of the two passes enabled by share: _share_sums() and the scalar common sub-expression pass. None (the default) inherits the value of share. Used by the ablation study.

  • scalar_cse (bool, optional) – Fine-grained control of the two passes enabled by share: _share_sums() and the scalar common sub-expression pass. None (the default) inherits the value of share. Used by the ablation study.

  • options (CodegenOptions, optional) – Behaviour options. Defaults to CodegenOptions(), that is the defaults of the behaviour keywords. A keyword passed explicitly in the same call overrides the matching field of options.

  • **legacy – Any behaviour option by name (strict, optional_derivatives, chain_rule, …; see the entries of this section and the fields of CodegenOptions). An unknown name raises TypeError.

  • symmetric_params (iterable of str, optional) – Names of rank-2 parameters known to be symmetric (declared with the symmetric attribute in a .model file).

  • param_symmetry (bool, optional) – Exploit symmetric_params: canonicalise their subscripts and fold symmetric double summations into a triangular loop (see _fold_symmetric_sums()). Off by default.

  • hessian_symmetry (bool, optional) – Compute only the upper triangle of the composition Hessian dfdndn (j >= i) and mirror it. Exact by Schwarz’ theorem. Off by default.

  • cse_backend ({"thermodiff", "sympy"}, optional) – Algorithm of the scalar common sub-expression pass.

  • sum_alpha (bool, optional) – Share summations that are equal up to the names of their bound indices (alpha equivalence), not only syntactically identical ones. Off by default.

  • array_pad (int, optional) – Extra rows added to the leading dimension of rank-2 array temporaries (t(nc + pad, nc)). Zero (the default) keeps t(nc, nc).

  • hoist_invariants (bool, optional) – Move costly sub-expressions that do not depend on every bound index of their summation out of the loop, into temporaries of lower rank (see _hoist_invariants()). Off by default.

  • chain_rule (bool, optional) – Differentiate by the chain rule over the summation nodes of the function, as a hand-written implementation does (see thermodiff.chain). Falls back to the plain derivatives when the function does not fit the pattern. Off by default.

  • hoist_loops (bool, optional) – Group the terms of every loop body over free indices by their index-dependent factors and compute the loop invariants once (see _hoist_loop_invariants()). Off by default.

  • sum_free_alpha (bool, optional) – Share summations equal up to the names of their bound and free indices (sum_k x(i,k) and sum_l x(j,l)). Off by default.

  • fuse_temps (bool, optional) – Do not materialise cheap rank-2 array temporaries that are only read inside summations: their body is inserted into the summation (see _fuse_temporaries()). Off by default.

  • nest_sums (bool, optional) – Rewrite double sums as dot products with vector sums that other outputs already need (see _nest_double_sums()). Off by default.

  • split_sqrt (bool, optional) – With chain_rule: split sqrt(c*A_a*A_b) into sqrt(c)*sqrt(A_a)*sqrt(A_b) for per-component temperature functions. Assumes they are non-negative (true for the attractive parameters of cubic equations). Off by default.

  • split_sums (bool, optional) – With chain_rule: expand summation bodies and split sums of terms into sums, so that each term can become a dot product with a vector sum. Off by default.

  • nest_shared (bool, optional) – With nest_sums: also nest double sums whose inner sum is shared by several double sums (not only by an output), and count equal summations once when deciding whether to fuse a temporary. Off by default.

  • sym_matvec (bool, optional) – With param_symmetry: emit the vector sums v(f) = sum_b P(b,f) R(b) with a symmetric P as a symmetric matrix-vector product that reads only the upper triangle. Off by default.

  • col_major (bool, optional) – Order the loops of vector sums and rank-2 tables so that the arrays they read are traversed along columns (see _prefers_column_order()). Off by default.

  • pair_cse (bool, optional) – With chain_rule: write pair functions in terms of earlier ones (tau*exp(-c tau) as tau*M), and write the temperature derivatives of pair functions with a cheap pair-dependent logarithmic rate in place (M' = M*r_ab). Off by default.

  • pair_rates (bool, optional) – With chain_rule: write pair functions in terms of earlier ones (tau*exp(-c tau) as tau*M), and write the temperature derivatives of pair functions with a cheap pair-dependent logarithmic rate in place (M' = M*r_ab). Off by default.

  • sum_transpose (bool, optional) – With sum_free_alpha: reuse a rank-2 summation that is the transpose of another one. Off by default.

  • sep_sums (bool, optional) – Distribute products over sums in summation bodies, split the sums and move out the factors that do not depend on the bound index (see _separate_sums()). Off by default.

  • sym_rank3 (bool, optional) – With param_symmetry: also canonicalise symmetric parameters of rank three or more (fully symmetric tensors). Off by default.

  • nest_general (bool, optional) – With nest_sums: also nest sums over three or more indices, and use rank-2 summations as inner sums. Off by default.

  • sym_sum2 (bool, optional) – With param_symmetry: a rank-2 summation whose body is symmetric in its two free indices is computed on the upper triangle and mirrored. Off by default.

  • cse_expensive (bool, optional) – The indexed CSE extracts a costly single-operation sub-expression (log, exp, a root) already when it is used twice. Off by default.

  • fuse_loops (bool, optional) – Merge consecutive vector sums with the same loop structure into one loop nest (see _fuse_loop_nests()); only without optional outputs. Off by default.

  • nested_nodes (bool, optional) – With chain_rule: index-free summations nested inside a node become nodes too, and derivatives are composed through them (see thermodiff.chain._nest_inner_nodes()). Off by default.

  • sym_perm (bool, optional) – Rewrite the subscripts of symmetric parameters inside loop nests so that the innermost loop index comes first (contiguous access). Exact by symmetry; applied after every other pass. Off by default.

  • fuse_guard (bool, optional) – With fuse_temps: never inline an expensive rank-2 temporary (transcendental body) that two or more different summations read, nested ones included. Off by default.

  • nest_cost (bool, optional) – With nest_sums and nest_general: nest every sum over three or more indices into an inner rank-2 table, even when no other output shares it. Off by default.

  • comp_fuse (bool, optional) – Fuse consecutive per-component maps (cmp0, cmp0_T, …) into one loop with a per-element common sub-expression elimination. Only without optional_derivatives. Off by default.

  • dummy_canon (bool, optional) – Merge the terms of a summation over two or three indices that are images of each other under a renaming of the bound indices (e.g. (b_k + b_l + b_m) with a symmetric tensor). Exact. Off by default.

  • float_canon (bool, optional) – Round every floating-point constant to its double value with a single representation before the common sub-expression passes. Off by default.

  • contiguous_args (bool, optional) – Declare every assumed-shape array argument (parameters, mole numbers and outputs) contiguous, so the compiler can drop the stride arithmetic and the multi-versioned loops. A caller that passes a non-contiguous section gets a copy-in/copy-out (still correct). Off by default.

  • fuse_outer (bool, optional) – Fuse consecutive per-component maps and scalar reductions that share the outer loop 1..nc into one loop. Only without optional_derivatives. Off by default.

  • fuse_libm_guard (bool, optional) – With fuse_outer, never fuse a double reduction into the outer loop of a map that calls exp, log, sqrt or a real power, so the map stays vectorisable. Off by default.

  • keep_libm_tables (bool, optional) – With fuse_temps, never inline a rank-2 temporary that calls a libm routine into a summation; it stays a table computed by its own map loop. Off by default.

  • table_layout (bool, optional) – With chain_rule, store a non-symmetric pair function in the subscript order of the parameters it reads (G(l, k) for exp(-c_lk tau_lk)) instead of the alphabetical order of the summation indices, so the table is written contiguously and the sums that read it take the contiguous inner index; with col_major a rank-2 sum that then reads its tables with the bound index last (sum_k G(i, k) H(j, k)) is emitted in jki order. Off by default.

  • lowrank_hess (bool or "sym", optional) – Assemble a rank-2 output (the composition Hessian) whose residual has separable terms c F(i) G(j) in rank-k form: the terms are grouped by the factor over one index, sum_l r_l(i) G_l(j), with the coefficient vectors r_l computed once (O(nc)); terms over one index and pair terms are kept. Applied only when it lowers the per-element operation count. True emits the full square in column order without mirror; "sym" keeps the triangle and mirror of hessian_symmetry. Only without optional_derivatives. Off by default.

  • drop_pair_tables (bool, optional) – Do not materialise a rank-2 table read only by scalar reductions (one double, triangular reduction and its diagonal sums) whose body calls no libm routine: its body is inlined there. In the scalar double reductions the factors over the outer index are applied once per outer iteration and the products over the inner index only become vectors. With fuse_libm_guard a single reduction that calls a libm routine does not share the outer loop of a double reduction either. Only without optional_derivatives. Off by default.

  • share_elementwise (bool, optional) – A costly rank-1 sub-expression (log, exp, a root of a per-component expression) read in two or more places – the body of a scalar reduction over k and an output over i – is computed once as a vector that every place reads. Occurrences are compared up to the index name and to the spelling of their scalar prefactors (x/y and (1/y)*x); differently spelt scalar temporaries of the shared occurrences are merged. Only without optional_derivatives. Off by default.

  • scalar_chain (bool, optional) – With chain_rule, compute the partial derivatives of the outer function F(S_1, ..., S_m, V, T) by forward second-order propagation over its expression DAG, followed by one common sub-expression elimination, instead of differentiating the expanded F (see thermodiff.chain._scalar_chain()). They become scalar temporaries computed after the reductions they read, and the outputs read them. Falls back to the plain path when F is not smooth (Piecewise, Max …). "cost" generates the kernel both ways and keeps the one with the lower operation_count (stats["scalar_chain_used"] tells which). With "estimate" the choice is made before the array pipeline, from the operation counts of the plain partials of F (after one CSE) and of the propagated definitions, so the pipeline runs once. Only without optional_derivatives. Off by default.

  • split_affine (bool, optional) – In a summation with free indices, sum_m (c - P(m, k, l)) w(m) with c and w independent of the free indices becomes c*S - sum_m P w: the scalar S = sum_m w(m) is computed once and the readers of the table read S - t, so the innermost body is one multiply-add; products of factors over the bound index only become vectors (see _split_affine()). Applied only when the body gets cheaper; only without optional_derivatives. Off by default.

  • split_acc (int or bool, optional) – 2: in the inner loop of a symmetric rank-2 table filled by a sum that reads a parameter of rank three (the O(N^3) nest of CMR), use two scalar partial accumulators per sum (even and odd m, one remainder iteration, then their sum), so that gcc vectorises the reduction without -ffast-math (reportes/brechas/ronda3-cmr-o3.md). Changes the summation order. Only without optional_derivatives. Off by default.

Returns:

The free-form Fortran source code.

Return type:

str

Warns:

UserWarning – Once per call, when validation disables ignored options.

Raises:
  • TypeError – For an unknown keyword.

  • ValueError – For an invalid option value (see CodegenOptions.validate()).

Code generator options

Typed, immutable options of the Fortran generator.

CodegenOptions groups the behaviour options of thermodiff.fortran.to_fortran(). Per-call context (the differentiated object, the selected derivatives, names, extra arguments and so on) is not part of it. The legacy keyword values (False/True/strings) are mapped to enums by CodegenOptions.from_legacy() and back by CodegenOptions.to_legacy().

class ScalarChainMode(*values)[source]

Bases: Enum

Legacy scalar_chain: False | True | "cost" | "estimate".

class SepSumsMode(*values)[source]

Bases: Enum

Legacy sep_sums: False | True | "cost".

class LowrankHessMode(*values)[source]

Bases: Enum

Legacy lowrank_hess: False | True | "sym".

class CseBackend(*values)[source]

Bases: Enum

Algorithm of the scalar CSE pass.

class Preset(*values)[source]

Bases: Enum

Named option sets, see PRESET_SETTINGS.

class CodegenOptions(strict: bool = False, optional_derivatives: bool = False, array_cse: bool = True, share: bool = True, share_sums: bool | None = None, scalar_cse: bool | None = None, param_symmetry: bool = False, hessian_symmetry: bool = False, cse_backend: CseBackend = CseBackend.THERMODIFF, sum_alpha: bool = False, array_pad: int = 0, hoist_invariants: bool = False, chain_rule: bool = False, hoist_loops: bool = False, sum_free_alpha: bool = False, fuse_temps: bool = False, nest_sums: bool = False, split_sqrt: bool = False, split_sums: bool = False, nest_shared: bool = False, sym_matvec: bool = False, col_major: bool = False, pair_cse: bool = False, pair_rates: bool = False, sum_transpose: bool = False, sep_sums: SepSumsMode = SepSumsMode.OFF, sym_rank3: bool = False, nest_general: bool = False, sym_sum2: bool = False, cse_expensive: bool = False, fuse_loops: bool = False, nested_nodes: bool = False, sym_perm: bool = False, fuse_guard: bool = False, nest_cost: bool = False, comp_fuse: bool = False, fuse_outer: bool = False, fuse_libm_guard: bool = False, keep_libm_tables: bool = False, diag_table: bool = False, sib_fuse: bool = False, dummy_canon: bool = False, float_canon: bool = False, contiguous_args: bool = False, table_layout: bool = False, lowrank_hess: LowrankHessMode = LowrankHessMode.OFF, drop_pair_tables: bool = False, share_elementwise: bool = False, scalar_chain: ScalarChainMode = ScalarChainMode.OFF, split_affine: bool = False, split_acc: int | None = None)[source]

Bases: object

Behaviour options of thermodiff.fortran.to_fortran().

Every field has the name and default of the keyword of the same name in to_fortran; see its docstring for the meaning of each one. Values are coerced on construction (legacy False/True/strings are accepted for the enum-valued fields).

Notes

scalar_chain, sep_sums and lowrank_hess receive ScalarChainMode, SepSumsMode and LowrankHessMode; split_acc is None or 2.

classmethod from_legacy(**kwargs: Any) → CodegenOptions[source]

Build options from to_fortran keyword values.

Parameters:

**kwargs – Behaviour keywords of to_fortran with their legacy values.

Returns:

The coerced options.

Return type:

CodegenOptions

Raises:
  • TypeError – For an unknown keyword.

  • ValueError – For an unknown cse_backend or a truthy non-integer split_acc. The latter deviates from today’s generator, which only converts split_acc when optional_derivatives is off.

to_legacy() → dict[str, Any][source]

Return the keyword arguments of today’s to_fortran.

Returns:

Option name to legacy value (enums become their values and split_acc=None becomes False).

Return type:

dict

classmethod from_preset(preset: Preset | str, **overrides: Any) → CodegenOptions[source]

Build a preset and apply overrides on top of it.

Presets

"minimal"

Today’s to_fortran defaults.

"standard"

The recommended default: the e8 settings of the met4 campaign (chain rule, symmetry, nesting and sum sharing).

"fastest"

The p33 settings: the fastest generated code of the met4 campaign. Meant for optional_derivatives=False, because a kernel specialised to the needed derivative set is what pays off. Generation is slower and reassociation changes the last bits of the results.

param preset:

Preset member or its value.

type preset:

Preset or str

param **overrides:

Options replacing the preset’s (legacy values or enums).

returns:

The resulting options.

rtype:

CodegenOptions

replace(**changes: Any) → CodegenOptions[source]

Return a copy with some fields changed (values are coerced).

Parameters:

**changes – Field names and their new values.

Returns:

The modified copy.

Return type:

CodegenOptions

validate(stacklevel: int = 1) → tuple[CodegenOptions, tuple[str, ...]][source]

Disable options that today’s generator silently ignores.

Parameters:

stacklevel (int, optional) – Frame the warning is attributed to: 1 is the caller of this method, 2 its caller, and so on.

Returns:

The normalised options and the names of the ignored options. A single UserWarning lists them.

Return type:

tuple

Raises:

ValueError – If split_acc is not 2 and optional_derivatives is off (the only case where to_fortran raises).

resolve_codegen_options(preset: Preset | str | None = None, options: CodegenOptions | None = None, **overrides: Any) → CodegenOptions[source]

Resolve the options of an entry point from its three sources.

The result is normalised: options that the chosen combination makes ineffective are disabled (see CodegenOptions.validate()), so the validation of to_fortran finds nothing left to report. Only the ignored options that the caller set explicitly (a non-None override or a field of options that differs from the defaults) are reported, in one UserWarning pointing at the caller of the entry point; options coming from the preset are disabled silently.

Parameters:
  • preset (Preset or str, optional) – Preset to start from. None means "standard" unless options is given. Passing both is an error.

  • options (CodegenOptions, optional) – Explicit options to start from instead of a preset.

  • **overrides – Option names and values applied on top. A value of None means “not given” and leaves the starting value untouched.

Returns:

The resulting normalised options.

Return type:

CodegenOptions

Raises:
  • ValueError – If preset is given together with options, or for the errors of CodegenOptions.validate().

  • TypeError – If an override name is not an option.