Sampling Study Tutorial

This example builds a Latin hypercube sampling study with two uniform uncertain variables and the Dakota text_book analysis driver. The Python and C++ versions assemble the same study graph.

Python

The Python version uses configuration keyword arguments. This is usually the most readable form when translating a small freeform input.

from dakota.study import Study, StudyConfig

config = StudyConfig()
config.output.precision = 12
config.output.output_file = "di_construction_demo.out"
config.output.error_file = "di_construction_demo.err"
config.output.write_restart = "di_construction_demo.rst"
config.output.results_output = True
config.output.results_output_file = "di_construction_demo_results"

study = Study(config)

variables = study.variables(
    active={"all": True},
    uniform_uncertain={
        "count": 2,
        "descriptors": ["x1", "x2"],
        "lower_bounds": [0.0, 0.0],
        "upper_bounds": [1.0, 1.0],
    },
)

response = study.responses(
    variables,
    response_type={"response_functions": {"count": 1}},
    descriptors=["f"],
    gradient_type={"no_gradients": True},
    hessian_type={"no_hessians": True},
)

interface = study.interface(
    analysis_drivers={
        "drivers": ["text_book"],
        "interface_type": {
            "fork": {
                "parameters_file": "params.in",
                "results_file": "results.out",
                "file_save": True,
            }
        },
    },
    deactivate={"restart_file": True},
)

model = study.model.simulation(variables, interface, response)

sampling = study.method.sampling(
    model,
    sample_type={"lhs": True},
    samples=10,
    seed=1234,
)

study.run(sampling)

The call to sampling passes its top-level configuration fields as keyword arguments. Dictionaries are still used for nested keyword groups: for example, sample_type={"lhs": True} represents the freeform sample_type lhs choice. The keyword-argument and Pydantic forms for that call are:

from dakota.spec.method import SamplingConfig

sampling = study.method.sampling(
    model,
    sample_type={"lhs": True},
    samples=10,
    seed=1234,
)

sampling = study.method.sampling(
    model,
    config=SamplingConfig(
        sample_type={"lhs": True},
        samples=10,
        seed=1234,
    ),
)

Python with inline callback

The same study can be driven by a Python function defined directly in the script, with no external executable needed. Decorate the function with python_interface() and pass it as the callback keyword argument to Study.interface(). Because the callback supplies the driver, no analysis_drivers configuration is required.

import dakota.interfacing as di
from dakota.study import Study, StudyConfig

@di.python_interface
def text_book(params, results):
    x1, x2 = params["x1"], params["x2"]
    response = results["f"]
    if response.asv.function:
        response.function = (x1 - 1.0) ** 4 + (x2 - 1.0) ** 4
    return results

config = StudyConfig()
config.output.precision = 12
config.output.output_file = "di_construction_demo_python_callback.out"
config.output.error_file = "di_construction_demo_python_callback.err"
config.output.write_restart = "di_construction_demo_python_callback.rst"
config.output.results_output = True
config.output.results_output_file = "di_construction_demo_python_callback_results"

study = Study(config)

variables = study.variables(
    active={"all": True},
    uniform_uncertain={
        "count": 2,
        "descriptors": ["x1", "x2"],
        "lower_bounds": [0.0, 0.0],
        "upper_bounds": [1.0, 1.0],
    },
)

response = study.responses(
    variables,
    response_type={"response_functions": {"count": 1}},
    descriptors=["f"],
    gradient_type={"no_gradients": True},
    hessian_type={"no_hessians": True},
)

interface = study.interface(callback=text_book)

model = study.model.simulation(variables, interface, response)

sampling = study.method.sampling(
    model,
    sample_type={"lhs": True},
    samples=10,
    seed=1234,
)

study.run(sampling)

The python_interface() decorator adapts the function to the dictionary protocol that Interface expects. Inside the decorated function, params is a Parameters object that provides named variable access (params["x1"]), and results is a Results object that holds one Response entry per response descriptor. Each response carries an active-set vector (response.asv.function, response.asv.gradient, response.asv.hessian) that the function should respect before assigning values.

When a callback is provided, interface configuration is not required — Dakota uses built-in defaults. A configuration object or keyword arguments can still be supplied alongside the callback, for example to enable batch evaluation:

interface = study.interface(
    concurrency={"batch": {}},
    callback=text_book,
)

C++

The C++ API accepts JSON configuration fragments and typed study-level output configuration. Dependencies are passed as C++ objects and smart pointers.

using json = nlohmann::json;

int main()
{
  using namespace Dakota;

  const json method_json = {
    {"sample_type", {{"lhs", true}}},
    {"samples", 10},
    {"seed", 1234}
  };

  const json variables_json = {
    {"active", {{"all", true}}},
    {"uniform_uncertain", {
      {"count", 2},
      {"descriptors", {"x1", "x2"}},
      {"lower_bounds", {0.0, 0.0}},
      {"upper_bounds", {1.0, 1.0}}
    }}
  };

  const json responses_json = {
    {"response_type", {{"response_functions", {{"count", 1}}}}},
    {"descriptors", {"f"}},
    {"gradient_type", {{"no_gradients", true}}},
    {"hessian_type", {{"no_hessians", true}}}
  };

  const json interface_json = {
    {"analysis_drivers", {
      {"drivers", {"text_book"}},
      {"interface_type",
        {
          {
            "fork", {
              {"parameters_file", "params.in"},
              {"results_file", "results.out"},
              {"file_save", true}
            }
          }
        }
      },
      {"deactivate", {"restart_file", true}},

    }}
  };

  const json model_json = json::object();

  StudyConfig config;
  config.output.precision = 12;
  config.output.outputFile = "di_construction_demo.out";
  config.output.errorFile = "di_construction_demo.err";
  config.output.writeRestart = "di_construction_demo.rst";
  config.output.resultsOutput = true;
  config.output.resultsOutputFile = "di_construction_demo_results";

  // Study owns the library-mode services used by DI-constructed components.
  Study study(config);

  std::cout << "Constructing DI study components...\n";
  std::cout << "Configured output precision: "
            << study.output_manager()->write_precision() << '\n';
  Variables variables = study.variables(variables_json);
  Response response = study.responses(responses_json, variables);
  auto interface = study.interface(interface_json);
  auto model = study.model().single(
    model_json, variables, interface, response);
  auto sampling = study.method().sampling(method_json, model);

  std::cout << "Running sampling study...\n";
  study.run(sampling);

  const auto& responses = sampling->all_responses();
  std::cout << "Completed DI study.\n";
  std::cout << "Samples evaluated: " << responses.size() << '\n';
  if (!responses.empty()) {
    const auto& first_response = responses.begin()->second;
    if (first_response.num_functions() > 0)
      std::cout << "First response value: "
                << first_response.function_value(0) << '\n';
  }
  return 0;
}

Both examples keep the Study alive through execution. The study owns the runtime services shared by the variables, interface, model, and iterator.

Running the examples

The examples require a Dakota build containing the Study API and the text_book analysis driver. Run them from a writable directory because the configured interface and output settings create files there. For Python, put the build-tree or installed Dakota Python package on PYTHONPATH.