Opinion Dynamic Models

Opinion dynamics models study how individual opinions evolve through local interactions in a networked population. Depending on the model, each node holds either a discrete opinion (e.g., binary 0/1) or a continuous opinion value, and updates it based on the states of its neighbors according to mechanisms such as imitation, social reinforcement, majority voting, or bounded-confidence averaging.

These models find applications in computational social science, political polarization analysis, consensus formation, marketing strategy, and the study of echo chambers in online social networks.

All opinion dynamics models in FS_GPlib operate on static networks — directed or undirected graphs with a fixed topology. The models support execution on both CPU and GPU, and can leverage the batch-parallel acceleration described in the Tutorial.

Base Class & Common API

Every opinion dynamics model inherits from DiffusionModel, which provides the shared initialisation pipeline and a uniform simulation interface. Understanding the base class helps you leverage the full API of any concrete model.

class fs_gplib.Opinions.base.DiffusionModel(data, seeds: float | List[int] | None, rand_seed=None, device='cpu', **kwargs)[source]

Base class for all opinion dynamics models on static graphs.

DiffusionModel (in the Opinions package) provides the shared initialisation logic and a uniform simulation interface that every concrete opinion model (Voter, QVoter, MajorityRule, Sznajd, HK, WHK) inherits. Users typically do not instantiate this class directly; instead they create a subclass such as VoterModel.

Initialisation pipeline (executed in __init__):

Validate the input graph via _validate_graph().
Initialise seed nodes (or initial opinions) via _initialize_seeds().
Validate and store model-specific parameters via _validate_parameters().
Transfer the model to the target device via _set_device().

Simulation interface – four progressively higher-level entry points:

Method	Description
`run_iteration()`	Advance one time step from the current state.
`run_iterations(times)`	Advance times steps from the current state.
`run_epoch(times)`	Reset to initial state, then run times steps (one independent realisation).
`run_epochs(epochs, times, batch_size)`	Run epochs independent realisations in batches (Monte-Carlo simulation).

Parameters:

data (torch_geometric.data.Data) -- PyTorch Geometric Data object representing the graph. Must contain edge_index.
seeds (float | list[int] | list[float] | None) --
Initial opinion configuration.
- For discrete opinion models (e.g. Voter): a list of node IDs holding opinion 1, or a float in [0, 1) representing the fraction of nodes to set to opinion 1 uniformly at random. None is accepted for models that set their own initial state.
- For continuous opinion models (e.g. HK): a list of floats giving the initial opinion of every node, or None to sample uniformly from \((-1, 1)\).
rand_seed (int | None) -- Random seed for NumPy / Python RNG, used when seeds is a float or None to make the random initialisation reproducible. Defaults to None.
device (str | int) -- 'cpu' or a CUDA device index (e.g. 0). Defaults to 'cpu'.
kwargs -- Model-specific parameters (e.g. epsilon for HK). Each key-value pair is validated and stored as an instance attribute.

Utility Methods

The following utility methods can be called on any opinion model instance to re-configure the model after construction:

DiffusionModel._init_node_status()[source]

Reset all node opinions to the initial configuration.

This method rebuilds the internal node_status tensor(s) so that the opinion state matches the original seed configuration.

Subclasses must override this method to create the status tensors appropriate for their opinion representation (e.g. a single boolean tensor for Voter, or a float tensor for HK).

Calling this method is useful when you want to rerun a simulation from scratch without reconstructing the model object.

Example

result1 = model.run_iterations(100)
model._init_node_status()   # reset
result2 = model.run_iterations(100)

DiffusionModel._set_device(device)[source]

Set (or switch) the computation device for the model.

When called during initialisation the graph data and internal tensors are moved to the target device. It can also be called after construction to migrate an existing model to a different device (subclasses should override this method to move additional tensors).

Parameters:: device (str | int) -- 'cpu' or a CUDA device index (e.g. 0).
Raises:: Exception -- If a GPU is requested but CUDA is not available.

Example

model = VoterModel(data, seeds, device='cpu')
# switch to GPU 0
model._set_device(0)

DiffusionModel._set_seed(seeds)[source]

Replace the current seed / opinion configuration and refresh node states.

This is the recommended way to change seeds after construction. It calls _initialize_seeds() to parse and store the new seeds, then (if the model is fully initialised) _init_node_status() to rebuild the node-state tensors on the current device.

Parameters:: seeds (float | list[int] | list[float] | None) -- New seed specification – same format as the constructor parameter seeds (a float fraction, a list of node IDs / opinion values, or None).

Example

model = VoterModel(data, seeds=[0, 1, 2], ...)
# later, switch to a random 20 % opinion-1 set
model._set_seed(0.2)

Simulation Interface

All opinion models expose four progressively higher-level simulation methods. The table below summarises their behaviour; each concrete model page documents the return type for that specific model.

Method	Description	Resets state?
`Model.run_iteration()`	Advance one time step from the current state.	No
`Model.run_iterations(times)`	Advance times steps from the current state.	No
`Model.run_epoch(times)`	Reset to initial state, then run times steps (one independent realisation).	Yes
`Model.run_epochs(epochs, times, batch_size)`	Run epochs independent realisations in batches (Monte-Carlo simulation).	Yes

Tip

run_iteration / run_iterations do not reset node opinions, so they can be chained to inspect intermediate states or implement custom stopping criteria. run_epoch / run_epochs always start from the initial opinion configuration and are the recommended entry points for Monte-Carlo studies.

Available Models

The following models are available: