Python API

All public functions below are available as jutuldarcy.<name>. Keyword arguments are converted and forwarded to Julia. Consult the Julia API for the full keyword lists and physical interpretation.

Simulation and conversion

jutuldarcy.simulate

Simulation entry points; KernelAbstractions on CPU is the default.

simulate_data_file(data_file_name, *, convert=False, units=jl.missing, mode='ka', gpu=False, **kwargs)

Simulate a DATA path or parsed deck; gpu=True selects an activated GPU.

simulate_reservoir(*args, convert=False, units=jl.missing, mode='ka', gpu=False, **kwargs)

Simulate a case or (state0, model, dt); optionally return Python results.

setup_reservoir_simulator(*args, mode='ka', gpu=False, **kwargs)

Return (simulator, config). Supports mode='ka_*' and Julia ka_backend objects.

jutuldarcy.conversion

Conversions at the Python/Julia boundary.

to_julia(value, *, symbols=True)

Copy containers to Julia; dict keys become Symbols unless symbols=False.

Matrices retain their shape (phases/components by cells). Indices stay one-based. Existing Julia values, including AD values, pass through.

to_python(value)

Recursively copy Julia dictionaries, tuples and arrays into Python/NumPy.

convert_to_pydict(result, case=None, units=jl.missing)

Return WELLS, FIELD, DAYS and STATES as Python dictionaries/NumPy arrays.

symdict_to_pydict(value)

Convert Symbol keys to strings, keeping the dictionary values as Julia values.

jutuldarcy.parsing

setup_case_from_data_file(*arg, **kwargs)

Setup a JutulDarcy case from a .DATA file. This function is used to set up a case for simulation. It does not run the simulation itself.

Examples: case = jd.setup_case_from_data_file(filename, )

parse_data_file(data_file_name, **kwargs)

Parse a .DATA file and return the parsed data as a Julia dictionary. Examples: pth = test_file_path("SPE1", "SPE1.DATA") res = jd.parse_data_file(pth)

test_file_path(*args)

Get the path to a test file in the GeoEnergyIO package. This may trigger a download if it is the first time the given example file is requested. If a path is returned, the file is available on-disk at that location.

Examples: test_file_path("SPE1", "SPE1.DATA") test_file_path("SPE9", "SPE9.DATA") test_file_path("OLYMPUS_1", "OLYMPUS_1.DATA") test_file_path("NORNE_NOHYST", "NORNE_NOHYST.DATA") test_file_path("EGG", "EGG.DATA")

Models, meshes and properties

jutuldarcy.meshes

CartesianMesh(dims, *args, **kwargs)

Construct a Julia Cartesian mesh from Python dimensions and lengths.

reservoir_mesh(*args, **kwargs)

Construct or extract a reservoir mesh; accepts tuples, grid dicts and cases.

extract_submesh(mesh, cells, **kwargs)

Extract cells specified using Julia's one-based cell indices.

jutuldarcy.reservoir

reservoir_domain(*args, **kwargs)

Construct/extract a domain; property matrices are components by cells.

jutuldarcy.systems

jutuldarcy.model

jutuldarcy.properties

Relative permeability and capillary pressure helpers from JutulDarcy.

set_relative_permeability(model, **kwargs)

Set relperm from SWOF/SGOF NumPy matrices or phase interpolators.

set_capillary_pressure(model, **kwargs)

Set Pc from [saturation, pressure] tables; pressures are in Pa.

Wells, units and cases

jutuldarcy.wells

jutuldarcy.units

si_unit(u)

Convert a unit to SI unit.

jutuldarcy.utils

setup_jutul_case(state0, model, dt, forces=None, parameters=None, **kwargs)

Construct a case; forces and parameters default to the model defaults.

Backends, plotting and gradients

jutuldarcy.backends

Optional Julia GPU packages and simulator execution modes.

activate_cuda()

Add CUDA only if absent, load it, and return CUDA.functional().

activate_amd()

Add AMDGPU only if absent, load it, and return AMDGPU.functional().

remove_cuda()

Remove the CUDA requirement. Restart Python to unload Julia modules.

remove_amd()

Remove the AMDGPU requirement. Restart Python to unload Julia modules.

available_backends()

Return activated, functional GPUs, in CUDA then AMD order.

jutuldarcy.plotting

Makie plots return their figure immediately; block=True waits in scripts.

activate_plotting(backend='GLMakie')

Load an installed Makie backend. CairoMakie supports headless rendering.

plot_reservoir(*args, **kwargs)

Return the Makie figure for a case/model/domain and optional states/result.

With CairoMakie, gui=False and force_glmakie=False are the defaults. Python state dictionaries/lists are converted to native Julia containers.

plot_field_measurables(*args, **kwargs)

Compatibility alias for JutulDarcy's plot_reservoir_measurables.

make_interactive()

Integrate Julia's event loop for non-blocking GLMakie windows.

plot_async(function, *args, **kwargs)

Compatibility entry point; return the figure without owning an asyncio loop.

jutuldarcy.gradients

Adjoint sensitivities and optimization with Julia or Python objectives.

reservoir_sensitivities(case, *args, convert=False, **kwargs)

Compute adjoint gradients for objective(model, state, dt, step, forces).

Pass (case, objective) to simulate first, returning (result, gradients), or (case, result, objective) to reuse a forward result. convert=True copies the gradient DataDomain to a dict of NumPy arrays. Keep AD values in objectives: use Julia arithmetic/reductions and never cast an objective to float.

solve_adjoint_sensitivities(case, result, objective, *, convert=False, **kwargs)

Return the lower-level parameter adjoint dictionary.

optimization_config(model, parameters=None, *args, **kwargs)

Build a Julia optimization config for a case, or model and parameters.

setup_reservoir_parameter_optimization(case, objective, *args, **kwargs)

Return Julia optimization callbacks/configuration (usable from SciPy).

evaluate_objective(objective, model, states, dt=None, forces=None, **kwargs)

Evaluate an objective with (model, states, dt, forces) or (case, result).

Passing a ReservoirSimResult includes wells and saved internal timesteps, matching the objective used by the adjoint. Its .states field contains only reservoir states and is intended for plotting.