{ "cells": [ { "cell_type": "markdown", "id": "76d3a242", "metadata": {}, "source": [ "# Model files: compiling a `.model` file to Fortran\n", "\n", "The `thermodiff.model` front-end lets you describe a thermodynamic model in a\n", "small text file and compile it into a Fortran module with the function and all\n", "its analytical derivatives. This is the recommended entry point if you do not\n", "want to write Python. The `.model` file is the single source of truth." ] }, { "cell_type": "code", "execution_count": 1, "id": "f4830489", "metadata": { "execution": { "iopub.execute_input": "2026-10-16T19:36:02.395517Z", "iopub.status.busy": "2026-10-16T19:36:02.395196Z", "iopub.status.idle": "2026-10-16T19:36:02.402207Z", "shell.execute_reply": "2026-10-16T19:36:02.400656Z" } }, "outputs": [], "source": [ "# Install if you are in Google Colab\n", "import sys\n", "\n", "if \"google.colab\" in sys.modules:\n", " !pip install git+https://github.com/ipqa-research/thermodiff" ] }, { "cell_type": "markdown", "id": "af29104d", "metadata": {}, "source": [ "## 1. Describe the model\n", "\n", "A `.model` file is organized in sections: `variables`, `parameters`,\n", "`expressions` and `function`. Intermediate expressions are written in index\n", "notation and substituted into the final `function` before it is differentiated.\n", "Here is a Peng-Robinson style pressure model:" ] }, { "cell_type": "code", "execution_count": 2, "id": "5dd40f00", "metadata": { "execution": { "iopub.execute_input": "2026-10-16T19:36:02.406068Z", "iopub.status.busy": "2026-10-16T19:36:02.405720Z", "iopub.status.idle": "2026-10-16T19:36:02.412250Z", "shell.execute_reply": "2026-10-16T19:36:02.410706Z" } }, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "\n", "model pr\n", "target fortran\n", "use yaeos__constants, only: R\n", "\n", "variables\n", " n nc\n", " V\n", " T\n", "\n", "parameters\n", " ac nc\n", " Tc nc\n", " k nc nc\n", " b nc\n", "\n", "expressions\n", " alpha_i = (T/Tc_i)^2\n", " a_i = ac_i*alpha_i\n", " amix = sum_i sum_j n_i*n_j*sqrt(a_i*a_j)*(1 - k_ij)\n", " bmix = sum_i n_i*b_i\n", "\n", "function\n", " R*T/(V - bmix) - amix/(V*(V + bmix) + bmix*(V - bmix))\n", "\n" ] } ], "source": [ "model = r'''\n", "model pr\n", "target fortran\n", "use yaeos__constants, only: R\n", "\n", "variables\n", " n nc\n", " V\n", " T\n", "\n", "parameters\n", " ac nc\n", " Tc nc\n", " k nc nc\n", " b nc\n", "\n", "expressions\n", " alpha_i = (T/Tc_i)^2\n", " a_i = ac_i*alpha_i\n", " amix = sum_i sum_j n_i*n_j*sqrt(a_i*a_j)*(1 - k_ij)\n", " bmix = sum_i n_i*b_i\n", "\n", "function\n", " R*T/(V - bmix) - amix/(V*(V + bmix) + bmix*(V - bmix))\n", "'''\n", "print(model)" ] }, { "cell_type": "markdown", "id": "ef045bff", "metadata": {}, "source": [ "## 2. Compile it\n", "\n", "`compile_model` returns the Fortran source of a module that contains a\n", "subroutine evaluating the function and all first and second order derivatives.\n", "On the command line the same is done with\n", "`thermodiff-model pr.model -o pr.f90`." ] }, { "cell_type": "code", "execution_count": 3, "id": "0a2b5213", "metadata": { "execution": { "iopub.execute_input": "2026-10-16T19:36:02.416139Z", "iopub.status.busy": "2026-10-16T19:36:02.415774Z", "iopub.status.idle": "2026-10-16T19:36:04.715515Z", "shell.execute_reply": "2026-10-16T19:36:04.714725Z" } }, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "! Generated by thermodiff from model 'pr'.\n", "! Do not edit by hand.\n", "module pr_mod\n", " use yaeos__constants, only: R\n", " implicit none\n", "contains\n", "\n", " subroutine pr_derivs(nc, V, T, Tc, ac, b, k, n, f, dfdT, dfdV, dfdn, dfdT2, dfdV2, dfdndn, dfdTdV, dfdndT, dfdndV)\n", " implicit none\n", " integer, intent(in) :: nc\n", " real(8), intent(in) :: V\n", " real(8), intent(in) :: T\n", " real(8), intent(in) :: Tc(:)\n", " real(8), intent(in) :: ac(:)\n", " real(8), intent(in) :: b(:)\n", " real(8), intent(in) :: k(:, :)\n", " real(8), intent(in) :: n(:)\n", " real(8), intent(out) :: f\n", " real(8), intent(out) :: dfdT\n", " real(8), intent(out) :: dfdV\n", " real(8), intent(out) :: dfdn(:)\n", " real(8), intent(out) :: dfdT2\n", " real(8), intent(out) :: dfdV2\n", " real(8), intent(out) :: dfdndn(:, :)\n", " real(8), intent(out) :: dfdTdV\n", " real(8), intent(out) :: dfdndT(:)\n", " real(8), intent(out) :: dfdndV(:)\n", " real(8) :: res, t1, t10, t11, t12, t13, t14, t15, t16, t17, t18, t19, t2, t20, t21, t22, t23, t24, t25, t26, t27, t28\n", " real(8) :: t29, t3, t30, t4, t5, t6, t7, t8, t9\n", " integer :: i, j, l, m\n", "\n", " t1 = 0.0d0\n", " do m = 1, nc\n", " do l = 1, nc\n", " t1 = t1 + sqrt(T**4*ac(l)*ac(m)/(Tc(l)**2*Tc(m)**2))*(1 - k(l, m))*n(l)*n(m)\n", " end do\n", " end do\n", " t2 = 0.0d0\n", " do l = 1, nc\n", " t2 = t2 + b(l)*n(l)\n", " end do\n", " res = R*T/(V - t2) - t1/(V*(V + t2) + t2*(V - t2))\n", " f = res\n", "\n", " t3 = 0.0d0\n", " do m = 1, nc\n", " do l = 1, nc\n", " t3 = t3 + 2*sqrt(T**4*ac(l)*ac(m)/(Tc(l)**2*Tc(m)**2))*(1 - k(l, m))*n(l)*n(m)/T\n", " end do\n", " end do\n", " t4 = 0.0d0\n", " do l = 1, nc\n", " t4 = t4 + b(l)*n(l)\n", " end do\n", " res = R/(V - t4) - t3/(V*(V + t4) + t4*(V - t4))\n", " dfdT = res\n", "\n", " t5 = 0.0d0\n", " do m = 1, nc\n", " do l = 1, nc\n", " t5 = t5 + sqrt(T**4*ac(l)*ac(m)/(Tc(l)**2*Tc(m)**2))*(1 - k(l, m))*n(l)*n(m)\n", " end do\n", " end do\n", " t6 = 0.0d0\n", " do l = 1, nc\n", " t6 = t6 + b(l)*n(l)\n", " end do\n", " res = -R*T/(V - t6)**2 - t5*(-2*V - 2*t6)/(V*(V + t6) + t6*(V - t6))**2\n", " dfdV = res\n", "\n", " do i = 1, nc\n", " t7 = 0.0d0\n", " do m = 1, nc\n", " do l = 1, nc\n", " t7 = t7 + sqrt(T**4*ac(l)*ac(m)/(Tc(l)**2*Tc(m)**2))*(1 - k(l, m))*n(l)*n(m)\n", " end do\n", " end do\n", " t8 = 0.0d0\n", " do l = 1, nc\n", " t8 = t8 + b(l)*n(l)\n", " end do\n", " t9 = 0.0d0\n", " do m = 1, nc\n", " t9 = t9 + sqrt(T**4*ac(i)*ac(m)/(Tc(i)**2*Tc(m)**2))*(k(i, m) - 1)*n(m)\n", " end do\n", " t10 = 0.0d0\n", " do l = 1, nc\n", " t10 = t10 + sqrt(T**4*ac(i)*ac(l)/(Tc(i)**2*Tc(l)**2))*(1 - k(l, i))*n(l)\n", " end do\n", " res = R*T*b(i)/(V - t8)**2 - t7*(-V*b(i) + t8*b(i) - (V - t8)*b(i))/(V*( &\n", " V + t8) + t8*(V - t8))**2 - (t10 - t9)/(V*(V + t8) + t8*(V - t8))\n", " dfdn(i) = res\n", " end do\n", "\n", " t11 = 0.0d0\n", " do m = 1, nc\n", " do l = 1, nc\n", " t11 = t11 + 2*sqrt(T**4*ac(l)*ac(m)/(Tc(l)**2*Tc(m)**2))*(1 - k(l, m))*n(l)*n(m)/T** &\n", " 2\n", " end do\n", " end do\n", " t12 = 0.0d0\n", " do l = 1, nc\n", " t12 = t12 + b(l)*n(l)\n", " end do\n", " res = -t11/(V*(V + t12) + t12*(V - t12))\n", " dfdT2 = res\n", "\n", " t13 = 0.0d0\n", " do m = 1, nc\n", " do l = 1, nc\n", " t13 = t13 + sqrt(T**4*ac(l)*ac(m)/(Tc(l)**2*Tc(m)**2))*(1 - k(l, m))*n(l)*n(m)\n", " end do\n", " end do\n", " t14 = 0.0d0\n", " do l = 1, nc\n", " t14 = t14 + b(l)*n(l)\n", " end do\n", " res = 2*R*T/(V - t14)**3 - t13*(-4*V - 4*t14)*(-2*V - 2*t14)/(V*(V + t14 &\n", " ) + t14*(V - t14))**3 + 2*t13/(V*(V + t14) + t14*(V - t14))**2\n", " dfdV2 = res\n", "\n", " do i = 1, nc\n", " do j = 1, nc\n", " t15 = 0.0d0\n", " do m = 1, nc\n", " t15 = t15 + sqrt(T**4*ac(j)*ac(m)/(Tc(j)**2*Tc(m)**2))*(k(j, m) - 1)*n(m)\n", " end do\n", " t16 = 0.0d0\n", " do l = 1, nc\n", " t16 = t16 + b(l)*n(l)\n", " end do\n", " t17 = 0.0d0\n", " do m = 1, nc\n", " t17 = t17 + sqrt(T**4*ac(i)*ac(m)/(Tc(i)**2*Tc(m)**2))*(k(i, m) - 1)*n(m)\n", " end do\n", " t18 = 0.0d0\n", " do m = 1, nc\n", " do l = 1, nc\n", " t18 = t18 + sqrt(T**4*ac(l)*ac(m)/(Tc(l)**2*Tc(m)**2))*(1 - k(l, m))*n(l)*n(m)\n", " end do\n", " end do\n", " t19 = 0.0d0\n", " do l = 1, nc\n", " t19 = t19 + sqrt(T**4*ac(i)*ac(l)/(Tc(i)**2*Tc(l)**2))*(1 - k(l, i))*n(l)\n", " end do\n", " t20 = 0.0d0\n", " do l = 1, nc\n", " t20 = t20 + sqrt(T**4*ac(j)*ac(l)/(Tc(j)**2*Tc(l)**2))*(1 - k(l, j))*n(l)\n", " end do\n", " res = 2*R*T*b(i)*b(j)/(V - t16)**3 - 2*t18*b(i)*b(j)/(V*(V + t16) + t16* &\n", " (V - t16))**2 - t18*(-V*b(i) + t16*b(i) - (V - t16)*b(i))*(-2*V*b &\n", " (j) + 2*t16*b(j) - 2*(V - t16)*b(j))/(V*(V + t16) + t16*(V - t16 &\n", " ))**3 - (-t15 + t20)*(-V*b(i) + t16*b(i) - (V - t16)*b(i))/(V*(V &\n", " + t16) + t16*(V - t16))**2 - (-t17 + t19)*(-V*b(j) + t16*b(j) - ( &\n", " V - t16)*b(j))/(V*(V + t16) + t16*(V - t16))**2 - (sqrt(T**4*ac(i &\n", " )*ac(j)/(Tc(i)**2*Tc(j)**2))*(1 - k(j, i)) - sqrt(T**4*ac(i)*ac(j &\n", " )/(Tc(i)**2*Tc(j)**2))*(k(i, j) - 1))/(V*(V + t16) + t16*(V - t16 &\n", " ))\n", " dfdndn(i, j) = res\n", " end do\n", " end do\n", "\n", " t21 = 0.0d0\n", " do m = 1, nc\n", " do l = 1, nc\n", " t21 = t21 + 2*sqrt(T**4*ac(l)*ac(m)/(Tc(l)**2*Tc(m)**2))*(1 - k(l, m))*n(l)*n(m)/T\n", " end do\n", " end do\n", " t22 = 0.0d0\n", " do l = 1, nc\n", " t22 = t22 + b(l)*n(l)\n", " end do\n", " res = -R/(V - t22)**2 - t21*(-2*V - 2*t22)/(V*(V + t22) + t22*(V - t22)) &\n", " **2\n", " dfdTdV = res\n", "\n", " do i = 1, nc\n", " t23 = 0.0d0\n", " do m = 1, nc\n", " do l = 1, nc\n", " t23 = t23 + 2*sqrt(T**4*ac(l)*ac(m)/(Tc(l)**2*Tc(m)**2))*(1 - k(l, m))*n(l)*n(m)/T\n", " end do\n", " end do\n", " t24 = 0.0d0\n", " do l = 1, nc\n", " t24 = t24 + b(l)*n(l)\n", " end do\n", " t25 = 0.0d0\n", " do m = 1, nc\n", " t25 = t25 + sqrt(T**4*ac(i)*ac(m)/(Tc(i)**2*Tc(m)**2))*(k(i, m) - 1)*n(m)\n", " end do\n", " t26 = 0.0d0\n", " do l = 1, nc\n", " t26 = t26 + 2*sqrt(T**4*ac(i)*ac(l)/(Tc(i)**2*Tc(l)**2))*(1 - k(l, i))*n(l)/T\n", " end do\n", " res = R*b(i)/(V - t24)**2 - t23*(-V*b(i) + t24*b(i) - (V - t24)*b(i))/(V &\n", " *(V + t24) + t24*(V - t24))**2 - (t26 - 2*t25/T)/(V*(V + t24) + &\n", " t24*(V - t24))\n", " dfdndT(i) = res\n", " end do\n", "\n", " do i = 1, nc\n", " t27 = 0.0d0\n", " do m = 1, nc\n", " do l = 1, nc\n", " t27 = t27 + sqrt(T**4*ac(l)*ac(m)/(Tc(l)**2*Tc(m)**2))*(1 - k(l, m))*n(l)*n(m)\n", " end do\n", " end do\n", " t28 = 0.0d0\n", " do l = 1, nc\n", " t28 = t28 + b(l)*n(l)\n", " end do\n", " t29 = 0.0d0\n", " do m = 1, nc\n", " t29 = t29 + sqrt(T**4*ac(i)*ac(m)/(Tc(i)**2*Tc(m)**2))*(k(i, m) - 1)*n(m)\n", " end do\n", " t30 = 0.0d0\n", " do l = 1, nc\n", " t30 = t30 + sqrt(T**4*ac(i)*ac(l)/(Tc(i)**2*Tc(l)**2))*(1 - k(l, i))*n(l)\n", " end do\n", " res = -2*R*T*b(i)/(V - t28)**3 - t27*(-2*V - 2*t28)*(-2*V*b(i) + 2*t28*b &\n", " (i) - 2*(V - t28)*b(i))/(V*(V + t28) + t28*(V - t28))**3 + 2*t27* &\n", " b(i)/(V*(V + t28) + t28*(V - t28))**2 - (-2*V - 2*t28)*(-t29 + &\n", " t30)/(V*(V + t28) + t28*(V - t28))**2\n", " dfdndV(i) = res\n", " end do\n", "\n", " end subroutine pr_derivs\n", "end module pr_mod\n", "\n" ] } ], "source": [ "from thermodiff.model import compile_model\n", "\n", "fortran = compile_model(model, filename=\"pr.model\")\n", "print(fortran)" ] }, { "cell_type": "markdown", "id": "dd778eea", "metadata": {}, "source": [ "A few things to notice:\n", "\n", "* The `use yaeos__constants, only: R` line is preserved, so `R` is taken from\n", " the `yaeos` module instead of being passed as an argument.\n", "* `nc` and the rank of every array are inferred from the declarations;\n", " `k` is declared as `k(:, :)` and `b` as `b(:)`.\n", "* The intermediate expressions `alpha`, `a`, `amix` and `bmix` were inlined\n", " and do not appear in the generated code.\n", "* All the first and second order derivatives of the declared variables are\n", " emitted: `f`, `dfdT`, `dfdV`, `dfdT2`, `dfdV2`, `dfdTdV`, `dfdn`, `dfdndn`,\n", " `dfdndT` and `dfdndV`." ] }, { "cell_type": "markdown", "id": "81abd8d3", "metadata": {}, "source": [ "## 3. Verify the derivatives numerically\n", "\n", "The generated subroutine can be compiled and compared with central finite\n", "differences of the model. The next cell does that when `gfortran` is\n", "available." ] }, { "cell_type": "code", "execution_count": 4, "id": "59907e7c", "metadata": { "execution": { "iopub.execute_input": "2026-10-16T19:36:04.717501Z", "iopub.status.busy": "2026-10-16T19:36:04.717285Z", "iopub.status.idle": "2026-10-16T19:36:05.295070Z", "shell.execute_reply": "2026-10-16T19:36:05.293935Z" } }, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ " f = 916.96446181898011 \n", " dfdT = 2.8639718111433705 \n", " dfdV = -316.04576867931746 \n", " dfdn = 12.327283070984604 9.1760394474430420 \n", " dfdndn = 0.24612187652112627 0.10092104812048516 \n", "\n" ] } ], "source": [ "import os\n", "import shutil\n", "import subprocess\n", "import tempfile\n", "\n", "compiler = shutil.which(\"gfortran\")\n", "\n", "stub = (\n", " \"module yaeos__constants\\n\"\n", " \" implicit none\\n\"\n", " \" real(8), parameter :: R = 8.31446261815324d0\\n\"\n", " \"end module yaeos__constants\\n\"\n", ")\n", "\n", "driver = '''\n", "program main\n", " use pr_mod\n", " implicit none\n", " integer, parameter :: nc = 2\n", " real(8) :: n(nc), V, T, ac(nc), Tc(nc), k(nc, nc), b(nc)\n", " real(8) :: f, dfdT, dfdV, dfdT2, dfdV2, dfdTdV\n", " real(8) :: dfdn(nc), dfdndn(nc, nc), dfdndT(nc), dfdndV(nc)\n", " integer :: i\n", " n = [1.0d0, 2.0d0]\n", " ac = [0.5d0, 0.8d0]\n", " Tc = [300.0d0, 400.0d0]\n", " b = [0.04d0, 0.03d0]\n", " k = reshape([0.0d0, 0.02d0, 0.02d0, 0.0d0], [nc, nc])\n", " V = 3.0d0\n", " T = 320.0d0\n", " call pr_derivs(nc, V, T, Tc, ac, b, k, n, f, dfdT, dfdV, dfdn, &\n", " dfdT2, dfdV2, dfdndn, dfdTdV, dfdndT, dfdndV)\n", " write(*,*) 'f =', f\n", " write(*,*) 'dfdT =', dfdT\n", " write(*,*) 'dfdV =', dfdV\n", " write(*,*) 'dfdn =', (dfdn(i), i=1,nc)\n", " write(*,*) 'dfdndn =', (dfdndn(i,i), i=1,nc)\n", "end program main\n", "'''\n", "\n", "if compiler is None:\n", " print(\"gfortran not found, skipping the numerical check\")\n", "else:\n", " workdir = tempfile.mkdtemp()\n", " source = os.path.join(workdir, \"main.f90\")\n", " with open(source, \"w\") as handle:\n", " handle.write(stub + fortran + driver)\n", " exe = os.path.join(workdir, \"a.out\")\n", " subprocess.run(\n", " [compiler, \"-O2\", \"-o\", exe, source], check=True, cwd=workdir\n", " )\n", " print(subprocess.run([exe], capture_output=True, text=True).stdout)" ] }, { "cell_type": "markdown", "id": "c11b22db", "metadata": {}, "source": [ "## Notes\n", "\n", "* The module is named `_mod` and the subroutine `_derivs`.\n", "* Indexed names use a single letter per index (`n_i`, `k_ij`); the\n", " compiler renames them internally so they never clash with the\n", " differentiation indices.\n", "* Sums are written `sum_i expr` (from `1` to `nc`) or with explicit\n", " limits `sum_i[a:b] expr`.\n", "* Every undeclared name, mismatched subscript or unbalanced index is\n", " reported with the file and line number." ] } ], "metadata": { "kernelspec": { "display_name": "Python 3", "language": "python", "name": "python3" }, "language_info": { "codemirror_mode": { "name": "ipython", "version": 3 }, "file_extension": ".py", "mimetype": "text/x-python", "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", "version": "3.14.7" } }, "nbformat": 4, "nbformat_minor": 5 }