Ensemble Generation

AbstractEnsembleGenerator

class rethon.AbstractEnsembleGenerator

Bases: ABC

Abstract base class for all ensemble generators.

This abstract class should be used to implement ensemble generators. It implements basic functionalities to add data items that will be used to generate dictionaries for each model run and that will contain information about each model run according to the specified data items. Data items (key-value pairs in the produced dict) can be defined by specifying a key and a function that returns the desired data (see add_item()).

Methods

add_item(key, fun)	Adds a data item.
add_obj(key, obj)	Adding a data object.
dialectical_structure()	Current dialectical structure when iterating through model runs.
ensemble_items_iter()	Iterator through data items of model runs.
ensemble_items_to_csv(output_file_name, ...)	Saving model runs as csv file.
ensemble_iter()	Iterator through all model runs.
ensemble_states()	Current ensemble states when iterating through the model runs.
get_item(key)	Returns the return value of the function that is defined by the data item.
get_obj(key)	Returns a data object.
init_ensemble_fields(ensemble_states, ...)	Initiating data objects that rely on the dialectical structure and a set of finished model runs.
init_re_final_fields(reflective_equilibrium, ...)	Initiating data objects that rely on the dialectical structure and a finished model run.
init_re_start_fields(reflective_equilibrium, ...)	Initiating data objects that rely on the dialectical structure and an instantied RE.
init_tau_fields(tau)	Initiating data objects that rely on the dialectical structure.
initial_commitments()	Current initial commitments when iterating through the model runs.
reflective_equilibrium()	Current state when iterating through the model runs.
remove_item(key)	Removing a data item.
state()	Current state when iterating through model runs.

__init__()

add_item(key, fun)

Adds a data item.

Adding a key-method pair that will be used to calculate a data item. Data items will be returned for each model run by ensemble_items_iter(). A data item represents data that describes a model run in some way. It can be defined by providing a function that can use the internal attributes (e.g. via its getters state(), dialectical_structure(), reflective_equilibrium(), initial_commitments() and ensemble_states()) and deposited objects (via add_obj()). The function should specify an AbstractEnsembleGenerator as its one argument.

A simple example is the following:

# defining the function
def data_last_coms(ensemble_generator):
    return ensemble_generator.state().last_commitments()

# adding the data item
my_ensemble_generator.add_item('last_coms', data_last_coms)

# looping through the ensemble using the item_iter will now
# have a key-value pair that stores the final commitments
# for each model run
for model_run_data_items in my_ensemble_generator.ensemble_items_iter():
    print("The model run produced the following data items:")
    print(f"{model_run_data_items}.")

Parameters:

• key (str) – A key for the data item.

• fun (Callable[[AbstractEnsembleGenerator], None]) – A function that defines a datum of a model run.

add_obj(key, obj)

Adding a data object.

This method can be used to store data objects that persists through different model runs and can then be accessed via get_obj(). See init_tau_fields() for the rationale of using data objects.

Parameters:

key (str) –

dialectical_structure()

Current dialectical structure when iterating through model runs.

Return type:

DialecticalStructure

ensemble_items_iter()

Iterator through data items of model runs.

This methods uses ensemble_iter() to return for each model run a dictionary with predefined data items as key-value pairs. The data items can be added with add_item().

Return type:

Iterator[Dict]

ensemble_items_to_csv(output_file_name, output_dir_name, archive=False, save_preliminary_results=False, preliminary_results_interval=500, append=False)

Saving model runs as csv file.

Using ensemble_items_iter() to save the data items of each model run as csv file.

Parameters:

• output_file_name (str) – Name of the csv file.

• output_dir_name (str) – Directory of the csv file.

• archive (bool) – If True the csv file will be archived as tar.gz. The csv file will not be removed.

• save_preliminary_results (bool) – If True the method will save preliminary results every other model run as defined by preliminary_results_interval.

• append (bool) – If True the rows will be added to the file (if it already exists).

• preliminary_results_interval (int) –

abstract ensemble_iter()

Iterator through all model runs.

This method should be overriden by subclasses and is responsible to call init_tau_fields(), init_re_start_fields(), init_re_final_fields() and init_ensemble_fields() at appropriate times. Addionally, it should reset the internal attributes current_dialectical_structure, current_state, current_reflective_equilibrium, current_initial_commitments and current_ensemble_states that can be used to define data item (see add_item()).

Return type:

Iterator[ReflectiveEquilibrium]

ensemble_states()

Current ensemble states when iterating through the model runs.

Return type:

List[REState]

get_item(key)

Returns the return value of the function that is defined by the data item.

get_obj(key)

Returns a data object.

init_ensemble_fields(ensemble_states, dialectical_structure)

Initiating data objects that rely on the dialectical structure and a set of finished model runs.

This method can be called by implementations of ensemble_iter() and can be used to store objects by add_obj() that in turn can be accessed by get_obj() in the definition of data items. Implementing classes should ensure that all models that are aggregated in a sub-ensemble finished in fixed points. (For a rationale of why using this method, see init_tau_fields().)

Parameters:

• ensemble_states (List[REState]) –

• dialectical_structure (DialecticalStructure) –

init_re_final_fields(reflective_equilibrium, dialectical_structure)

Initiating data objects that rely on the dialectical structure and a finished model run.

This method can be called by implementations of ensemble_iter() and can be used to store objects by add_obj() that in turn can be accessed by get_obj() in the definition of data items. Implementing classes should ensure that the model represented by reflective_equilibrium finished in a fixed point. (For a rationale of why using this method, see init_tau_fields().)

Parameters:

• reflective_equilibrium (ReflectiveEquilibrium) –

• dialectical_structure (DialecticalStructure) –

init_re_start_fields(reflective_equilibrium, dialectical_structure)

Initiating data objects that rely on the dialectical structure and an instantied RE.

This method can be called by implementations of ensemble_iter() and can be used to store objects by add_obj() that in turn can be accessed by get_obj() in the definition of data items. Implementing classes should ensure that at least the initial commitments and model parameters of the RE instance are already set. (For a rationale of why using this method, see init_tau_fields().)

Parameters:

• reflective_equilibrium (ReflectiveEquilibrium) –

• dialectical_structure (DialecticalStructure) –

init_tau_fields(tau)

Initiating data objects that rely on the dialectical structure.

This method can be called by implementations of ensemble_iter() and can be used to store objects by add_obj() that in turn can be accessed by get_obj() in the definition of data items.

The idea is to reuse data instead of recalculating it in every model run inasmuch (depending on the implementation of this class) several model runs can be based on the same dialectical structure \(\tau\). Accordingly, implementations of ensemble_iter() should call this method once for every model run that is based on a particular dialectical structure. A subclass, say MyEnsembleGenerator, can then override this method:

def init_tau_fields(self, tau):
    self.add_obj('inferential_density',
                 tau.inferential_density())

The implementation can then access this object in the definition of data items, for instance:

generator = MyEnsembleGenerator()
generator.add_item('calculated_inferential_density',
                   lambda x: x.get_obj('inferential_density'))

initial_commitments()

Current initial commitments when iterating through the model runs.

Return type:

Position

reflective_equilibrium()

Current state when iterating through the model runs.

Return type:

ReflectiveEquilibrium

remove_item(key)

Removing a data item.

Parameters:

key (str) –

state()

Current state when iterating through model runs.

Return type:

REState

EnsembleGenerator

class rethon.EnsembleGenerator

Bases: AbstractEnsembleGenerator

Ensemble generator base class for independent model runs.

A class that provides iterators for model runs based on the given parameters of the constructor. The iterator will be build as a cartesian product of these arguments (see EnsembleGenerator.ensemble_iter()). The model runs of the ensemble are all based on the same sentence pool. If you whish to generate ensemble with differing sentence pool, you can concatenate instances of this class.

Parameters:

• arguments_list – Dialectical structures as list of argument lists.

• n_sentence_pool – Number of (unnegated) sentences in the sentence pool.

• initial_commitments_list – List of initial commitments. Each commitments is represent as set of integers.

• model_parameters_list – A list of dictionaries that represents the model parameters and can be set by ReflectiveEquilibrium.set_model_parameter().

• max_re_length – If the number of adjustment steps in an RE process exeed max_re_length, the generator raises a MaxLoopsWarning.

• create_branches – If True all branches are created.

• max_branches – Only active if create_branches = True. If the number of branches exceeds max_branches, the generator raises a MaxBranchesWarning.

• implementations – A list of dicts, each representing a specific implementation. Each dict should contain strings for the keys ‘tau_module_name’, ‘rethon_module_name’, ‘position_class_name’, ‘dialectical_structure_class_name’ and ‘reflective_equilibrium_class_name’. (If these classes are located in different modules, you can, alternatively, specify modules for each class by using the keys ‘position_module_name’, ‘dialectical_structure_module_name’ and ‘reflective_equilibrium_module_name’)

Methods

add_item(key, fun)	Adds a data item.
add_obj(key, obj)	Adding a data object.
dialectical_structure()	Current dialectical structure when iterating through model runs.
ensemble_items_iter()	Iterator through data items of model runs.
ensemble_items_to_csv(output_file_name, ...)	Saving model runs as csv file.
ensemble_iter()	Iterator through re processes.
ensemble_states()	Current ensemble states when iterating through the model runs.
get_item(key)	Returns the return value of the function that is defined by the data item.
get_obj(key)	Returns a data object.
init_ensemble_fields(ensemble_states, ...)	Initiating data objects that rely on the dialectical structure and a set of finished model runs.
init_re_final_fields(reflective_equilibrium, ...)	Initiating data objects that rely on the dialectical structure and a finished model run.
init_re_start_fields(reflective_equilibrium, ...)	Initiating data objects that rely on the dialectical structure and an instantied RE.
init_tau_fields(tau)	Initiating data objects that rely on the dialectical structure.
initial_commitments()	Current initial commitments when iterating through the model runs.
reflective_equilibrium()	Current state when iterating through the model runs.
remove_item(key)	Removing a data item.
state()	Current state when iterating through model runs.

__init__(arguments_list, n_sentence_pool, initial_commitments_list, model_parameters_list=None, max_re_length=50, create_branches=False, max_branches=50, implementations=None)

Parameters:

• arguments_list (List[List[List[int]]]) –

• n_sentence_pool (int) –

• initial_commitments_list (List[Set[int]]) –

• model_parameters_list (List[Dict] | None) –

• max_re_length (int) –

• create_branches (bool) –

• max_branches (int) –

• implementations (List[Dict] | None) –

ensemble_iter()

Iterator through re processes.

An ensemble iterator that produces all ensembles in the cartesian product of the given dialectical structures (arguments_list), the initial commitments (initial_commitments_list), the list of model parameters (model_parameters_list) and the given implementations (implementations). If create_branches is set to True every branch resulting from an underdetermination of commitments or theory candidates will be returned as well.

Return type:

Iterator[ReflectiveEquilibrium]

SimpleEnsembleGenerator

class rethon.SimpleEnsembleGenerator

Bases: EnsembleGenerator

This class extends EnsembleGenerator by adding the following data items that are produced by AbstractEnsembleGenerator.ensemble_items_iter():

FEATURES OF THE DIALECTICAL STRUCTURE

• model_name: A name of the model as string.

• tau: The dialectical structure as list of int-lists. The first numbers of each list represent the premises, the last one the conclusion.

• n_sentence_pool: Number of unnegated sentences (half the full size).

• tau_arg_size: Number of arguments.

• tau_infer_dens: The inferential density of the structure.

• tau_n_consistent_complete_positions: Number of dialectically complete and consistent positions.

• tau_mean_prem: Mean number of premises per argument.

• tau_variance_prem: Variance of the number of premises per argument.

• tau_truths: Propositions that are true in every complete consistent position.

• principles: A list of tuples of the form (principle, multiplicity) with multiplicity indicating the multiplicity of the principle. A sentence counts as a principle iff it occurs in at least one argument as premise and it or its negation does not occur as a conclusion in an argument. The multiplicity counts in how many argument the sentence occurs as premise.

PARAMETERS OF THE RE-PROCESS

• account_penalties:

• faithfulness_penalties:

• weight_account:

• weight_systematicity:

• weight_faithfulness:

PROCESS-FEATURES

• error_code: If a process did not terminate correctly an error code is provided. The container will execute subsequent processes in this case. Error code MaxLoopsWarning.ERROR_CODE (1) indicates that the process did not finish within the given maximum number of loops (as set via EnsembleGenerator, see also REState.). Error code MaxBranchesWarning.ERROR_CODE (2) indicates that the execution of all branches exceeded the maximum number of allowed branches (set by max_branches). Error code 0 indicates all other thrown exceptions. If the process terminates without errors the field is empty (nan).

• init_coms: The initial commitments.

• init_coms_size: Number of initial commitments.

• init_coms_n_tau_truths: Number of tau-true propositions in the initial commitments.

• init_coms_n_tau_falsehoods: Number of tau-false propositions in the initial commitments.

• init_coms_min_ax_bases: Minimal-length axiomatic bases of init_coms with sentences from init_coms only. (Sentences \(\mathcal{C}_a\) are an axiomatic basis of \(\mathcal{C}_1\) (with sentences from \(\mathcal{C}_2\) only) iff \(\mathcal{C}_a\) dialectically implies \(\mathcal{C}_1\) and there is no proper subset of \(\mathcal{C}_a\) such that it implies \(\mathcal{C}_1\) (and \(\mathcal{C}_a \subset \mathcal{C}_2\)).)

• n_init_coms_min_ax_base: The length of the minimal-length axiomatic bases (not the number of such bases).

• init_coms_n_consistent_complete_positions: Number of consistent complete positions that extend the initial commitments.

• init_coms_dia_consistent: Whether the initial commitments are dialectically consistent.

• init_coms_closed: Whether the initial commitments are dialectically closed.

• init_coms_closure: Dialectical closure of initial commitments.

• fixed_point_coms: Final commitments.

• fixed_point_coms_size: The number of propositions in fixed_point_coms.

• fixed_point_coms_com_n_tau_truths: Number of tau-true propositions in the final commitments.

• fixed_point_coms_com_n_tau_falsehoods: Number of tau-false propositions in the final commitments.

• fixed_point_coms_closed: Whether the final commitments is dialectically closed.

• fixed_point_coms_closure: Dialectical closure of final commitments.

• fixed_point_coms_consistent: Whether the final commitments is dialectically consistent.

• fixed_point_theory: The final theory.

• fixed_point_theory_closure: Closure of the final theory.

• achievements_evolution:

• fixed_point_dia_consistent: Whether the union of final theory & commitments is dialectically consistent.

• init_final_coms_simple_hamming: Simple hamming distance between initial and final commitments.

• init_final_coms_hamming: Hamming distance between initial and final commitments as defined in BBB with d_3 = 1, d_2 = 1, d_1 = 1, d_0 = 0.

• init_final_coms_contradictions: Amount of contradictions: number of sentences whose contradictions are in both positions (i.e. hamming distance as defined in BBB with d_3 = 1, d_2 = 0, d_1 = 0, d_0 = 0)

• init_final_coms_expansions: Amount of expansions without expansions that lead to contradictions or identities (i.e. hamming distance as defined in BBB with d_3 = 0, d_2 = 0, d_1 = 1, d_0 = 0)

• init_final_coms_contractions: Amount of contractions (i.e. hamming distance as defined in BBB with d_3 = 0, d_2 = 1, d_1 = 0, d_0 = 0)

• init_final_coms_identities: Amount of identities without identities that are associated with contradictions (i.e. hamming distance as defined in BBB with d_3 = 0, d_2 = 0, d_1 = 0, d_0 = 1) attention: counts also sentences on which both positions are indifferent.

• random_choices:

• n_random_choices: Number of random choice of the process.

• coms_evolution: The dynamic evolution of theories during the process. (Depicting the algorithmic process.)

• theory_evolution: The dynamic evolution of commitments during the process. (Depicting the algorithmic process.)

• process_length: The length of the process. Defined as the number of number of theories and commitment sets in the evolution of the epistemic state, including the initial and final state. The minimal length of a process is 4 and represents a case of no change in the epistemic state. I.e., a case where the achievement of initial commitments and the first chosen theory cannot be further improved.

PROCESS-INDEPENDENT FEATURES

In the case that the ensemble generator is configured (via its instantiation) to run all branches the following data items are added as well:

• n_branches: Number of branches of the process (i.e. paths to all fixed points w.r.t. the given initial commitments. Note that n_branches will not necessarily coincide with the size of the set fixed_points (n_fixed_points) since different branches may end up in the same fixed point.

• fixed_points: The set of fixed points as theory-commitments-tuples (unique fixed points).

• n_fixed_points: Number of fixed points (again, which is not necessarily identical to the number of branches).

Fixed points:

• fp_coms_consistent: A list of bools (List[bool]) indicating whether commitments of the fixed_points are dialectically consistent. The order of the list represents the order in fixed_points.

• fp_union_consistent: A list of bools (List[bool]) indicating whether the unions of a commitment-theory-tuple of the fixed_points are dialectically consistent.The order of the list represents the order in fixed_points.

• fp_account: The account of each fixed point as List[float]. The order of the list represents the order in fixed_points.

• fp_faithfulness: The faithfulness of each fixed as List[float]. The order of the list represents the order in fixed_points.

Methods

add_item(key, fun)	Adds a data item.
add_obj(key, obj)	Adding a data object.
dialectical_structure()	Current dialectical structure when iterating through model runs.
ensemble_items_iter()	Iterator through data items of model runs.
ensemble_items_to_csv(output_file_name, ...)	Saving model runs as csv file.
ensemble_iter()	Iterator through re processes.
ensemble_states()	Current ensemble states when iterating through the model runs.
get_item(key)	Returns the return value of the function that is defined by the data item.
get_obj(key)	Returns a data object.
init_ensemble_fields(ensemble_states, ...)	Overrides AbstractEnsembleGenerator.init_ensemble_fields.
init_re_final_fields(reflective_equilibrium, ...)	Initiating data objects that rely on the dialectical structure and a finished model run.
init_re_start_fields(reflective_equilibrium, ...)	Overrides AbstractEnsembleGenerator.init_re_start_fields.
init_tau_fields(tau)	Overrides AbstractEnsembleGenerator.init_tau_fields.
initial_commitments()	Current initial commitments when iterating through the model runs.
reflective_equilibrium()	Current state when iterating through the model runs.
remove_item(key)	Removing a data item.
state()	Current state when iterating through model runs.

__init__(arguments_list, n_sentence_pool, initial_commitments_list, model_parameters_list=None, max_re_length=50, create_branches=False, max_branches=50, implementations=None)

Parameters:

• arguments_list (List[List[List[int]]]) – A list of dialectical structures. Each dialectical structure is represented as a list of arguments (List[List[int]]).

• n_sentence_pool (int) – Size of the (unnegated) sentence pool.

• initial_commitments_list (List[Set[int]]) – A list of initial commitments.

• model_parameters_list (Optional[List[Dict]]) – A list of model parameter.

• max_re_length (int) – A threshold for how long individual RE processes can maximally run. Processes that exceed this value, will be interrupted. However, the ensemble generator itself will not be interrupted. Interrupted model runs will appear in the result set with an error code (field error_code).

• create_branches (bool) – If True, the ensemble generator will track every branch. Every branch will be represented by an individual result in the resulting iterator (or an individual row in the resulting csv). The results will contain multiple redundancies: The field fixed_points is a set of all fixed points which will be reproduced in every row that represents a branch of a model run. Similarly, the field global_optima will contain the same set of global optima for each branch. Note that n_branches will not necessarily coincide with the size of the set fixed_points (n_fixed_points) since different branches may end up in the same fixed point.

• max_branches (int) –

• implementations (Optional[List[Dict]]) –

init_ensemble_fields(ensemble_states, dialectical_structure)

Overrides AbstractEnsembleGenerator.init_ensemble_fields.

Adds the following data object that can be accessed via AbstractEnsembleGenerator.get_obj(): ‘n_branches’ and ‘fixed_points’, if the ensemble generator is set up to run every branch.

Parameters:

• ensemble_states (List[REState]) –

• dialectical_structure (DialecticalStructure) –

init_re_start_fields(reflective_equilibrium, dialectical_structure)

Overrides AbstractEnsembleGenerator.init_re_start_fields.

Adds the following data object that can be accessed via AbstractEnsembleGenerator.get_obj(): ‘init_com_min_ax_bases’.

Parameters:

• reflective_equilibrium (ReflectiveEquilibrium) –

• dialectical_structure (DialecticalStructure) –

init_tau_fields(tau)

Overrides AbstractEnsembleGenerator.init_tau_fields.

Adds the following data objects that can be accessed via AbstractEnsembleGenerator.get_obj(): ‘tau_infer_dens’, ‘n_premises’, ‘principles’, ‘tau_truths’ and ‘tau_falsehoods’.

Parameters:

tau (DialecticalStructure) –

GlobalREEnsembleGenerator

class rethon.GlobalREEnsembleGenerator

Bases: SimpleEnsembleGenerator

This class extends SimpleEnsembleGenerator by adding the following data items that are produced by AbstractEnsembleGenerator.ensemble_items_iter():

Additional items for the fixed point:

• fixed_point_is_global_optimum: Whether the fixed point is a global optimum.

• fixed_point_is_re_state: Whether the fixed point is a RE state.

• fixed_point_is_full_re_state: Whether the fixed point is a full RE state.

• fixed_point_coms_n_consistent_complete_positions: The number of complete and dialectically consistent positions that extend the final commitments.

• fixed_point_coms_min_ax_bases: Minimal-length axiomatic bases of fixed_point_coms with sentences from fixed_point_coms only. (Sentences \(\mathcal{C}_a\) are an axiomatic basis of \(\mathcal{C}_1\) (with sentences from \(\mathcal{C}_2\) only) iff \(\mathcal{C}_a\) dialectically implies \(\mathcal{C}_1\) and there is no proper subset of \(\mathcal{C}_a\) such that it implies \(\mathcal{C}_1\) (and \(\mathcal{C}_a \subset \mathcal{C}_2\)).)

• n_fixed_point_coms_min_ax_base: The size of minimal-length axiomatic bases of fixed_point_coms with sentences from fixed_point_coms only.

• fixed_point_coms_min_ax_bases_theory: A minimal-length subset \(\mathcal{C}'\) of the final commitments such that the final commitments are entailed by the theory and \(\mathcal{C}'\). (Or equivalently: A smallest subset \(\mathcal{C}'\) within the commitments such that there is an axiomatic basis \(A\) for the commitments \(\mathcal{C}\) with: \(A= \mathcal{C}' \cup \mathcal{T}'\) and \(\mathcal{T}'\) a subset of the theory)

• n_fixed_point_coms_min_ax_base_theory: Number of propositions in each set in fixed_point_coms_min_ax_bases_theory.

• fixed_point_theory_axioms: Axiomatic bases of the final theory.

Additional items for all fixed points (these items are only generated if branches are created):

• fp_full_re_state: A list of bools (List[bool]) indicating whether the fixed_points are full RE-states (i.e. whether the dialectical closure of the theory is identical to the commitments). The order of the list represents the order in fixed_points. (This field is only available if create_branches is set.)

• fp_global_optimum: A list of bools (List[bool]) indicating whether the fixed_points are global_optima. (This field is only available if create_branches is set.)

Additional items for global optima:

• global_optima: All global optima as theory-commitments-tuples.

• n_global_optima: Number of global optima.

• go_coms_consistent: A list of bools (List[bool]) indicating whether commitments of the global_optima are dialectically consistent. The order of the list represents the order in global_optima.

• go_union_consistent: A list of bools (List[bool]) indicating whether the unions of a

  commitment-theory-tuple of the global_optima are dialectically consistent. I.e. whether the global optima are RE states.The order of the list represents the order in global_optima.

• go_full_re_state: A list of bools (List[bool]) indicating whether the global_optima are full RE-states (i.e. whether the dialectical closure of the theory is identical to the commitments). The order of the list represents the order in global_optima.

• go_fixed_point: A list of bools (List[bool]) indicating which global optima are fixed points (i.e. which global optima are reachable via a re-process). The order of the list represents the order in global_optima. (This field is only available if create_branches is set.)

• go_account: The account of each global optimum as List[float]. The order of the list represents the order in global_optima.

• go_faithfulness: The faithfulness of each global optimum as List[float]. The order of the list represents the order in global_optima.

Additional items for RE states and full RE states:

• re_states:

• n_re_states:

• full_re_states:

• n_full_re_states:

Methods

add_item(key, fun)	Adds a data item.
add_obj(key, obj)	Adding a data object.
dialectical_structure()	Current dialectical structure when iterating through model runs.
ensemble_items_iter()	Iterator through data items of model runs.
ensemble_items_to_csv(output_file_name, ...)	Saving model runs as csv file.
ensemble_iter()	Iterator through re processes.
ensemble_states()	Current ensemble states when iterating through the model runs.
get_item(key)	Returns the return value of the function that is defined by the data item.
get_obj(key)	Returns a data object.
init_ensemble_fields(ensemble_states, ...)	Overrides AbstractEnsembleGenerator.init_ensemble_fields.
init_re_final_fields(reflective_equilibrium, ...)	Overrides AbstractEnsembleGenerator.init_re_final_fields.
init_re_start_fields(reflective_equilibrium, ...)	Extends SimpleEnsembleGenerator.init_re_final_fields.
init_tau_fields(tau)	Overrides AbstractEnsembleGenerator.init_tau_fields.
initial_commitments()	Current initial commitments when iterating through the model runs.
reflective_equilibrium()	Current state when iterating through the model runs.
remove_item(key)	Removing a data item.
state()	Current state when iterating through model runs.

__init__(arguments_list, n_sentence_pool, initial_commitments_list, model_parameters_list=None, max_re_length=50, create_branches=False, max_branches=50, implementations=None)

Parameters:

• arguments_list (List[List[List[int]]]) – A list of dialectical structures. Each dialectical structure is represented as a list of arguments (List[List[int]]).

• n_sentence_pool (int) – Size of the (unnegated) sentence pool.

• initial_commitments_list (List[Set[int]]) – A list of initial commitments.

• model_parameters_list (Optional[List[Dict]]) – A list of model parameter.

• max_re_length (int) – A threshold for how long individual RE processes can maximally run. Processes that exceed this value, will be interrupted. However, the ensemble generator itself will not be interrupted. Interrupted model runs will appear in the result set with an error code (field error_code).

• create_branches (bool) – If True, the ensemble generator will track every branch. Every branch will be represented by an individual result in the resulting iterator (or an individual row in the resulting csv). The results will contain multiple redundancies: The field fixed_points is a set of all fixed points which will be reproduced in every row that represents a branch of a model run. Similarly, the field global_optima will contain the same set of global optima for each branch. Note that n_branches will not necessarily coincide with the size of the set fixed_points (n_fixed_points) since different branches may end up in the same fixed point.

• max_branches (int) –

• implementations (Optional[List[Dict]]) –

init_re_final_fields(reflective_equilibrium, dialectical_structure)

Overrides AbstractEnsembleGenerator.init_re_final_fields.

Adds the following data objects that can be accessed via AbstractEnsembleGenerator.get_obj(): ‘fixed_point_coms_min_ax_bases’ and ‘fixed_point_coms_min_ax_bases_theory’.

Parameters:

• reflective_equilibrium (ReflectiveEquilibrium) –

• dialectical_structure (DialecticalStructure) –

init_re_start_fields(reflective_equilibrium, dialectical_structure)

Extends SimpleEnsembleGenerator.init_re_final_fields.

Adds the following data objects that can be accessed via AbstractEnsembleGenerator.get_obj(): ‘global_optima’, ‘re_states’ and ‘full_re_states’.

Parameters:

• reflective_equilibrium (ReflectiveEquilibrium) –

• dialectical_structure (DialecticalStructure) –

LocalREEnsembleGenerator

class rethon.LocalREEnsembleGenerator

Bases: SimpleEnsembleGenerator

This class extends SimpleEnsembleGenerator by adding the following data items that are produced by AbstractEnsembleGenerator.ensemble_items_iter():

• neigbourhood_depth: The neighbourhood depth that is used to search for next commitments

  and theory candidates.

Methods

add_item(key, fun)	Adds a data item.
add_obj(key, obj)	Adding a data object.
dialectical_structure()	Current dialectical structure when iterating through model runs.
ensemble_items_iter()	Iterator through data items of model runs.
ensemble_items_to_csv(output_file_name, ...)	Saving model runs as csv file.
ensemble_iter()	Iterator through re processes.
ensemble_states()	Current ensemble states when iterating through the model runs.
get_item(key)	Returns the return value of the function that is defined by the data item.
get_obj(key)	Returns a data object.
init_ensemble_fields(ensemble_states, ...)	Overrides AbstractEnsembleGenerator.init_ensemble_fields.
init_re_final_fields(reflective_equilibrium, ...)	Initiating data objects that rely on the dialectical structure and a finished model run.
init_re_start_fields(reflective_equilibrium, ...)	Overrides AbstractEnsembleGenerator.init_re_start_fields.
init_tau_fields(tau)	Overrides AbstractEnsembleGenerator.init_tau_fields.
initial_commitments()	Current initial commitments when iterating through the model runs.
reflective_equilibrium()	Current state when iterating through the model runs.
remove_item(key)	Removing a data item.
state()	Current state when iterating through model runs.

__init__(arguments_list, n_sentence_pool, initial_commitments_list, model_parameters_list=None, max_re_length=50, create_branches=False, max_branches=50, implementations=None)

Parameters:

• arguments_list (List[List[List[int]]]) – A list of dialectical structures. Each dialectical structure is represented as a list of arguments (List[List[int]]).

• n_sentence_pool (int) – Size of the (unnegated) sentence pool.

• initial_commitments_list (List[Set[int]]) – A list of initial commitments.

• model_parameters_list (Optional[List[Dict]]) – A list of model parameter.

• max_re_length (int) – A threshold for how long individual RE processes can maximally run. Processes that exceed this value, will be interrupted. However, the ensemble generator itself will not be interrupted. Interrupted model runs will appear in the result set with an error code (field error_code).

• create_branches (bool) – If True, the ensemble generator will track every branch. Every branch will be represented by an individual result in the resulting iterator (or an individual row in the resulting csv). The results will contain multiple redundancies: The field fixed_points is a set of all fixed points which will be reproduced in every row that represents a branch of a model run. Similarly, the field global_optima will contain the same set of global optima for each branch. Note that n_branches will not necessarily coincide with the size of the set fixed_points (n_fixed_points) since different branches may end up in the same fixed point.

• max_branches (int) –

• implementations (Optional[List[Dict]]) –

SimpleMultiAgentREContainer

class rethon.SimpleMultiAgentREContainer

Bases: REContainer

An REContainer for multi-agent ensembles.

This container manages and executes model runs that are defined as an multi-agent ensemble. The container will execute for each particular point in time the next step of all model and will then proceed accordingly with the time point. Each model will be provided with the current model states of the other models by references to the other models via the argument other_model_runs. This argument is accessible by overriding or extending the following methods in each model:

• ReflectiveEquilibrium.theory_candidates(),

• ReflectiveEquilibrium.commitment_candidates(),

• ReflectiveEquilibrium.pick_theory_candidate(),

• ReflectiveEquilibrium.pick_commitment_candidate() and

• ReflectiveEquilibrium.finished().

Methods

add_object(key, object)	Helper function to store objects within the container.
get_object(key)	Helper function to retrieve stores objects (see add_object()) from the container.

get_objects
re_processes

__init__(re_models, initial_commitments_list, max_re_length=250)

Parameters:

• re_models (List[ReflectiveEquilibrium]) –

• initial_commitments_list (List[Position]) –

• max_re_length (int) –

re_processes(re_models=None)

Return type:

List[ReflectiveEquilibrium]

Parameters:

re_models (List[ReflectiveEquilibrium] | None) –

MultiAgentEnsemblesGenerator

class rethon.MultiAgentEnsemblesGenerator

Bases: AbstractEnsembleGenerator

Ensemble generator base class for multi-agent (=interdependent) model runs.

A class that provides iterators for interdependent model runs based on the given parameters of the constructor. One ensemble corresponds to a dialectical structure together with a set of agents (represented by their initial commitments). The generator will run all ensembles successively.

This structure can be used to generate different ensembles. For instance, you can vary the number of agents for one particular dialectical structure by repeating the dialectical structure in the above list and vary the list of initial positions. All list must have the same length and the lenght of the lists corresponds to the number of ensembles (defined by them). Note that this design adheres to the following confinements: All agents in one ensemble share the implementing classes and their model parameters.

The following data items are defined by default for each multi-agent ensemble:

• ensemble_id: An id for each ensemble, which is (only) unique within one data file.

• ensemble_size: The size of the ensemble (i.e., the number of agents/initial commitments).

• agents_name: For each ensemble a name for the set of agents, which can be passed by the constructor.

Parameters:

• arguments_list – A list of n dialectical structures as list of argument lists. Each dialectical structure corresponds an multi-agent ensemble.

• n_sentence_pool – Number of (unnegated) sentences in the sentence pool.

• initial_commitments_list – For each dialectical structure a list of initial commitments. (The initial commitments can be thought of as different agents.)

• tau_names – A list of names for the dialectical structures.

• agents_names – For each ensemble a name for the set of agents.

• model_parameters_list – For each dialectical structure a specification of model parameters as dictionary that can be set via ReflectiveEquilibrium.set_model_parameters().

• implementations – A list of dicts, each representing a specific implementation. Each dict should contain strings for the keys ‘module_name’, ‘position_class_name’, ‘dialectical_structure_class_name’ and ‘reflective_equilibrium_class_name’. (If these classes are located in different modules, you can, alternatively, specify modules for each class by using the keys ‘position_module_name’, ‘dialectical_structure_module_name’ and ‘reflective_equilibrium_module_name’)

Methods

add_item(key, fun)	Adds a data item.
add_obj(key, obj)	Adding a data object.
dialectical_structure()	Current dialectical structure when iterating through model runs.
ensemble_items_iter()	Iterator through data items of model runs.
ensemble_items_to_csv(output_file_name, ...)	Extends AbstractEnsembleGenerator.ensemble_items_to_csv.
ensemble_iter()	Iterator through the re processes.
ensemble_states()	Current ensemble states when iterating through the model runs.
get_item(key)	Returns the return value of the function that is defined by the data item.
get_obj(key)	Returns a data object.
init_ensemble_fields(re_states, ...[, ...])	Overrides AbstractEnsembleGenerator.init_ensemble_fields()
init_re_final_fields(reflective_equilibrium, ...)	Initiating data objects that rely on the dialectical structure and a finished model run.
init_re_start_fields(reflective_equilibrium, ...)	Initiating data objects that rely on the dialectical structure and an instantied RE.
init_tau_fields(tau)	Initiating data objects that rely on the dialectical structure.
initial_commitments()	Current initial commitments when iterating through the model runs.
reflective_equilibrium()	Current state when iterating through the model runs.
remove_item(key)	Removing a data item.
state()	Current state when iterating through model runs.

__init__(arguments_list, n_sentence_pools, initial_commitments_list, tau_names=None, agents_names=None, implementations=None, model_parameters_list=None)

Parameters:

• arguments_list (List[List[List[int]]]) –

• n_sentence_pools (List[int]) –

• initial_commitments_list (List[List[Set[int]]]) –

• tau_names (List[str] | None) –

• agents_names (List[str] | None) –

• implementations (List[Dict] | None) –

• model_parameters_list (List[Dict] | None) –

ensemble_items_to_csv(output_file_name, output_dir_name, archive=False, save_preliminary_results=False, preliminary_results_interval=500, append=False)

Extends AbstractEnsembleGenerator.ensemble_items_to_csv.

If append is set to True the method will make sure that different ensembles have different ensemble ids (which are saved via an extra column for each model run).

Parameters:

• output_file_name (str) –

• output_dir_name (str) –

• save_preliminary_results (bool) –

• preliminary_results_interval (int) –

ensemble_iter()

Iterator through the re processes.

An ensemble iterator through all model runs of all multi-agents ensembles as defined by the class attributes (implements AbstractEnsembleGenerator.ensemble_iter()). Model runs that belong to the same multi-agent ensemble can be identified via their ensemble id, which can be accessed via get_obj('ensemble_id').

Return type:

Iterator[ReflectiveEquilibrium]

init_ensemble_fields(re_states, dialectical_structure, init_commitments_name=None)

Overrides AbstractEnsembleGenerator.init_ensemble_fields()

Adds for every multi-agent ensemble the following data objects: ‘ensemble_id’, ‘agents_name’ and ‘ensemble_size’.

Parameters:

• re_states (List[REState]) –

• dialectical_structure (DialecticalStructure) –

• init_commitments_name ([str, None]) –

SimpleMultiAgentEnsemblesGenerator

class rethon.SimpleMultiAgentEnsemblesGenerator

Bases: MultiAgentEnsemblesGenerator

A MultiAgentEnsembleGenerator with predefined data items.

This class extends MultiAgentEnsembleGenerator by adding data items that are produced by AbstractEnsembleGenerator.ensemble_items_iter(). The ensemble generator is initiated with the same data fields as the SimpleEnsembleGenerator (except data fields that are only created in the case that the SimpleEnsembleGenerator runs all branches).

Methods

add_item(key, fun)	Adds a data item.
add_obj(key, obj)	Adding a data object.
dialectical_structure()	Current dialectical structure when iterating through model runs.
ensemble_items_iter()	Iterator through data items of model runs.
ensemble_items_to_csv(output_file_name, ...)	Extends AbstractEnsembleGenerator.ensemble_items_to_csv.
ensemble_iter()	Iterator through the re processes.
ensemble_states()	Current ensemble states when iterating through the model runs.
get_item(key)	Returns the return value of the function that is defined by the data item.
get_obj(key)	Returns a data object.
init_ensemble_fields(re_states, ...[, ...])	Overrides AbstractEnsembleGenerator.init_ensemble_fields()
init_re_final_fields(reflective_equilibrium, ...)	Initiating data objects that rely on the dialectical structure and a finished model run.
init_re_start_fields(reflective_equilibrium, ...)	Overrides AbstractEnsembleGenerator.init_re_start_fields.
init_tau_fields(tau)	Overrides AbstractEnsembleGenerator.init_tau_fields.
initial_commitments()	Current initial commitments when iterating through the model runs.
reflective_equilibrium()	Current state when iterating through the model runs.
remove_item(key)	Removing a data item.
state()	Current state when iterating through model runs.

__init__(arguments_list, n_sentence_pools, initial_commitments_list, tau_names=None, agents_names=None, implementations=None, model_parameters_list=None)

Parameters:

• arguments_list (List[List[List[int]]]) –

• n_sentence_pools (List[int]) –

• initial_commitments_list (List[List[Set[int]]]) –

• tau_names (List[str] | None) –

• agents_names (List[str] | None) –

• implementations (List[Dict] | None) –

• model_parameters_list (List[Dict] | None) –

init_re_start_fields(reflective_equilibrium, dialectical_structure)

Overrides AbstractEnsembleGenerator.init_re_start_fields.

Adds the following data object that can be accessed via AbstractEnsembleGenerator.get_obj(): ‘init_com_min_ax_bases’.

Parameters:

• reflective_equilibrium (ReflectiveEquilibrium) –

• dialectical_structure (DialecticalStructure) –

init_tau_fields(tau)

Overrides AbstractEnsembleGenerator.init_tau_fields.

Adds the following data objects that can be accessed via AbstractEnsembleGenerator.get_obj(): ‘tau_infer_dens’, ‘n_premises’, ‘principles’, ‘tau_truths’ and ‘tau_falsehoods’.

Parameters:

tau (DialecticalStructure) –