Add a Julia Interface for Cantera (Cantera.jl)

.github/workflows/julia-interface.yml

@@ -0,0 +1,89 @@
+# CI for the experimental Julia interface (interfaces/julia).
+#
+# Builds libcantera *from this checkout* (so the generated CLib matches the
+# bindings, including functions this branch adds/renames), then runs the Julia
+# test suite against the freshly built library on Linux.
+name: Julia interface
+
+on:
+  push:
+    paths:
+      - 'interfaces/julia/**'
+      - 'interfaces/sourcegen/**'
+      - 'interfaces/clib/**'
+      - '.github/workflows/julia-interface.yml'
+  pull_request:
+    paths:
+      - 'interfaces/julia/**'
+      - 'interfaces/sourcegen/**'
+      - 'interfaces/clib/**'
+      - '.github/workflows/julia-interface.yml'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    name: Julia ${{ matrix.julia-version }} on ubuntu-latest
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        shell: bash -el {0}
+    strategy:
+      fail-fast: false
+      matrix:
+        julia-version: ['1']
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          persist-credentials: false
+
+      - name: Set up build dependencies (conda)
+        uses: conda-incubator/setup-miniconda@fc2d68f6413eb2d87b895e92f8584b5b94a10167 # v3.3.0
+        with:
+          miniforge-version: latest
+          activate-environment: build
+          python-version: '3.12'
+          channels: conda-forge
+
+      - name: Install Cantera build dependencies
+        run: |
+          # Build toolchain + C++ deps, plus sourcegen's Python deps (jinja2,
+          # ruamel.yaml) which are needed to regenerate the CLib during the build.
+          conda install -y scons cython "eigen" sundials fmt yaml-cpp hdf5 \
+            "boost-cpp" doxygen openblas jinja2 "ruamel.yaml"
+
+      - name: Build libcantera (shared)
+        run: |
+          cat > cantera.conf <<EOF
+          prefix = '${CONDA_PREFIX}'
+          python_package = 'n'
+          f90_interface = 'n'
+          system_eigen = 'y'
+          system_sundials = 'y'
+          system_fmt = 'y'
+          system_yamlcpp = 'y'
+          system_blas_lapack = 'y'
+          extra_inc_dirs = '${CONDA_PREFIX}/include'
+          extra_lib_dirs = '${CONDA_PREFIX}/lib'
+          boost_inc_dir = '${CONDA_PREFIX}/include'
+          googletest = 'none'
+          EOF
+          # `scons build` regenerates the CLib and the low-level Julia bindings
+          # from interfaces/sourcegen and auto-generates the doxygen tag it
+          # needs (doxygen installed above).
+          scons build -j2
+
+      - name: Set up Julia
+        uses: julia-actions/setup-julia@4c0cb0fce8556fdb04a90347310e5db8b1f98fb9 # v2.7.0
+        with:
+          version: ${{ matrix.julia-version }}
+
+      - name: Run tests
+        env:
+          CANTERA_LIBRARY_PATH: ${{ github.workspace }}/build/lib
+          CANTERA_DATA: ${{ github.workspace }}/data
+        run: |
+          julia --project=interfaces/julia -e 'using Pkg; Pkg.instantiate()'
+          julia --project=interfaces/julia interfaces/julia/test/runtests.jl

.github/workflows/main.yml

@@ -520,9 +520,13 @@ jobs:
           pip install "git+https://github.com/Cantera/sphinx-tags.git@main"
       - name: Build Cantera
         run: scons build -j4 debug=n optimize=y use_pch=n
+      - name: Set up Julia
+        uses: julia-actions/setup-julia@4c0cb0fce8556fdb04a90347310e5db8b1f98fb9 # v2.7.0
+        with:
+          version: '1'
       - name: Build documentation
         run: |
-          scons sphinx doxygen logging=debug \
+          scons sphinx doxygen julia_docs=y logging=debug \
             sphinx_options="-W --keep-going --warning-file=sphinx-warnings.txt"
       - name: Show Sphinx warnings
         run: |

AUTHORS.md

@@ -49,6 +49,7 @@ update, please report on Cantera's
 - **Ashwin Kumar** [@mgashwinkumar](https://github.com/mgashwinkumar) - Virginia Tech
 - **Jon Kristofer**
 - **Samesh Lakothia** [@sameshl](https://github.com/sameshl)
+- **Louis Libat** [@Fastaxx](https://github.com/Fastaxx) - Gustave Eiffel University
 - **Kyle Linevitch, Jr.** [@KyleLinevitchJr](https://github.com/KyleLinevitchJr)
 - **Christopher Leuth**
 - **Nicholas Malaya** [@nicholasmalaya](https://github.com/nicholasmalaya) - University of Texas at Austin

SConstruct

@@ -105,7 +105,7 @@ if os.name not in ["nt", "posix"]:
     sys.exit(1)
 
 valid_commands = ("build", "clean", "install", "uninstall",
-                  "help", "msi", "samples", "sphinx", "doxygen", "dump",
+                  "help", "msi", "samples", "sphinx", "doxygen", "julia", "dump",
                   "sdist", "pyodide-wheel")
 
 # set default logging level
@@ -419,6 +419,11 @@ config_options = [
         "sphinx_docs",
         "Build HTML documentation for Cantera using Sphinx.",
         False),
+    BoolOption(
+        "julia_docs",
+        """Build HTML documentation for the Julia interface using Documenter.
+           Requires Julia, a built libcantera, and the generated CLib bindings.""",
+        False),
     BoolOption(
         "run_examples",
         """Run examples to generate plots and outputs for Sphinx Gallery. Disable to
@@ -1016,6 +1021,8 @@ if 'doxygen' in COMMAND_LINE_TARGETS:
     env['doxygen_docs'] = True
 if 'sphinx' in COMMAND_LINE_TARGETS:
     env['sphinx_docs'] = True
+if 'julia' in COMMAND_LINE_TARGETS:
+    env['julia_docs'] = True
 for arg in ARGUMENTS:
     if arg not in config:
         logger.error(f"Encountered unexpected command line option: {arg!r}")
@@ -2009,6 +2016,8 @@ if env['f90_interface'] == 'y':
 # to run this for scons doxygen and scons sphinx
 if not {"doxygen", "sphinx"} & set(COMMAND_LINE_TARGETS):
     SConscript("interfaces/clib/SConscript")
+    # The Julia bindings are scaffolded from the same CLib specifications
+    SConscript("interfaces/julia/SConscript")
 
 VariantDir('build/src', 'src', duplicate=0)
 SConscript('build/src/SConscript')
@@ -2021,7 +2030,8 @@ if env['CC'] != 'cl':
     VariantDir('build/platform', 'platform/posix', duplicate=0)
     SConscript('build/platform/SConscript')
 
-if env['doxygen_docs'] or env['sphinx_docs'] or "install" in COMMAND_LINE_TARGETS:
+if (env['doxygen_docs'] or env['sphinx_docs'] or env['julia_docs']
+        or "install" in COMMAND_LINE_TARGETS):
     SConscript('doc/SConscript')
 
 # Sample programs (also used from test_problems/SConscript)

doc/SConscript

@@ -135,6 +135,30 @@ if localenv['sphinx_docs']:
     if localenv['doxygen_docs']:
         localenv.Depends(sphinxdocs, docs)
 
+if localenv['julia_docs']:
+    juliaenv = localenv.Clone()
+    juliaenv['ENV']['CANTERA_LIBRARY_PATH'] = Dir('#build/lib').abspath
+    juliaenv['ENV']['CANTERA_DATA'] = Dir('#data').abspath
+
+    julia_doc = build(juliaenv.Command(
+        "#build/doc/html/julia/index.html",
+        "#interfaces/julia/docs/make.jl",
+        [
+            Delete("build/doc/html/julia"),
+            "julia --project=interfaces/julia/docs -e "
+            "'using Pkg; Pkg.develop(PackageSpec(path=\"interfaces/julia\")); "
+            "Pkg.instantiate()'",
+            "julia --project=interfaces/julia/docs $SOURCE",
+            Copy("build/doc/html/julia", "interfaces/julia/docs/build"),
+        ]
+    ))
+    env.Depends(julia_doc, env['cantera_shlib'])
+    env.Depends(julia_doc, multi_glob(env, '#interfaces/julia/src', 'jl') +
+                           multi_glob(env, '#interfaces/julia/docs/src', 'md'))
+    env.Alias('julia', julia_doc)
+    if localenv['sphinx_docs']:
+        env.Depends(sphinxdocs, julia_doc)
+
 doc_files = install(localenv.RecursiveInstall, '$inst_docdir',
                     '#build/doc/html', exclude=['\\.map', '\\.md5'])
 

doc/sphinx/reference/index.md

@@ -35,6 +35,10 @@ mechanism files.
 :text-align: center
 ```
 
+```{grid-item-card} Julia API Reference
+:link: ../julia/index.html
+```
+
 ```{grid-item-card} .NET API Reference
 :link: /dotnet/index
 :link-type: doc

interfaces/julia/.gitignore

@@ -0,0 +1,7 @@
+# Julia resolves this per-environment; do not commit.
+Manifest.toml
+
+/src/generated/
+
+# Documenter output.
+docs/build/

interfaces/julia/Project.toml

@@ -0,0 +1,14 @@
+name = "Cantera"
+uuid = "c8cccd67-5bbd-4b73-b352-8d151246ed36"
+authors = ["Cantera Developers <developers@cantera.org>"]
+version = "0.1.0"
+
+[compat]
+julia = "1.9"
+
+[extras]
+LinearAlgebra = "37e2e46d-f89d-539d-b4ee-838fcccc9c8e"
+Test = "8dfed614-e22c-5e08-85e1-65c5234f0b40"
+
+[targets]
+test = ["LinearAlgebra", "Test"]

interfaces/julia/README.md

@@ -0,0 +1,47 @@
+# Cantera.jl
+
+A Julia interface to [Cantera](https://cantera.org) for chemical
+kinetics, thermodynamics, and transport. It links Cantera's native `libcantera`
+directly through the generated CLib API — it is **not** a reimplementation of
+Cantera and has **no** Python dependency.
+
+## Install
+
+Requires Julia 1.9+ and a compiled `libcantera`. Point the package at the
+library (a directory or a full path) and the mechanism data:
+
+```bash
+export CANTERA_LIBRARY_PATH=/path/to/cantera/lib   # or use a conda env
+export CANTERA_DATA=/path/to/cantera/data          # for gri30.yaml, etc.
+```
+
+The low-level CLib bindings are scaffolded by `scons build` and are kept up to
+date by the build process.
+
+```julia
+using Pkg
+Pkg.activate("interfaces/julia")
+Pkg.instantiate()
+```
+
+## Quickstart
+
+```julia
+using Cantera
+gas = Solution("gri30.yaml")
+set_TPX!(gas, 1000.0, one_atm, "H2:2, O2:1, N2:4")
+net = ReactorNet(IdealGasReactor(gas))
+advance!(net, 1e-3)
+temperature(gas)          # ignited temperature [K]
+```
+
+## Documentation
+
+Exported functions carry docstrings, accessible from the Julia REPL help mode
+(type `?` followed by the function name). See the [`examples/`](examples)
+directory for runnable usage.
+
+## Status
+
+Experimental. This interface targets Cantera's experimental CLib backend, and
+APIs may change.

interfaces/julia/SConscript

@@ -0,0 +1,26 @@
+"""SConscript file for the generated Julia CLib bindings."""
+from pathlib import Path
+
+Import("env", "build")
+
+# Generated file names can be anticipated from the CLib specifications
+auto_path = Path(Dir("#interfaces/sourcegen/src/sourcegen/headers").abspath)
+yaml_files = sorted(auto_path.glob("ct*.yaml"))
+generated_files = ["#interfaces/julia/src/generated/_manifest.jl"]
+generated_files.extend(
+    f"#interfaces/julia/src/generated/lib{yaml_file.stem}.jl"
+    for yaml_file in yaml_files)
+
+sourcegen = env.Command(
+    generated_files,
+    "#build/doc/Cantera.tag",
+    ("$python_cmd -m interfaces.sourcegen.src.sourcegen "
+     f"--api=julia --output={Path(Dir('#interfaces/julia').abspath)}")
+)
+env.Depends(sourcegen, [File(ff) for ff in yaml_files])
+env.Depends(sourcegen, env.Glob("#interfaces/sourcegen/src/sourcegen/*.py"))
+env.Depends(sourcegen, env.Glob("#interfaces/sourcegen/src/sourcegen/julia/*.*"))
+
+build(sourcegen)
+
+Return("sourcegen")

interfaces/julia/docs/Project.toml

@@ -0,0 +1,6 @@
+[deps]
+Cantera = "c8cccd67-5bbd-4b73-b352-8d151246ed36"
+Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
+
+[compat]
+Documenter = "1"

interfaces/julia/docs/make.jl

@@ -0,0 +1,32 @@
+# Build the Cantera.jl documentation with Documenter.
+#
+#   julia --project=interfaces/julia/docs interfaces/julia/docs/make.jl
+#
+# The generated HTML is written to `docs/build`, which the Cantera doc build
+# (doc/SConscript) copies into `build/doc/html/julia` so it is deployed
+# alongside the rest of the Cantera documentation. There is intentionally no
+# `deploydocs` call: deployment is handled by the top-level docs workflow.
+#
+# Requires a working libcantera and the generated CLib bindings (see the
+# interface README); `using Cantera` loads the library to introspect docstrings.
+
+using Documenter
+using Cantera
+
+makedocs(
+    sitename = "Cantera.jl",
+    modules = [Cantera],
+    authors = "Cantera Developers",
+    pages = [
+        "Home" => "index.md",
+        "API Reference" => "reference.md",
+    ],
+    format = Documenter.HTML(
+        prettyurls = get(ENV, "CI", "false") == "true",
+        canonical = "https://cantera.org/dev/julia",
+        # The API reference is a single @autodocs page; allow it to exceed the
+        # default 200 KiB cap rather than splitting the generated listing.
+        size_threshold = 512 * 1024,
+    ),
+    warnonly = true,   # the CLib backend is experimental; don't fail on missing refs
+)

interfaces/julia/docs/src/index.md

@@ -0,0 +1,43 @@
+# Cantera.jl
+
+A Julia interface to [Cantera](https://cantera.org) for chemical kinetics,
+thermodynamics, and transport. It links Cantera's native `libcantera` directly
+through the generated CLib API — it is **not** a reimplementation of Cantera and
+has **no** Python dependency.
+
+!!! warning "Experimental"
+    This interface targets Cantera's experimental CLib backend. The API may
+    change between releases.
+
+## Installation
+
+Requires Julia 1.9+ and a compiled `libcantera`. Point the package at the
+library and the mechanism data:
+
+```bash
+export CANTERA_LIBRARY_PATH=/path/to/cantera/lib   # or use a conda env
+export CANTERA_DATA=/path/to/cantera/data          # for gri30.yaml, etc.
+```
+
+The low-level CLib bindings are scaffolded by `scons build`, so only the
+environment needs to be instantiated:
+
+```bash
+julia --project=interfaces/julia -e 'using Pkg; Pkg.instantiate()'
+```
+
+## Quickstart
+
+```julia
+using Cantera
+
+gas = Solution("gri30.yaml")
+set_TPX!(gas, 1000.0, one_atm, "H2:2, O2:1, N2:4")
+net = ReactorNet(IdealGasReactor(gas))
+advance!(net, 1e-3)
+temperature(gas)          # ignited temperature [K]
+```
+
+See the [`examples/`](https://github.com/Cantera/cantera/tree/main/interfaces/julia/examples)
+directory for more runnable usage, and the [API Reference](reference.md) for the
+full list of documented functions.

interfaces/julia/docs/src/reference.md

@@ -0,0 +1,7 @@
+# API Reference
+
+Documentation for the functions and types exported by `Cantera.jl`.
+
+```@autodocs
+Modules = [Cantera]
+```