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.

