Wrapper class for configuring a simulation. More...

Inheritance diagram for dqcsim::wrap::SimulationConfiguration:

Public Member Functions
	SimulationConfiguration (HandleIndex handle) noexcept
	Wraps the given simulation configuration handle. More...

	SimulationConfiguration ()
	Creates a new simulation configuration.

	SimulationConfiguration (const SimulationConfiguration &)=delete

void	operator= (const SimulationConfiguration &)=delete

	SimulationConfiguration (SimulationConfiguration &&)=default
	Default move constructor.

SimulationConfiguration &	operator= (SimulationConfiguration &&)=default
	Default move assignment.

void	add_plugin (PluginConfiguration &&plugin)
	Appends a plugin to a simulation configuration. More...

SimulationConfiguration &&	with_plugin (PluginConfiguration &&plugin)
	Appends a plugin to a simulation configuration (builder pattern). More...

void	set_seed (uint64_t seed)
	Configures the random seed that the simulation should use. More...

SimulationConfiguration &&	with_seed (uint64_t seed)
	Configures the random seed that the simulation should use (builder pattern). More...

uint64_t	get_seed () const noexcept
	Returns the configured random seed. More...

void	set_reproduction_style (PathStyle style)
	Sets the path style used when writing reproduction files. More...

SimulationConfiguration &&	with_reproduction_style (PathStyle style)
	Sets the path style used when writing reproduction files (builder pattern). More...

PathStyle	get_reproduction_style () const
	Returns the path style used when writing reproduction files. More...

void	disable_reproduction ()
	Disables the reproduction logging system. More...

SimulationConfiguration &&	without_reproduction ()
	Disables the reproduction logging system (builder pattern). More...

void	set_dqcsim_verbosity (Loglevel level)
	Configures the logging verbosity for DQCsim's own messages. More...

SimulationConfiguration &&	with_dqcsim_verbosity (Loglevel level)
	Configures the logging verbosity for DQCsim's own messages (builder pattern). More...

Loglevel	get_dqcsim_verbosity () const
	Returns the configured verbosity for DQCsim's own messages. More...

void	set_stderr_verbosity (Loglevel level)
	Configures the stderr sink verbosity for a simulation. More...

SimulationConfiguration &&	with_stderr_verbosity (Loglevel level)
	Configures the stderr sink verbosity for a simulation (builder pattern). More...

Loglevel	get_stderr_verbosity () const
	Returns the configured stderr sink verbosity for a simulation. More...

void	log_tee (Loglevel verbosity, const std::string &filename)
	Configures DQCsim to also output its log messages to a file. More...

SimulationConfiguration &&	with_log_tee (Loglevel verbosity, const std::string &filename)
	Configures DQCsim to also output its log messages to a file (builder pattern). More...

void	set_log_callback (Loglevel verbosity, const callback::Log &data)
	Configures DQCsim to also output its log messages to callback function. More...

void	set_log_callback (Loglevel verbosity, callback::Log &&data)
	Configures DQCsim to also output its log messages to callback function. More...

template<typename... Args>
void	set_log_callback (Loglevel verbosity, Args... args)
	Configures DQCsim to also output its log messages to callback function. More...

SimulationConfiguration &&	with_log_callback (Loglevel verbosity, const callback::Log &data)
	Configures DQCsim to also output its log messages to callback function (builder pattern). More...

SimulationConfiguration &&	with_log_callback (Loglevel verbosity, callback::Log &&data)
	Configures DQCsim to also output its log messages to callback function (builder pattern). More...

template<typename... Args>
SimulationConfiguration &&	with_log_callback (Loglevel verbosity, Args... args)
	Configures DQCsim to also output its log messages to callback function (builder pattern). More...

Simulation	build ()
	Constructs the DQCsim simulation from this configuration object. More...

Simulation	run ()
	Constructs the DQCsim simulation from this configuration object, and runs a program on the simulated accelerator without an argument. More...

Simulation	run (ArbData &&data)
	Constructs the DQCsim simulation from this configuration object, and runs a program on the simulated accelerator with the given `ArbData` argument (passed by move). More...

Simulation	run (const ArbData &data)
	Constructs the DQCsim simulation from this configuration object, and runs a program on the simulated accelerator with the given `ArbData` argument (passed by copy). More...

Public Member Functions inherited from dqcsim::wrap::Handle
	Handle () noexcept
	Constructs an empty wrapper. More...

	Handle (HandleIndex handle) noexcept
	Wraps the given raw handle. More...

virtual	~Handle () noexcept
	Delete the handle and its wrapper.

void	free ()
	Explicitly delete the handle, allowing errors to be caught. More...

bool	is_valid () const noexcept
	Returns whether this wrapper (still) contains a valid handle. More...

HandleIndex	get_handle () const noexcept
	Returns the raw handle without relinquishing ownership. More...

HandleIndex	take_handle () noexcept
	Returns the raw handle and relinquishes ownership. More...

	Handle (const Handle &)=delete

void	operator= (const Handle &)=delete

	Handle (Handle &&src)
	Move constructor; simply moves ownership of the handle from the source object to the constructed object. More...

Handle &	operator= (Handle &&src)
	Move constructor; simply moves ownership of the handle from the source object to the assignment target. More...

std::string	dump () const
	Returns a string containing a debug dump of the handle. More...

HandleType	type () const
	Returns the type of this handle. More...

Additional Inherited Members
Protected Attributes inherited from dqcsim::wrap::Handle
HandleIndex	handle
	The wrapped handle.

Detailed Description

Wrapper class for configuring a simulation.

Definition at line 9866 of file dqcsim.

Constructor & Destructor Documentation

◆ SimulationConfiguration()

dqcsim::wrap::SimulationConfiguration::SimulationConfiguration ( HandleIndex handle )

inlinenoexcept

Wraps the given simulation configuration handle.

Note: This constructor does not verify that the handle is actually valid.

Parameters

handle The raw handle to wrap.

Definition at line 9877 of file dqcsim.

Member Function Documentation

◆ add_plugin()

void dqcsim::wrap::SimulationConfiguration::add_plugin ( PluginConfiguration && plugin )

inline

Appends a plugin to a simulation configuration.

Frontend and backend plugins will automatically be inserted at the front and back of the pipeline when the simulation is created. Operators are inserted in front to back order. This function does not provide safeguards against multiple frontends/backends; such errors will only be reported when the simulation is started.

Note: It is not possible to observe or mutate a plugin configuration once it has been added to a simulator configuration handle. If you want to do this for some reason, you should maintain your own data structures, and only build the DQCsim structures from them when you're done.

Parameters

plugin The plugin configuration object. If not constructed in-place, this must be std::move()d into this method.

Exceptions

std::runtime_error When the simulation or plugin configuration handle is invalid for some reason.

Definition at line 9920 of file dqcsim.

◆ with_plugin()

SimulationConfiguration&& dqcsim::wrap::SimulationConfiguration::with_plugin ( PluginConfiguration && plugin )

inline

Appends a plugin to a simulation configuration (builder pattern).

See also: add_plugin()

Parameters

plugin The plugin configuration object. If not constructed in-place, this must be std::move()d into this method.

Returns: &self, to continue building.

Exceptions

std::runtime_error When the simulation or plugin configuration handle is invalid for some reason.

Definition at line 9935 of file dqcsim.

◆ set_seed()

void dqcsim::wrap::SimulationConfiguration::set_seed ( uint64_t seed )

inline

Configures the random seed that the simulation should use.

Note that the seed is randomized by default.

Parameters

seed	The random seed to use.

Exceptions

std::runtime_error When the simulation configuration handle is invalid for some reason.

Definition at line 9949 of file dqcsim.

◆ with_seed()

SimulationConfiguration&& dqcsim::wrap::SimulationConfiguration::with_seed ( uint64_t seed )

inline

Configures the random seed that the simulation should use (builder pattern).

Note that the seed is randomized by default.

Parameters

seed	The random seed to use.

Returns: &self, to continue building.

Exceptions

std::runtime_error When the simulation configuration handle is invalid for some reason.

Definition at line 9964 of file dqcsim.

◆ get_seed()

uint64_t dqcsim::wrap::SimulationConfiguration::get_seed ( ) const

inlinenoexcept

Returns the configured random seed.

Returns: The configured random seed.

Note: Due to the C interface layer underneath, this function cannot distinguish between seed 0 and an exception. Therefore, it is noexcept.

Definition at line 9978 of file dqcsim.

◆ set_reproduction_style()

void dqcsim::wrap::SimulationConfiguration::set_reproduction_style ( PathStyle style )

inline

Sets the path style used when writing reproduction files.

By default, the generated reproduction file will specify the plugin executable and script paths as they were generated or specified. However, depending on how you intend to reproduce the simulation later, you may want purely relative or purely absolute paths instead. This function sets the style used.

Parameters

style The path style to use.

Exceptions

std::runtime_error When the simulation configuration handle is invalid for some reason.

Definition at line 9995 of file dqcsim.

◆ with_reproduction_style()

SimulationConfiguration&& dqcsim::wrap::SimulationConfiguration::with_reproduction_style ( PathStyle style )

inline

Sets the path style used when writing reproduction files (builder pattern).

By default, the generated reproduction file will specify the plugin executable and script paths as they were generated or specified. However, depending on how you intend to reproduce the simulation later, you may want purely relative or purely absolute paths instead. This function sets the style used.

Parameters

style The path style to use.

Returns: &self, to continue building.

Exceptions

std::runtime_error When the simulation configuration handle is invalid for some reason.

Definition at line 10014 of file dqcsim.

◆ get_reproduction_style()

PathStyle dqcsim::wrap::SimulationConfiguration::get_reproduction_style ( ) const

inline

Returns the path style used when writing reproduction files.

Returns: The path style used when writing reproduction files.

Exceptions

std::runtime_error When the simulation configuration handle is invalid for some reason.

Definition at line 10026 of file dqcsim.

◆ disable_reproduction()

void dqcsim::wrap::SimulationConfiguration::disable_reproduction ( )

inline

Disables the reproduction logging system.

Calling this will disable the warnings printed when a simulation that cannot be reproduced is constructed.

Exceptions

std::runtime_error When the simulation configuration handle is invalid for some reason.

Definition at line 10039 of file dqcsim.

◆ without_reproduction()

SimulationConfiguration&& dqcsim::wrap::SimulationConfiguration::without_reproduction ( )

inline

Disables the reproduction logging system (builder pattern).

Calling this will disable the warnings printed when a simulation that cannot be reproduced is constructed.

Returns: &self, to continue building.

Exceptions

std::runtime_error When the simulation configuration handle is invalid for some reason.

Definition at line 10053 of file dqcsim.

◆ set_dqcsim_verbosity()

void dqcsim::wrap::SimulationConfiguration::set_dqcsim_verbosity ( Loglevel level )

inline

Configures the logging verbosity for DQCsim's own messages.

Parameters

level The verbosity level for DQCsim's own messages.

Exceptions

std::runtime_error When the simulation configuration handle is invalid for some reason.

Definition at line 10065 of file dqcsim.

◆ with_dqcsim_verbosity()

SimulationConfiguration&& dqcsim::wrap::SimulationConfiguration::with_dqcsim_verbosity ( Loglevel level )

inline

Configures the logging verbosity for DQCsim's own messages (builder pattern).

Parameters

level The verbosity level for DQCsim's own messages.

Returns: &self, to continue building.

Exceptions

std::runtime_error When the simulation configuration handle is invalid for some reason.

Definition at line 10078 of file dqcsim.

◆ get_dqcsim_verbosity()

Loglevel dqcsim::wrap::SimulationConfiguration::get_dqcsim_verbosity ( ) const

inline

Returns the configured verbosity for DQCsim's own messages.

Returns: The configured verbosity for DQCsim's own messages.

Exceptions

std::runtime_error When the simulation configuration handle is invalid for some reason.

Definition at line 10090 of file dqcsim.

◆ set_stderr_verbosity()

void dqcsim::wrap::SimulationConfiguration::set_stderr_verbosity ( Loglevel level )

inline

Configures the stderr sink verbosity for a simulation.

That is, the minimum loglevel that a messages needs to have for it to be printed to stderr.

Parameters

level The verbosity level to set.

Exceptions

std::runtime_error When the simulation configuration handle is invalid for some reason.

Definition at line 10104 of file dqcsim.

◆ with_stderr_verbosity()

SimulationConfiguration&& dqcsim::wrap::SimulationConfiguration::with_stderr_verbosity ( Loglevel level )

inline

Configures the stderr sink verbosity for a simulation (builder pattern).

That is, the minimum loglevel that a messages needs to have for it to be printed to stderr.

Parameters

level The verbosity level to set.

Returns: &self, to continue building.

Exceptions

std::runtime_error When the simulation configuration handle is invalid for some reason.

Definition at line 10119 of file dqcsim.

◆ get_stderr_verbosity()

Loglevel dqcsim::wrap::SimulationConfiguration::get_stderr_verbosity ( ) const

inline

Returns the configured stderr sink verbosity for a simulation.

That is, the minimum loglevel that a messages needs to have for it to be printed to stderr.

Returns: The configured stderr sink verbosity for a simulation.

Exceptions

std::runtime_error When the simulation configuration handle is invalid for some reason.

Definition at line 10134 of file dqcsim.

◆ log_tee()

void dqcsim::wrap::SimulationConfiguration::log_tee	(	Loglevel	verbosity,
		const std::string &	filename
	)

inline

Configures DQCsim to also output its log messages to a file.

Parameters

verbosity	The logging verbosity for the tee file.
filename	The name of the file to log to.

Exceptions

std::runtime_error When the simulation configuration handle is invalid for some reason.

Definition at line 10146 of file dqcsim.

◆ with_log_tee()

SimulationConfiguration&& dqcsim::wrap::SimulationConfiguration::with_log_tee	(	Loglevel	verbosity,
		const std::string &	filename
	)

inline

Configures DQCsim to also output its log messages to a file (builder pattern).

Parameters

verbosity	The logging verbosity for the tee file.
filename	The name of the file to log to.

Returns: &self, to continue building.

Exceptions

std::runtime_error When the simulation configuration handle is invalid for some reason.

Definition at line 10160 of file dqcsim.

◆ set_log_callback() [1/3]

void dqcsim::wrap::SimulationConfiguration::set_log_callback	(	Loglevel	verbosity,
		const callback::Log &	data
	)

inline

Configures DQCsim to also output its log messages to callback function.

verbosity specifies the minimum importance of a message required for the callback to be called. data is the callback information object, taken by copy by this function. Refer to callback::Log for more information.

Note: This callback may be called from a thread spawned by the simulator. Calling any API calls from the callback is therefore undefined behavior!

Parameters

verbosity	The minimum loglevel needed for a log message for the callback to be called.
data	The wrapper object for the log callback.

Exceptions

std::runtime_error When the simulation configuration handle is invalid for some reason.

Definition at line 10220 of file dqcsim.

◆ set_log_callback() [2/3]

void dqcsim::wrap::SimulationConfiguration::set_log_callback	(	Loglevel	verbosity,
		callback::Log &&	data
	)

inline

Configures DQCsim to also output its log messages to callback function.

verbosity specifies the minimum importance of a message required for the callback to be called. data is the callback information object, taken by move by this function. Refer to callback::Log for more information.

Note: This callback may be called from a thread spawned by the simulator. Calling any API calls from the callback is therefore undefined behavior!

Parameters

verbosity	The minimum loglevel needed for a log message for the callback to be called.
data	The wrapper object for the log callback.

Exceptions

std::runtime_error When the simulation configuration handle is invalid for some reason.

Definition at line 10242 of file dqcsim.

◆ set_log_callback() [3/3]

template<typename... Args>

void dqcsim::wrap::SimulationConfiguration::set_log_callback	(	Loglevel	verbosity,
		Args...	args
	)

inline

Configures DQCsim to also output its log messages to callback function.

verbosity specifies the minimum importance of a message required for the callback to be called. The callback information object is constructed in place from the remaining arguments. Refer to callback::Log for more information.

Note: This callback may be called from a thread spawned by the simulator. Calling any API calls from the callback is therefore undefined behavior!

Parameters

verbosity	The minimum loglevel needed for a log message for the callback to be called.
args	Any valid argument list for constructing `callback::Log`.

Exceptions

std::runtime_error When the simulation configuration handle is invalid for some reason.

Definition at line 10265 of file dqcsim.

◆ with_log_callback() [1/3]

SimulationConfiguration&& dqcsim::wrap::SimulationConfiguration::with_log_callback	(	Loglevel	verbosity,
		const callback::Log &	data
	)

inline

Configures DQCsim to also output its log messages to callback function (builder pattern).

verbosity specifies the minimum importance of a message required for the callback to be called. data is the callback information object, taken by copy by this function. Refer to callback::Log for more information.

Note: This callback may be called from a thread spawned by the simulator. Calling any API calls from the callback is therefore undefined behavior!

Parameters

verbosity	The minimum loglevel needed for a log message for the callback to be called.
data	The wrapper object for the log callback.

Returns: &self, to continue building.

Exceptions

std::runtime_error When the simulation configuration handle is invalid for some reason.

Definition at line 10289 of file dqcsim.

◆ with_log_callback() [2/3]

SimulationConfiguration&& dqcsim::wrap::SimulationConfiguration::with_log_callback	(	Loglevel	verbosity,
		callback::Log &&	data
	)

inline

Configures DQCsim to also output its log messages to callback function (builder pattern).

verbosity specifies the minimum importance of a message required for the callback to be called. data is the callback information object, taken by move by this function. Refer to callback::Log for more information.

Note: This callback may be called from a thread spawned by the simulator. Calling any API calls from the callback is therefore undefined behavior!

Parameters

verbosity	The minimum loglevel needed for a log message for the callback to be called.
data	The wrapper object for the log callback.

Returns: &self, to continue building.

Exceptions

std::runtime_error When the simulation configuration handle is invalid for some reason.

Definition at line 10314 of file dqcsim.

◆ with_log_callback() [3/3]

template<typename... Args>

SimulationConfiguration&& dqcsim::wrap::SimulationConfiguration::with_log_callback	(	Loglevel	verbosity,
		Args...	args
	)

inline

Configures DQCsim to also output its log messages to callback function (builder pattern).

verbosity specifies the minimum importance of a message required for the callback to be called. The callback information object is constructed in place from the remaining arguments. Refer to callback::Log for more information.

Note: This callback may be called from a thread spawned by the simulator. Calling any API calls from the callback is therefore undefined behavior!

Parameters

verbosity	The minimum loglevel needed for a log message for the callback to be called.
args	Any valid argument list for constructing `callback::Log`.

Returns: &self, to continue building.

Exceptions

std::runtime_error When the simulation configuration handle is invalid for some reason.

Definition at line 10340 of file dqcsim.

◆ build()

Simulation dqcsim::wrap::SimulationConfiguration::build ( )

inline

Constructs the DQCsim simulation from this configuration object.

Note: The builder object can only be used once. After calling build(), the behavior of every other member function is undefined.; It is currently not possible to have more than one simulation handle within a single thread at the same time. This has to do with DQCsim's log system, which uses thread-local storage to determine where log messages should go. If you want to run multiple simulations in parallel, you'll have to run them from different threads.

Returns: The constructed simulation object.

Exceptions

std::runtime_error When the simulation configuration handle is invalid for some reason, or initializing the simulation fails.

Definition at line 10361 of file dqcsim.

◆ run() [1/3]

Simulation dqcsim::wrap::SimulationConfiguration::run ( )

inline

Constructs the DQCsim simulation from this configuration object, and runs a program on the simulated accelerator without an argument.

This is simply a shorthand for build() followed by Simulation::run(). The accelerator return value is discarded in favor of returning the simulation object, which you can then call write_reproduction_file() on.

Returns: The constructed simulation object.

Exceptions

std::runtime_error When the simulation configuration handle is invalid for some reason, or running the simulation fails.

Definition at line 10378 of file dqcsim.

◆ run() [2/3]

Simulation dqcsim::wrap::SimulationConfiguration::run ( ArbData && data )

inline

Constructs the DQCsim simulation from this configuration object, and runs a program on the simulated accelerator with the given ArbData argument (passed by move).

This is simply a shorthand for build() followed by Simulation::run(). The accelerator return value is discarded in favor of returning the simulation object, which you can then call write_reproduction_file() on.

Parameters

data	The `ArbData` object to pass to the frontend's `run` callback.

Returns: The constructed simulation object.

Exceptions

std::runtime_error When the simulation configuration handle is invalid for some reason, or running the simulation fails.

Definition at line 10400 of file dqcsim.

◆ run() [3/3]

Simulation dqcsim::wrap::SimulationConfiguration::run ( const ArbData & data )

inline

Constructs the DQCsim simulation from this configuration object, and runs a program on the simulated accelerator with the given ArbData argument (passed by copy).

This is simply a shorthand for build() followed by Simulation::run(). The accelerator return value is discarded in favor of returning the simulation object, which you can then call write_reproduction_file() on.

Parameters

data	The `ArbData` object to pass to the frontend's `run` callback.

Returns: The constructed simulation object.

Exceptions

std::runtime_error When the simulation configuration handle is invalid for some reason, or running the simulation fails.

Definition at line 10422 of file dqcsim.

The documentation for this class was generated from the following file:

dqcsim

Public Member Functions

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ SimulationConfiguration()

Member Function Documentation

◆ add_plugin()

◆ with_plugin()

◆ set_seed()

◆ with_seed()

◆ get_seed()

◆ set_reproduction_style()

◆ with_reproduction_style()

◆ get_reproduction_style()

◆ disable_reproduction()

◆ without_reproduction()

◆ set_dqcsim_verbosity()

◆ with_dqcsim_verbosity()

◆ get_dqcsim_verbosity()

◆ set_stderr_verbosity()

◆ with_stderr_verbosity()

◆ get_stderr_verbosity()

◆ log_tee()

◆ with_log_tee()

◆ set_log_callback() [1/3]

◆ set_log_callback() [2/3]

◆ set_log_callback() [3/3]

◆ with_log_callback() [1/3]

◆ with_log_callback() [2/3]

◆ with_log_callback() [3/3]

◆ build()

◆ run() [1/3]

◆ run() [2/3]

◆ run() [3/3]