Personality generator: draws traits from a weighted catalogue, shaped by Big Five axes, conflicts and synergies. More...

#include <traitgen.hpp>

Public Types
enum class	table : std::uint8_t { traits , axes , loadings , relations }
	The data tables. More...

Public Member Functions
	trtg ()=default
	Default constructor — creates an empty generator with no data.

	trtg (const trtg &)=delete
	Not copyable.

trtg &	operator= (const trtg &)=delete
	Not copyable.

	trtg (trtg &&) noexcept=default
	Movable.

trtg &	operator= (trtg &&) noexcept=default
	Movable.

	~trtg ()=default
	Destructor.

personality	get_personality (const trait_request &request)
	Generate a random personality as requested. Use trait_request{} for three traits without constraints.

personality	get_personality (const trait_request &request, std::uint64_t call_seed) const
	Generate a deterministic personality as requested.

std::vector< personality >	get_personality_batch (const trait_request &request, const core::batch_options &options)
	Generate a batch of personality results from a seed drawn like get_personality() draws its own.

std::vector< personality >	get_personality_batch (const trait_request &request, const core::batch_options &options, std::uint64_t batch_seed) const
	Generate a batch of personality results, deterministically.

template<typename Sink >
void	for_each_personality (const trait_request &request, const core::batch_options &options, std::uint64_t batch_seed, Sink &&sink) const
	Stream a batch of personality results to a sink without holding the whole batch.

template<typename Sink >
void	for_each_personality (const trait_request &request, const core::batch_options &options, Sink &&sink)
	Stream a batch of personality results with a batch seed drawn like get_personality() draws its own.

bool	has_data () const
	Check whether any data has been loaded.

std::size_t	trait_count () const
	Return the number of loaded traits.

std::size_t	axis_count () const
	Return the number of loaded axes.

bool	has_trait (std::string_view key) const
	Whether a trait is loaded.

const std::vector< std::string > &	unresolved () const
	Loadings and relations that name a trait or axis that is not loaded. They are ignored, so removing a trait needs no other change; this lists them to catch misspelt names.

void	load (const std::filesystem::path &dir)
	Load a resource directory, replacing all data and layers loaded before.

bool	load (dataset tier)
	Load a dataset tier, replacing all data and layers loaded before.

void	extend (const std::filesystem::path &path, core::layer_mode mode=core::layer_mode::override)
	Add data layers from a directory or a file.

const core::layer_info &	extend (table which, core::tsv_document doc, core::layer_mode mode=core::layer_mode::override)
	Add a data layer to one table.

const core::layer_info &	extend_from_string (table which, std::string_view text, std::string source, core::layer_mode mode=core::layer_mode::override)
	Add a data layer to one table from TSV text (for example from a WebAssembly host).

const std::vector< core::layer_info > &	layers (table which) const
	The layers in effect for one table, in order.

std::uint64_t	data_hash () const
	Hash of the loaded data (all four tables), recorded in each result's signature().

Static Public Member Functions
static trtg &	instance ()
	Access the global singleton instance.

Detailed Description

Personality generator: draws traits from a weighted catalogue, shaped by Big Five axes, conflicts and synergies.

The generation pipeline, each step drawing from its own stream split from the call seed:

Each axis draws a base value from normal(mean, sd) (stream "axis:<key>"; an axis with sd 0 takes its mean).
Each trait's weight is multiplied by its affinity, exp(sum of loading * standardised base value), so a person high in an axis is likelier to have the traits that load on it.
Included traits are taken; then traits are drawn one at a time (stream "traits"), skipping traits already chosen, excluded, conflicting with a chosen trait or in a chosen trait's group, and multiplying weights by the synergy factors of the chosen traits.
Each axis value is its base plus the loadings of the chosen traits.

The catalogue is four tables (see table), extended by layers. Output is identical on every compiler and platform (dasmig-core).

Can be used as a singleton via instance() or constructed independently.

Thread safety: Each instance is independent. Concurrent calls to get_personality() on the same instance require external synchronisation.

Definition at line 230 of file traitgen.hpp.

Member Enumeration Documentation

◆ table

enum class dasmig::trtg::table : std::uint8_t

strong

The data tables.

Enumerator
traits	`traits.tsv`: key `trait`; label, weight, group, tags.
axes	`axes.tsv`: key `axis`; label, mean, sd.
loadings	`loadings.tsv`: key `trait` and `axis`; loading.
relations	`relations.tsv`: key `trait` and `other`; relation, factor.

Definition at line 234 of file traitgen.hpp.

Member Function Documentation

◆ axis_count()

std::size_t dasmig::trtg::axis_count ( ) const

inline

Return the number of loaded axes.

Returns: The count.

Definition at line 379 of file traitgen.hpp.

◆ data_hash()

std::uint64_t dasmig::trtg::data_hash ( ) const

inline

Hash of the loaded data (all four tables), recorded in each result's signature().

Returns: The hash; 0 when nothing is loaded.

Definition at line 520 of file traitgen.hpp.

◆ extend() [1/2]

void dasmig::trtg::extend	(	const std::filesystem::path &	path,
		core::layer_mode	mode = `core::layer_mode::override`
	)

inline

Add data layers from a directory or a file.

A directory may hold any of traits.tsv, axes.tsv, loadings.tsv and relations.tsv; all are applied together or, if any fails, none. A file must have one of those names.

Parameters

path	Directory or file.
mode	How the layers combine with the data loaded before.

Exceptions

core::tsv_error	If a file cannot be read or a row is invalid; the data is then unchanged.
std::invalid_argument	If `path` is a file with another name.

Definition at line 460 of file traitgen.hpp.

◆ extend() [2/2]

const core::layer_info & dasmig::trtg::extend	(	table	which,
		core::tsv_document	doc,
		core::layer_mode	mode = `core::layer_mode::override`
	)

inline

Add a data layer to one table.

Parameters

which	The table.
doc	TSV with that table's columns.
mode	How the layer combines with the data loaded before.

Returns: What the layer did.

Exceptions

core::tsv_error If a row is invalid; the data is unchanged.

Definition at line 486 of file traitgen.hpp.

◆ extend_from_string()

const core::layer_info & dasmig::trtg::extend_from_string	(	table	which,
		std::string_view	text,
		std::string	source,
		core::layer_mode	mode = `core::layer_mode::override`
	)

inline

Add a data layer to one table from TSV text (for example from a WebAssembly host).

Parameters

which	The table.
text	TSV with that table's columns.
source	Name used in errors.
mode	How the layer combines with the data loaded before.

Returns: What the layer did.

Exceptions

core::tsv_error If a row is invalid; the data is unchanged.

Definition at line 503 of file traitgen.hpp.

◆ for_each_personality() [1/2]

template<typename Sink >

void dasmig::trtg::for_each_personality	(	const trait_request &	request,
		const core::batch_options &	options,
		Sink &&	sink
	)

inline

Stream a batch of personality results with a batch seed drawn like get_personality() draws its own.

Template Parameters

Sink	Callable taking `(std::uint64_t, personality&)`.

Parameters

request	What every item is generated from.
options	Count, first index, threads and uniqueness.
sink	Receives the items.

Definition at line 360 of file traitgen.hpp.

◆ for_each_personality() [2/2]

template<typename Sink >

void dasmig::trtg::for_each_personality	(	const trait_request &	request,
		const core::batch_options &	options,
		std::uint64_t	batch_seed,
		Sink &&	sink
	)		const

inline

Stream a batch of personality results to a sink without holding the whole batch.

Generates the same items as get_personality_batch() and calls sink(index, item) in index order on the calling thread; index includes options.first.

Template Parameters

Sink	Callable taking `(std::uint64_t, personality&)`; for example core::jsonl_writer or core::csv_writer.

Parameters

request	What every item is generated from.
options	Count, first index, threads and uniqueness.
batch_seed	Seed of the whole batch.
sink	Receives the items.

Definition at line 345 of file traitgen.hpp.

◆ get_personality() [1/2]

personality dasmig::trtg::get_personality ( const trait_request & request )

inline

Generate a random personality as requested. Use trait_request{} for three traits without constraints.

Parameters

request Count, and traits to include or leave out.

Returns: The personality.

Exceptions

std::runtime_error	If no data has been loaded.
std::invalid_argument	If an included trait is unknown, repeated, excluded or in conflict with another included trait, or more traits are included than requested.

Definition at line 273 of file traitgen.hpp.

◆ get_personality() [2/2]

personality dasmig::trtg::get_personality	(	const trait_request &	request,
		std::uint64_t	call_seed
	)		const

inline

Generate a deterministic personality as requested.

Parameters

request	Count, and traits to include or leave out.
call_seed	Seed; the same seed, request and data give the same result.

Returns: The personality.

Exceptions

std::runtime_error	If no data has been loaded.
std::invalid_argument	As get_personality(const trait_request&).

Definition at line 285 of file traitgen.hpp.

◆ get_personality_batch() [1/2]

std::vector< personality > dasmig::trtg::get_personality_batch	(	const trait_request &	request,
		const core::batch_options &	options
	)

inline

Generate a batch of personality results from a seed drawn like get_personality() draws its own.

Item i is get_personality(request, core::item_seed(batch_seed, options.first + i)) for the drawn batch seed; see the seeded overload.

Parameters

request	What every item is generated from.
options	Count, first index, threads and uniqueness.

Returns: The results, in index order.

Definition at line 302 of file traitgen.hpp.

◆ get_personality_batch() [2/2]

std::vector< personality > dasmig::trtg::get_personality_batch	(	const trait_request &	request,
		const core::batch_options &	options,
		std::uint64_t	batch_seed
	)		const

inline

Generate a batch of personality results, deterministically.

Item i is exactly get_personality(request, core::item_seed(batch_seed, options.first + i)), so an item replays on its own, a range can be generated directly, two batches that follow each other equal one, and the output does not depend on options.threads.

Parameters

request	What every item is generated from.
options	Count, first index, threads and uniqueness (see core::unique_rule; the rule must be made for `personality`).
batch_seed	Seed of the whole batch.

Returns: The results, in index order.

Exceptions

std::invalid_argument	If the request or options are invalid.
std::runtime_error	If no data has been loaded, or a unique batch runs out of attempts.

Definition at line 323 of file traitgen.hpp.

◆ has_data()

bool dasmig::trtg::has_data ( ) const

inline

Check whether any data has been loaded.

Returns: True when at least one trait is loaded.

Definition at line 371 of file traitgen.hpp.

◆ has_trait()

bool dasmig::trtg::has_trait ( std::string_view key ) const

inline

Whether a trait is loaded.

Parameters

key	Trait key.

Returns: True when loaded.

Definition at line 384 of file traitgen.hpp.

◆ instance()

static trtg & dasmig::trtg::instance ( )

inlinestatic

Access the global singleton instance.

Loads the lite tier (or full if lite is missing) on first access, from compiled-in data or an auto-probed resources/.

Returns: The singleton.

Definition at line 257 of file traitgen.hpp.

◆ layers()

const std::vector< core::layer_info > & dasmig::trtg::layers ( table which ) const

inline

The layers in effect for one table, in order.

Parameters

which The table.

Returns: The layer records.

Definition at line 512 of file traitgen.hpp.

◆ load() [1/2]

void dasmig::trtg::load ( const std::filesystem::path & dir )

inline

Load a resource directory, replacing all data and layers loaded before.

The directory must contain traits.tsv; axes.tsv, loadings.tsv and relations.tsv are read when present (a missing one leaves its table empty). A path without traits.tsv is ignored.

Parameters

dir	Directory such as `resources/lite`.

Exceptions

core::tsv_error If a file is malformed; the data is then unchanged.

Definition at line 411 of file traitgen.hpp.

◆ load() [2/2]

bool dasmig::trtg::load ( dataset tier )

inline

Load a dataset tier, replacing all data and layers loaded before.

Uses the compiled-in copy when the library is built with DASMIG_TRAIT_EMBED, otherwise searches resources/, ../resources, trait-generator/resources and ../trait-generator/resources.

Parameters

tier The tier.

Returns: False when the tier was not found.

Exceptions

core::tsv_error If a file is malformed.

Definition at line 433 of file traitgen.hpp.

◆ trait_count()

std::size_t dasmig::trtg::trait_count ( ) const

inline

Return the number of loaded traits.

Returns: The count.

Definition at line 375 of file traitgen.hpp.

◆ unresolved()

const std::vector< std::string > & dasmig::trtg::unresolved ( ) const

inline

Loadings and relations that name a trait or axis that is not loaded. They are ignored, so removing a trait needs no other change; this lists them to catch misspelt names.

Returns: One description per ignored row, such as ‘loadings.tsv:12: unknown axis 'opennes’`.

Definition at line 394 of file traitgen.hpp.

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

dasmig/traitgen.hpp

Public Types

Public Member Functions

Static Public Member Functions

Detailed Description

Member Enumeration Documentation

◆ table

Member Function Documentation

◆ axis_count()

◆ data_hash()

◆ extend() [1/2]

◆ extend() [2/2]

◆ extend_from_string()

◆ for_each_personality() [1/2]

◆ for_each_personality() [2/2]

◆ get_personality() [1/2]

◆ get_personality() [2/2]

◆ get_personality_batch() [1/2]

◆ get_personality_batch() [2/2]

◆ has_data()

◆ has_trait()

◆ instance()

◆ layers()

◆ load() [1/2]

◆ load() [2/2]

◆ trait_count()

◆ unresolved()