Relationship

Class for agent relationships.

__init__(self, agent1, agent2, duration, bond_type, id=None) special

Constructor for a Relationship

Parameters:

Name	Type	Description	Default
agent1	Agent	first agent	required
agent2	Agent	second agent	required
duration	int	target duration of relationship	required
bond_type	str	type of bond for the relationship [params.classes.bond_types]	required
id	Optional[int]	unique identifier	None

Source code in titan/agent.py

def __init__(
    self,
    agent1: Agent,
    agent2: Agent,
    duration: int,
    bond_type: str,
    id: Optional[int] = None,
):
    """
    Constructor for a Relationship

    args:
        agent1: first agent
        agent2: second agent
        duration: target duration of relationship
        bond_type: type of bond for the relationship [params.classes.bond_types]
        id: unique identifier
    """
    # make sure these agents can be in a relationship
    assert agent1 != agent2, "Cannot create relationship with same agent"
    for rel in agent1.relationships:
        assert agent2 != rel.get_partner(agent1), "Agents already partnered!"

    # self.id is unique ID number used to track each person agent.
    self.agent1 = agent1
    self.agent2 = agent2

    if id is not None:
        self.id = id
    else:
        self.id = self.next_rel_id

    self.update_id_counter(self.id)

    # Relationship properties
    self.duration = duration
    self.total_duration = duration
    self.bond_type = bond_type

    self.bond()

bond(self)

Bond two agents. Adds the relationship to each agent's relationships set, then adds each partner to the others' partner list.

Source code in titan/agent.py

def bond(self) -> None:
    """
    Bond two agents. Adds the relationship to each agent's `relationships` set, then adds each partner to the others' partner list.
    """

    # Append relationship to relationships list for each agent
    self.agent1.relationships.add(self)
    self.agent2.relationships.add(self)

    # Pair agent with partner and partner with agent
    self.agent1.partners[self.bond_type].add(self.agent2)
    self.agent2.partners[self.bond_type].add(self.agent1)

get_number_of_sex_acts(self, rand_gen)

Number of sex acts in the relationship during the time step.

Parameters:

Name	Type	Description	Default
rand_gen		np random number generator (e.g. self.run_random in model)	required

Returns:

Type	Description
int	number of sex acts

Source code in titan/agent.py

def get_number_of_sex_acts(self, rand_gen) -> int:
    """
    Number of sex acts in the relationship during the time step.

    args:
        rand_gen: np random number generator (e.g. self.run_random in model)

    returns:
        number of sex acts
    """
    agent = safe_random_choice([self.agent1, self.agent2], rand_gen)
    freq_params = agent.location.params.partnership.sex.frequency[self.bond_type]

    if freq_params.type == "bins":
        i = get_independent_bin(rand_gen, freq_params.bins)
        return safe_random_int(
            freq_params.bins[i].min, freq_params.bins[i].max, rand_gen
        )

    elif freq_params.type == "distribution":
        return round(safe_dist(freq_params.distribution, rand_gen))

    else:
        raise Exception("Sex acts must be defined as bin or distribution")

get_partner(self, agent)

Given an agent in the relationship, return the other agent

Parameters:

Name	Type	Description	Default
agent	Agent	one of the agents in the relationship	required

Returns:

Type	Description
Agent	the agent's partner

Source code in titan/agent.py

def get_partner(self, agent: "Agent") -> "Agent":
    """
    Given an agent in the relationship, return the other agent

    args:
        agent: one of the agents in the relationship

    returns:
        the agent's partner
    """
    if agent == self.agent1:
        return self.agent2
    elif agent == self.agent2:
        return self.agent1
    else:
        raise ValueError("Agent must be in this relationship")

progress(self, force=False)

Progress a relationship to the next time step (decrementing remaining target duration), or end a relationship if the duration is 0 or if force is set to True

Parameters:

Name	Type	Description	Default
force	bool	whether to force the relationship to end	False

Source code in titan/agent.py

def progress(self, force: bool = False) -> bool:
    """
    Progress a relationship to the next time step (decrementing remaining target duration), or end a relationship if the duration is 0 or if `force` is set to `True`

    args:
        force: whether to force the relationship to end
    """
    if self.duration <= 0 or force:
        self.unbond()
        return True
    else:
        self.duration -= 1
        return False

unbond(self)

Unbond two agents. Removes relationship from relationship sets. Removes partners in each others' partner list.

Source code in titan/agent.py

def unbond(self):
    """
    Unbond two agents. Removes relationship from relationship sets.
    Removes partners in each others' partner list.
    """

    # Remove relationship to relationships list for each agent
    self.agent1.relationships.remove(self)
    self.agent2.relationships.remove(self)

    # Unpair agent with partner and partner with agent
    self.agent1.partners[self.bond_type].remove(self.agent2)
    self.agent2.partners[self.bond_type].remove(self.agent1)