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
DiffPlzinstance.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 oneUserWarning(seeCodegenOptions.validate()). For ready-made option sets useCodegenOptions.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 groupsall,none,firstandsecond(seethermodiff.derivatives.resolve_derivatives()). By default every non-zero derivative computed bydiffis emitted.name (str, optional) – Base name used for the generated variables. Defaults to the
nameattribute ofdiff.subroutine_name (str, optional) – Name of the generated subroutine. Defaults to the base name.
strict (bool, optional) – When
True, raise aValueErrorif the expression contains internal functions or unresolved derivatives instead of exposing them as input arguments. By defaultFalse.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
usestatement 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 Fortranoptionalargument 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 toFalseto 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” isarray_cse=False, share=False; “V2 partial” isarray_cse=False; “V3 full” isarray_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_opssummed over the final output expressions and over the body of every shared temporary),operation_count_tool(the exact tool/options used) andn_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 ofshare. 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 ofshare. 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 ofoptions.**legacy – Any behaviour option by name (
strict,optional_derivatives,chain_rule, …; see the entries of this section and the fields ofCodegenOptions). An unknown name raisesTypeError.symmetric_params (iterable of str, optional) – Names of rank-2 parameters known to be symmetric (declared with the
symmetricattribute in a.modelfile).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) keepst(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)andsum_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: splitsqrt(c*A_a*A_b)intosqrt(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 sumsv(f) = sum_b P(b,f) R(b)with a symmetricPas 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)astau*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)astau*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 (seethermodiff.chain._nest_inner_nodes()). Off by default.sym_perm (bool, optional) – Rewrite the subscripts of
symmetricparameters 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_sumsandnest_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 withoutoptional_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..ncinto one loop. Only withoutoptional_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 callsexp,log,sqrtor 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)forexp(-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; withcol_majora rank-2 sum that then reads its tables with the bound index last (sum_k G(i, k) H(j, k)) is emitted injkiorder. 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 vectorsr_lcomputed once (O(nc)); terms over one index and pair terms are kept. Applied only when it lowers the per-element operation count.Trueemits the full square in column order without mirror;"sym"keeps the triangle and mirror ofhessian_symmetry. Only withoutoptional_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_guarda single reduction that calls a libm routine does not share the outer loop of a double reduction either. Only withoutoptional_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 overkand an output overi– 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/yand(1/y)*x); differently spelt scalar temporaries of the shared occurrences are merged. Only withoutoptional_derivatives. Off by default.scalar_chain (bool, optional) – With
chain_rule, compute the partial derivatives of the outer functionF(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 expandedF(seethermodiff.chain._scalar_chain()). They become scalar temporaries computed after the reductions they read, and the outputs read them. Falls back to the plain path whenFis not smooth (Piecewise,Max…)."cost"generates the kernel both ways and keeps the one with the loweroperation_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 ofF(after one CSE) and of the propagated definitions, so the pipeline runs once. Only withoutoptional_derivatives. Off by default.split_affine (bool, optional) – In a summation with free indices,
sum_m (c - P(m, k, l)) w(m)withcandwindependent of the free indices becomesc*S - sum_m P w: the scalarS = sum_m w(m)is computed once and the readers of the table readS - 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 withoutoptional_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 oddm, 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 withoutoptional_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:
EnumLegacy
scalar_chain:False | True | "cost" | "estimate".
- 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:
objectBehaviour 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 (legacyFalse/True/strings are accepted for the enum-valued fields).Notes
scalar_chain,sep_sumsandlowrank_hessreceiveScalarChainMode,SepSumsModeandLowrankHessMode;split_accisNoneor2.- classmethod from_legacy(**kwargs: Any) CodegenOptions[source]¶
Build options from
to_fortrankeyword values.- Parameters:
**kwargs – Behaviour keywords of
to_fortranwith their legacy values.- Returns:
The coerced options.
- Return type:
- Raises:
TypeError – For an unknown keyword.
ValueError – For an unknown
cse_backendor a truthy non-integersplit_acc. The latter deviates from today’s generator, which only convertssplit_accwhenoptional_derivativesis 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=NonebecomesFalse).- 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_fortrandefaults."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:
- 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:
1is the caller of this method,2its caller, and so on.- Returns:
The normalised options and the names of the ignored options. A single
UserWarninglists them.- Return type:
tuple
- Raises:
ValueError – If
split_accis not 2 andoptional_derivativesis off (the only case whereto_fortranraises).
- 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 ofto_fortranfinds nothing left to report. Only the ignored options that the caller set explicitly (a non-Noneoverride or a field ofoptionsthat differs from the defaults) are reported, in oneUserWarningpointing 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.
Nonemeans"standard"unlessoptionsis 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
Nonemeans “not given” and leaves the starting value untouched.
- Returns:
The resulting normalised options.
- Return type:
- Raises:
ValueError – If
presetis given together withoptions, or for the errors ofCodegenOptions.validate().TypeError – If an override name is not an option.