Parallel state: multiple instances of same compond state

[Motioneer]

Hello!
I was wondering if it is possible to create a parallel state that is not composed of unique compound states, but multiple copies of the same.

My use case is, that a process involves a list of items that should be processed in parallel, with each item using an instance of a statemachine. Only if all items have processed and their individual statemachines have finished, the overall process should advance.

To illustrate it more, here is a bit of pseudo statemachine code:

class Battle(State.Compound):
      fighting = State(initial=True)
      won = State(final=True)
      victory = fighting.to(won)

class War(StateChart):
    class war(State.Parallel):
        battles = [Battle, Battle, Battle]

Is this even conceptionally possible, or does this break a fundamental rule?
Thank you in advance for any guidance!

[brunolnetto]

@Motioneer Hi! I use Claude to learn about this library. Its answer might be helpful regarding your use case.

TL;DR is: statecharts model structure, not quantity. When the quantity is dynamic, the right tool is an orchestrator that holds a collection of machines and reacts to their state changes.

Short Answer: Yes, This Breaks a Fundamental Rule

In Harel Statecharts (the theoretical foundation for libraries like python-statemachine), parallel regions must be defined statically at design time. They are fixed orthogonal regions, not a dynamic list. You can't have "N copies of the same region" where N is a runtime value — that's simply outside the statechart formalism.

So your pseudo-code battles = [Battle, Battle, Battle] doesn't map to any valid statechart construct.

---

The Right Mental Model

What you're describing is actually dynamic orchestration, not parallel composition. The distinction:

Concept	Statechart Parallel State	Your Use Case
Regions defined	At design time	At runtime
Region count	Fixed	Variable (length of a list)
Semantics	Orthogonal AND-regions	N independent machines to coordinate

---

Practical Solution: Orchestration Pattern

The War machine orchestrates a dynamic list of Battle instances. It delegates to them and only advances when all have reached their final state.

from statemachine import StateMachine, State

# --- The sub-machine (one per item) ---

class Battle(StateMachine):
    fighting = State(initial=True)
    won      = State(final=True)

    victory = fighting.to(won)


# --- The orchestrating machine ---

class War(StateMachine):
    mobilizing = State(initial=True)
    at_war     = State()
    triumphant = State(final=True)

    declare_war  = mobilizing.to(at_war)
    declare_victory = at_war.to(triumphant)

    def __init__(self, num_battles: int):
        self.battles = [Battle() for _ in range(num_battles)]
        super().__init__()

    # Called by external code (or events) when a battle resolves
    def resolve_battle(self, index: int):
        if self.current_state != self.at_war:
            raise RuntimeError("War hasn't started yet.")

        battle = self.battles[index]
        if not battle.current_state.final:
            battle.victory()
            print(f"Battle {index} won!")

        if self._all_battles_done():
            self.declare_victory()

    def _all_battles_done(self) -> bool:
        return all(b.current_state.final for b in self.battles)


# --- Usage ---

war = War(num_battles=3)
war.declare_war()

war.resolve_battle(0)   # Battle 0 won!
war.resolve_battle(2)   # Battle 2 won!
war.resolve_battle(1)   # Battle 1 won! → triggers declare_victory

print(war.current_state)  # triumphant

---

Key Design Decisions Explained

Why not subclass or nest Battle inside War? python-statemachine does support compound states, but nesting them means the structure is fixed at class definition time. You'd have to hard-code battle_0, battle_1, battle_2 as separate named regions — defeating the purpose of a dynamic list.

Where should resolve_battle be called from? Wherever your business logic lives — an event loop, async tasks, callbacks, etc. The War machine is purely the coordinator; the trigger mechanism is up to you.

What if battles can also be lost? Just add a lost = State(final=True) and defeat = fighting.to(lost) to Battle, then check that outcome in _all_battles_done (or add a separate _any_battle_lost check that triggers a concede transition on War).

---