Components

Event and Action

Event

Event job is to trig Actions when conditions matches.

_mechanism

Mechanism class can be specified in _mechanism class attribute. Event parameters will be prepared by this Mechanism.

_concern

Event can observe specified objects. You can specify COL identifier in the _concern class attribute. By default, Event observe all synergies objects.

_prepare

Write here conditions who determine if looked object is concerned by this event. If yes, you must return parameters given to Action. If event is not concerned, you must raise NotConcernedEvent exception.

The Event class

Events must be child class of synergine.synergy.event.Event.Event:

class synergine.synergy.event.Event.Event(actions)

Event are called by mechanisms and trig associated actions if conditions matches.

_concern = 1

The COL id of concerned synergies objects

_each_cycle = 1

Event ca be executed each x cycle if needed

_first_cycle_force = False

Event will be executed at first cycle regardless of _each_cycle

_mechanism

Mechanism class who run this event with prepared parameters

alias of Mechanism

_prepare(object_id, context, parameters={})

Return dict with parameters for actions

Parameters:

• object_id – The id of observed synergy object
• context – The Context
• parameters – Mechanism prepared dict of parameters

Raise:

NotConcernedEvent

Returns:

classmethod get_concern()

Returns:COL name if concerned synergies objects

classmethod get_each_cycle()

Returns:The number of each cycle where execute this event

classmethod get_mechanism()

Returns:Mechanism class who will run this event Return type:Mechanism

classmethod is_first_cycle_force()

observe(object_id, context, parameters={})

Return actions who have to be executed.

Parameters:

• object_id – The id of observed synergy object
• context – The Context
• parameters – Mechanism prepared dict of parameters

Returns:

list of actions

Return type:

list (of Action)

Example

You can found here an example of implemented Event:

from synergine_lifegame.synergy.event.AliveAroundEvent import AliveAroundEvent
from synergine.core.exceptions import NotConcernedEvent
from synergine_xyz.mechanism.AroundMechanism import AroundMechanism
from synergine_lifegame.cst import ALIVE, COL_DIED


class GoodConditionToBornEvent(AliveAroundEvent):
    """
    This event is applied when born condition are here. So when exactly 3 alive cell are around of observed cell.
    """

    _mechanism = AroundMechanism
    """This event need to know what is around concerned cell. So we use AroundMechanism who give us list of around
    objects ids."""

    _concern = COL_DIED
    """This event only concern died cells."""

    def _prepare(self, object_id, context, parameters={}):
        """
        According to “Conway’s Game of Life”, event match if exactly 3 around cell are alive.
        """
        cell_near_count = self._get_alive_cell_around_count(context, parameters)
        if cell_near_count is 3:
            return parameters
        #  If event not match, we must raise an NotConcernedEvent.
        raise NotConcernedEvent()

Action

Action own the code intended for modify synergies objects.

_listen

They have to listen an Event. Action _listen class attribute must be contain an Event class.

_depend

If the Action must be executed after other actions, you can list them in Action _depend class attribute.

run

The execution code of Action have to be write in run method.

The Action class

Actions must be child class of synergine.synergy.event.Action.Action.

class synergine.synergy.event.Action.Action(object_id, parameters)

Action own the code intended for modify synergies objects.

_depend = []

List of Action who need to be executed before this.

_listen = None

The Event class to listen.

classmethod cycle_pre_run(context, synergy_manager)

This class method will be executed each cycle, one time by action class. Useful fo apply some tricks before this synergies objects action.

Parameters:

• context –
• synergy_manager –

Returns:

classmethod get_dependencies()

Returns:List of Action who need to be executed before this. Return type:list (of Action)

classmethod get_listened_class()

Returns:The listened Event class. Return type:synergine.synergy.Event.Event

get_object_id()

Returns:The concerned synergy object id Return type:int

run(obj, context, synergy_manager)

The execution code of Action have to be write in run method.

Parameters:

• obj – The synergy concerned object
• context – The Context
• synergy_manager – SynergyObjectManager

Returns:

Example

You can found here an example of implemented Action:

from synergine.synergy.event.Action import Action
from synergine_lifegame.synergy.event.GoodConditionToBornEvent import GoodConditionToBornEvent


class BornAction(Action):
    """
    This action change state of Cell into alive.
    """

    _listen = GoodConditionToBornEvent
    """This action listen the GoodConditionToBornEvent"""

    def run(self, obj, context, synergy_manager):
        obj.set_alive(True)

Mechanism

Mechanism prepare data for associated Events. It’s role is to compute once what multiple Events will need.

Mechanisms must be child of:

class synergine.core.simulation.mechanism.Mechanism.Mechanism(events)

Mechanism prepare data for associated events. The principle: One mechanism compute once what multiple events need.

_get_computed_object_event_parameters(object_id, context)

(You must override this method in child-class.) Compute concerned object event parameters.

Parameters:

• object_id – Concerned object id
• context – The Context

Returns:

Concerned object event parameters

_get_object_parameters(object_id, context)

Return concerned object parameters for event.

Parameters:

• object_id – Concerned object if
• context – The Context

Returns:

parameters who will be used by event

_run_events(context)

Return Action according to this mechanism events.

Parameters:context – The Context Returns:list (of Action)

run(context)

Prepare new mechanism cycle and return Action according to this mechanism events.

Parameters:context – Returns:Actions to run this cycle Return type:list (of Action objects)

Example

You can found here an example of implemented Mechanism:

from synergine.core.exceptions import UselessMechanism
from synergine.core.simulation.mechanism.Mechanism import Mechanism
from synergine_xyz.cst import POSITION


class AroundMechanism(Mechanism):
    """
    Compute near object ids of concerned object.
    """

    def _get_computed_object_event_parameters(self, object_id, context):
        """

        :param object_id: Concerned object id
        :param context: Context object
        :return: Near objects ids: {'objects_ids_near': [0, 1, 2, 3, ...]}
        :rtype: dict
        """

        object_point = context.metas.value.get(POSITION, object_id)
        objects_ids_near = context.get_objects_ids_near_point(object_point, 1)

        # If we not have near object, this mechanism is useless. So we raise a UselessMechanism: Synergine will not
        # run associated events in this case.
        if not objects_ids_near:
            raise UselessMechanism()

        return {'objects_ids_near': objects_ids_near}

Context, Metas

Context is designed to contain data (in metas attribute) and method representing simulation. You can found information about it here, example of Context class here and usage example in HowTo documentation.

COL

For performance reason, an event can compute for specified list of SynergyObject. When his _concern attribute is configured with a COL_XXX, only SynergyObjects contained in this COL_XXX will be concerned.

You can see _concern usage example here.

SynergyObject

SynergyObject is a representation of your simulation subject.

class synergine.synergy.object.SynergyObject.SynergyObject(collection, context)

Variables:

• _collection – Foo
• _cycle_frequency – Bar

_add_col(col, **kwargs)

Shortcut to self._context.metas.collections.add

Parameters:col – COL Returns:

_add_state(state, **kwargs)

Shortcut to self._context.metas.states.add

Parameters:state – State Returns:

_remove_col(col, **kwargs)

Shortcut to self._context.metas.collections.remove

Parameters:col – COL Returns:

_remove_state(state, **kwargs)

Shortcut to self._context.metas.states.remove

Parameters:state – State Returns:

get_collection()

Return the Collection who contain this

Returns:The Collection who contain this Return type:SynergyCollection

get_id()

Return the unique id of this object

Returns:Unique id of this object Return type:int

initialize()

You can place code here to initialize object after his creation and before simulation start.

Returns:

class synergine.core.Test.Test

foo = None

A foo bar instance attribute !

Display

Ready-to-use DisplayObjects are available:

• synergine_xyz.display.Pygame.Pygame (you can found example usage here)
• xywold.display.CursesDisplay.CursesDisplay

Signals

Hook are available. To trig hook:

>>> Signals.signal(<HOOK NAME>).send(<PARAMETERS>)

Where <HOOK NAME> is anything you want and <PARAMETERS> according your callbacks parameters definitions.

To define callback:

>>> Signals.signal(<HOOK NAME>).connect(<A CALLABLE>)

Existing signals are (list of hook names):

• An Action class: Trig just after Action have been executed. Callback parameters definition is .send(obj: SynergyObject, context: Context)
• synergine.synergy.collection.SynergyCollection.SynergyCollection.SIGNAL_ADD_OBJECT: When object add to a SynergyCollection. Callback parameters definition is .send(collection:: SynergyCollection, obj: SynergyObject)
• synergine.synergy.collection.SynergyCollection.SynergyCollection.SIGNAL_REMOVE_OBJECT: When object removed from a SynergyCollection. Callback parameters definition is .send(collection:: SynergyCollection, obj: SynergyObject)

Exceptions

Available Exception:

exception synergine.core.exceptions.EventException

Event related Exception

exception synergine.core.exceptions.ImproperlyConfigured

exception synergine.core.exceptions.NotConcernedEvent

Exception raised when concerned SynergyObject is not concerned by Event.

exception synergine.core.exceptions.NotFound

exception synergine.core.exceptions.UselessMechanism

Exception raised when concerned SynergyObject is not concerned by this Mechanism.