API Reference¶

The generated API reference is built from the curated public namespaces in the Python source. The top-level namespace is the preferred import surface for common workflows; the frontend namespace groups the same semantic modeling constructors under their layer-specific package.

Top-Level API¶

`pydgens` ¶

Public API for PYDGENS.

The top-level namespace provides the preferred constructors for common modeling and solving workflows. Lower-level namespaces such as pydgens.frontend remain available when users want to organize imports by API layer.

`time_grid(*, nt, dt, t0=0.0)` ¶

Create a uniform time grid for a dynamic game.

A TimeGrid defines the discrete times at which the game dynamics, controls, strategies, costs, and constraints are evaluated.

The grid contains nt time points:

t0, t0 + dt, t0 + 2 dt, ..., t0 + (nt - 1) dt

This corresponds to nt-1 steps in the grid. i.e. nsteps = nt-1

Parameters:

Name	Type	Description	Default
`nt`	`int`	Number of discrete time points in the grid. Must be greater than zero. If `nt` states are stored along a trajectory, then there are typically `nt - 1` control intervals between them.	required
`dt`	`float`	Time step between consecutive grid points. Must be greater than zero.	required
`t0`	`float`	Initial time. Defaults to `0.0`.	`0.0`

Returns:

Type	Description
`TimeGrid`	Validated time-grid object used by control systems and games.

Examples:

>>> tg = time_grid(nt=51, dt=0.1)
>>> tg.nt
51
>>> tg.dt
0.1

For a one-stage game with an initial and final state:

>>> tg = time_grid(nt=2, dt=1.0)

`linear_dynamics(*, A, B)` ¶

Create continuous-time linear dynamics for a dynamic game.

The dynamics are defined in joint state and joint control coordinates:

``dx/dt = A x + B u``

Parameters:

Name	Type	Description	Default
`A`	`ndarray`	State matrix with shape `(nx, nx)`, where `nx` is the joint state dimension.	required
`B`	`ndarray`	Control matrix with shape `(nx, nu)`, where `nu` is the joint control dimension.	required

Returns:

Type	Description
`LTIContinuousSystem`	Continuous-time linear time-invariant system with inferred joint state and control dimensions.

Examples:

A scalar system with two players, each controlling one scalar input:

>>> dyn = linear_dynamics(
...     A=jnp.array([[0.0]]),
...     B=jnp.array([[1.0, 1.0]]),
... )
>>> dyn.nx
1
>>> dyn.nu
2

`nonlinear_dynamics(*, nx, nu, dynamics)` ¶

Create continuous-time nonlinear dynamics for a dynamic game.

The dynamics callable is defined in joint state and joint control coordinates:

``dx/dt = f(t, x, u)``

Parameters:

Name	Type	Description	Default
`nx`	`int`	Joint state dimension. Must be positive.	required
`nu`	`int`	Joint control dimension. Must be positive.	required
`dynamics`		Callable of the form `dynamics(t, x, u) -> dxdt`. The callable receives scalar time `t`, joint state `x` with shape `(nx,)`, and joint control `u` with shape `(nu,)`. It must return the state derivative with shape `(nx,)`. Time invariance is not assumed at the frontend layer, which keeps this interface aligned with common ODE-solver conventions.	required

Returns:

Type	Description
`NonlinearContinuousSystem`	Continuous-time nonlinear system with fixed joint state and joint control dimensions.

`player_cost(*, running, terminal=None)` ¶

Create a continuous-time player cost from user-provided callables.

Use this factory for nonlinear games when a player's running and terminal costs are easiest to express as Python callables. The returned object stores those callables in frontend form and lowers them to solver IR when a game is solved.

Parameters:

Name	Type	Description	Default
`running`		Running cost callable of the form: ``running(t, x, u_joint) -> scalar`` The callable receives scalar time `t`, joint state `x`, and the full joint control vector `u_joint`.	required
`terminal`		Optional terminal cost callable of the form: ``terminal(t, x) -> scalar``	`None`

Returns:

Type	Description
`ContinuousPlayerCost`	Generic continuous-time player cost object suitable for nonlinear frontend games.

Notes

The frontend nonlinear-cost contract is intentionally narrower than the lower-level IR: running costs are defined over the joint control vector, just as quadratic frontend costs are. Structural conditions such as player-wise control separability are validated later at the game/solver layer, where player ownership information is available.

`quadratic_cost(*, nx, nu, state_weights=None, state_indices=None, state_target=None, terminal_state_weights=None, terminal_state_indices=None, terminal_state_target=None, control_weights=None, control_indices=None, control_target=None)` ¶

Create a quadratic player cost using semantic frontend arguments.

This factory defines diagonal quadratic running and terminal costs over the joint state and joint control spaces. It is the recommended entry point for linear-quadratic games whose penalties can be described by scalar weights.

Conceptually, the returned cost represents:

``(x - x_ref)^T Qp (x - x_ref)``
``+ (u - u_ref)^T Rp (u - u_ref)``
``+ (x_T - x_ref_terminal)^T Qp_terminal (x_T - x_ref_terminal)``

where Qp, Rp, and Qp_terminal are diagonal matrices built from the provided weights.

Parameters:

Name	Type	Description	Default
`nx`	`int`	Joint state dimension.	required
`nu`	`int`	Joint control dimension.	required
`state_weights`		Optional weights for quadratic state terms. Weights may be positive or negative. If `state_indices` is omitted, this must have length `nx`.	`None`
`state_indices`	`list[int] \| None`	Optional joint-state indices to penalize. If omitted, the state weights apply to all state dimensions.	`None`
`state_target`		Optional desired joint-state reference `x_ref`.	`None`
`terminal_state_weights`		Optional weights for terminal quadratic state terms. Weights may be positive or negative. If `terminal_state_indices` is omitted, this must have length `nx`.	`None`
`terminal_state_indices`	`list[int] \| None`	Optional joint-state indices to penalize at the terminal state. If omitted, the terminal state weights apply to all state dimensions.	`None`
`terminal_state_target`		Optional desired terminal joint-state reference `x_ref_terminal`.	`None`
`control_weights`		Optional nonnegative weights for quadratic control penalties. If `control_indices` is omitted, this must have length `nu`.	`None`
`control_indices`	`list[int] \| None`	Optional joint-control indices to penalize. If omitted, the control weights apply to all control dimensions.	`None`
`control_target`		Optional desired joint-control reference `u_ref`.	`None`

Returns:

Type	Description
`QuadraticPlayerCost`	Configured quadratic player cost object.

`matrix_quadratic_cost(*, nx, nu, state_matrix=None, state_target=None, terminal_state_matrix=None, terminal_state_target=None, control_matrix=None, control_target=None)` ¶

Create an advanced quadratic player cost from explicit full matrices.

This is the LQ companion to quadratic_cost(...) for games that need coupled state terms such as ||p_guard - alpha p_bandit||^2 or indefinite state rewards/penalties. The simpler quadratic_cost(...) remains the recommended beginner-facing factory for diagonal weights.

Parameters:

Name	Type	Description	Default
`nx`	`int`	Joint state dimension. Must be positive.	required
`nu`	`int`	Joint control dimension. Must be positive.	required
`state_matrix`		Optional joint-state running cost matrix with shape `(nx, nx)`. The matrix must be symmetric and may be indefinite when supported by the downstream solver.	`None`
`state_target`		Optional desired joint-state reference with shape `(nx,)`.	`None`
`terminal_state_matrix`		Optional joint-state terminal cost matrix with shape `(nx, nx)`. The matrix must be symmetric and may be indefinite when supported by the downstream solver.	`None`
`terminal_state_target`		Optional desired terminal joint-state reference with shape `(nx,)`.	`None`
`control_matrix`		Optional joint-control running cost matrix with shape `(nu, nu)`. The matrix must be symmetric positive semidefinite.	`None`
`control_target`		Optional desired joint-control reference with shape `(nu,)`.	`None`

Returns:

Type	Description
`QuadraticPlayerCost`	Configured quadratic player cost object.

`control_bounds(*, lower=None, upper=None, indices=None, steps=None)` ¶

Create path-wise bounds on the joint control vector.

Bounds may apply to selected joint-control dimensions and selected control intervals. For example, this can express constraints such as:

``-1 <= u[0] <= 1``
``-2 <= u[1] <= 2``

over some or all control intervals.

Parameters:

Name	Type	Description	Default
`lower`		Lower bounds for the selected control dimensions. May be a scalar or a length-matched sequence. `None` means no lower bound.	`None`
`upper`		Upper bounds for the selected control dimensions. May be a scalar or a length-matched sequence. `None` means no upper bound.	`None`
`indices`	`Sequence[int] \| None`	Joint-control indices to constrain. If omitted, the bounds apply to all joint-control dimensions when lowered against a game.	`None`
`steps`	`Sequence[int] \| None`	Optional control-interval indices where the bounds are active. If omitted, the bounds apply on all control intervals.	`None`

Returns:

Type	Description
`ControlBounds`	Frontend control-bound specification suitable for `constraint_set(...)`.

`state_bounds(*, lower=None, upper=None, indices=None, steps=None, include_terminal=True)` ¶

Create bounds on the joint state vector.

Bounds may apply to selected joint-state dimensions and selected path intervals. For example, this can express constraints such as:

``px >= 0``
``-5 <= v <= 5``

with the option to also enforce the same bound at the terminal state.

Parameters:

Name	Type	Description	Default
`lower`		Lower bounds for the selected state dimensions. May be a scalar or a length-matched sequence. `None` means no lower bound.	`None`
`upper`		Upper bounds for the selected state dimensions. May be a scalar or a length-matched sequence. `None` means no upper bound.	`None`
`indices`	`Sequence[int] \| None`	Joint-state indices to constrain. If omitted, the bounds apply to all joint-state dimensions when lowered against a game.	`None`
`steps`	`Sequence[int] \| None`	Optional control-interval indices where the path portion of the bounds is active. If omitted, the bounds apply on all control intervals.	`None`
`include_terminal`	`bool`	Whether the same bounds should also be enforced at the terminal node.	`True`

Returns:

Type	Description
`StateBounds`	Frontend state-bound specification suitable for `constraint_set(...)`.

`constraint_set(*items)` ¶

Bundle frontend constraint specifications into a single set.

Parameters:

Name	Type	Description	Default
`*items`	`AbstractConstraintSpec`	Constraint specifications such as `control_bounds(...)` or `state_bounds(...)`.	`()`

Returns:

Type	Description
`ConstraintSet`	Frontend constraint collection that can be passed to `game(...)`.

Examples:

>>> cons = constraint_set(
...     control_bounds(lower=-1.0, upper=1.0, indices=[0]),
...     state_bounds(lower=0.0, indices=[1]),
... )

`player(*, cost, joint_ctrl_slice, name=None, state_view=None)` ¶

Create a frontend player object from semantic inputs.

A player owns a contiguous slice of the joint control vector and carries the cost model used to evaluate that player's objective. This factory chooses the most specific known frontend player type compatible with the supplied cost object.

Current dispatch rules

QuadraticPlayerCost -> LQPlayer
any other AbstractPlayerCost -> generic Player

Parameters:

Name	Type	Description	Default
`cost`	`AbstractPlayerCost`	Player-specific frontend cost model created by `player_cost(...)`, `quadratic_cost(...)`, or another frontend cost factory.	required
`joint_ctrl_slice`	`SliceLike`	Contiguous block of the joint control vector owned by this player. This may be a `slice(start, stop)` or a length-2 sequence such as `(start, stop)`.	required
`name`	`str \| None`	Optional player name used for diagnostics and solution access.	`None`
`state_view`	`Sequence[int] \| None`	Optional joint-state indices associated with this player for plotting and diagnostics. This is metadata only; it does not imply state ownership.	`None`

Returns:

Type	Description
`AbstractPlayer`	The most specific known frontend player object compatible with `cost`.

Notes

This factory intentionally hides some frontend type selection from beginners. For example, quadratic costs currently imply an LQPlayer because that is the structurally appropriate frontend player type for linear-quadratic games.

Advanced users may still instantiate Player or LQPlayer directly when they want precise control over the concrete type.

`game(*, tg, dynamics, players, constraints=None, discretization='zoh')` ¶

Create a frontend game object from semantic modeling inputs.

A game combines a time grid, dynamics, players, and optional constraints into the semantic object consumed by solve(...). This factory chooses the most specific known frontend game type compatible with the supplied modeling ingredients.

Current dispatch rules

LTIContinuousSystem with all LQPlayer objects -> LQGame
NonlinearContinuousSystem with all generic Player objects backed by ContinuousPlayerCost -> NonlinearGame
same nonlinear ingredients plus ConstraintSet -> ConstrainedNonlinearGame

Parameters:

Name	Type	Description	Default
`tg`	`TimeGrid`	Time grid used to sample the game, usually created by `time_grid(...)`.	required
`dynamics`		Frontend dynamics object created by `linear_dynamics(...)` or `nonlinear_dynamics(...)`.	required
`players`	`Sequence`	Sequence of frontend player objects created by `player(...)`. Player control slices must be contiguous, ordered, and cover the full joint control vector.	required
`constraints`	`ConstraintSet \| None`	Optional frontend constraint set. Supplying constraints currently selects the constrained nonlinear frontend game path.	`None`
`discretization`	`Literal['zoh', 'euler']`	Method used to discretize continuous-time dynamics when lowering to solver IR. Currently relevant for `LQGame` construction.	`'zoh'`

Returns:

Type	Description
`object`	Frontend game object compatible with the supplied inputs and suitable for `solve(...)`.

Notes

This factory intentionally hides some frontend type selection from beginners. For example, linear continuous-time dynamics together with quadratic players currently imply LQGame because that is the structurally appropriate frontend game type for that combination.

Advanced users may still instantiate concrete game classes directly when they want precise control over the frontend type.

`solve(game, *, x0=None, method='auto', op0=None, al_state0=None, **solver_kwargs)` ¶

Solve a frontend or IR game object using the appropriate solver family.

This is the primary solver entry point for user-facing workflows. It accepts a semantic frontend game, lowers it to solver IR when needed, chooses a solver family, and returns a normalized solution bundle.

Current dispatch rules

LQGame or LinearQuadraticGameType1 -> LQ solver
NonlinearGame or NonlinearGameType1 -> iLQ solver
ConstrainedNonlinearGame or NonlinearGameType2 -> Augmented Lagrangian solver

Parameters:

Name	Type	Description	Default
`game`		Frontend or IR game object to solve.	required
`x0`		Optional initial joint state. This is required for iLQ solves, and for AL solves unless the caller provides `op0` directly. For LQ, this is optional; if provided, the frontend will propagate the returned feedback strategy from `x0` to produce a trajectory.	`None`
`method`	`SolveMethod`	Solver family selection. `"auto"` infers the method from the game type. Explicit choices are currently `"lq"`, `"ilq"`, and `"al"`.	`'auto'`
`op0`	`FixedStepPrimalDualTrajectory \| None`	Optional initial primal-dual trajectory for the AL solver.	`None`
`al_state0`	`JointAugmentedLagrangianState \| None`	Optional initial augmented Lagrangian state for the AL solver.	`None`
`**solver_kwargs`		Additional keyword arguments forwarded to the selected low-level solver implementation.	`{}`

Returns:

Type	Description
`SolveResult`	Minimal normalized frontend solution bundle.

Notes

This wrapper focuses on:

method dispatch
lowering frontend games to IR when needed
simple default initialization for AL solves
returning a consistent top-level container

Solver-family structural assumptions still matter:

iLQ currently expects unconstrained nonlinear games whose running costs are defined over the JOINT control vector and whose declared control structure is compatible with the LQ approximation solved inside iLQ. In practice, that means no GENERAL mixed-control block structure across player-owned control partitions.
AL currently expects constrained nonlinear games whose running costs are expressed in each player's LOCAL control variables and are LOCAL_ONLY by control structure.

Higher-level conveniences such as named player-control access, plotting hooks, and richer solver logs can be layered on top of this normalized result without changing the basic dispatch contract.

Frontend API¶

`frontend` ¶

Frontend semantic modeling API for PYDGENS.

The :mod:pydgens.frontend namespace collects the higher-level modeling objects and convenience constructors used to define and solve games before they are lowered into solver-facing IR objects.

Most users can import these same constructors directly from pydgens. This namespace exists for users who want the frontend API grouped under its own subpackage.

`time_grid(*, nt, dt, t0=0.0)` ¶

Create a uniform time grid for a dynamic game.

A TimeGrid defines the discrete times at which the game dynamics, controls, strategies, costs, and constraints are evaluated.

The grid contains nt time points:

t0, t0 + dt, t0 + 2 dt, ..., t0 + (nt - 1) dt

This corresponds to nt-1 steps in the grid. i.e. nsteps = nt-1

Parameters:

Name	Type	Description	Default
`nt`	`int`	Number of discrete time points in the grid. Must be greater than zero. If `nt` states are stored along a trajectory, then there are typically `nt - 1` control intervals between them.	required
`dt`	`float`	Time step between consecutive grid points. Must be greater than zero.	required
`t0`	`float`	Initial time. Defaults to `0.0`.	`0.0`

Returns:

Type	Description
`TimeGrid`	Validated time-grid object used by control systems and games.

Examples:

>>> tg = time_grid(nt=51, dt=0.1)
>>> tg.nt
51
>>> tg.dt
0.1

For a one-stage game with an initial and final state:

>>> tg = time_grid(nt=2, dt=1.0)

`constraint_set(*items)` ¶

Bundle frontend constraint specifications into a single set.

Parameters:

Name	Type	Description	Default
`*items`	`AbstractConstraintSpec`	Constraint specifications such as `control_bounds(...)` or `state_bounds(...)`.	`()`

Returns:

Type	Description
`ConstraintSet`	Frontend constraint collection that can be passed to `game(...)`.

Examples:

>>> cons = constraint_set(
...     control_bounds(lower=-1.0, upper=1.0, indices=[0]),
...     state_bounds(lower=0.0, indices=[1]),
... )

`control_bounds(*, lower=None, upper=None, indices=None, steps=None)` ¶

Create path-wise bounds on the joint control vector.

Bounds may apply to selected joint-control dimensions and selected control intervals. For example, this can express constraints such as:

``-1 <= u[0] <= 1``
``-2 <= u[1] <= 2``

over some or all control intervals.

Parameters:

Name	Type	Description	Default
`lower`		Lower bounds for the selected control dimensions. May be a scalar or a length-matched sequence. `None` means no lower bound.	`None`
`upper`		Upper bounds for the selected control dimensions. May be a scalar or a length-matched sequence. `None` means no upper bound.	`None`
`indices`	`Sequence[int] \| None`	Joint-control indices to constrain. If omitted, the bounds apply to all joint-control dimensions when lowered against a game.	`None`
`steps`	`Sequence[int] \| None`	Optional control-interval indices where the bounds are active. If omitted, the bounds apply on all control intervals.	`None`

Returns:

Type	Description
`ControlBounds`	Frontend control-bound specification suitable for `constraint_set(...)`.

`state_bounds(*, lower=None, upper=None, indices=None, steps=None, include_terminal=True)` ¶

Create bounds on the joint state vector.

Bounds may apply to selected joint-state dimensions and selected path intervals. For example, this can express constraints such as:

``px >= 0``
``-5 <= v <= 5``

with the option to also enforce the same bound at the terminal state.

Parameters:

Name	Type	Description	Default
`lower`		Lower bounds for the selected state dimensions. May be a scalar or a length-matched sequence. `None` means no lower bound.	`None`
`upper`		Upper bounds for the selected state dimensions. May be a scalar or a length-matched sequence. `None` means no upper bound.	`None`
`indices`	`Sequence[int] \| None`	Joint-state indices to constrain. If omitted, the bounds apply to all joint-state dimensions when lowered against a game.	`None`
`steps`	`Sequence[int] \| None`	Optional control-interval indices where the path portion of the bounds is active. If omitted, the bounds apply on all control intervals.	`None`
`include_terminal`	`bool`	Whether the same bounds should also be enforced at the terminal node.	`True`

Returns:

Type	Description
`StateBounds`	Frontend state-bound specification suitable for `constraint_set(...)`.

`matrix_quadratic_cost(*, nx, nu, state_matrix=None, state_target=None, terminal_state_matrix=None, terminal_state_target=None, control_matrix=None, control_target=None)` ¶

Create an advanced quadratic player cost from explicit full matrices.

This is the LQ companion to quadratic_cost(...) for games that need coupled state terms such as ||p_guard - alpha p_bandit||^2 or indefinite state rewards/penalties. The simpler quadratic_cost(...) remains the recommended beginner-facing factory for diagonal weights.

Parameters:

Name	Type	Description	Default
`nx`	`int`	Joint state dimension. Must be positive.	required
`nu`	`int`	Joint control dimension. Must be positive.	required
`state_matrix`		Optional joint-state running cost matrix with shape `(nx, nx)`. The matrix must be symmetric and may be indefinite when supported by the downstream solver.	`None`
`state_target`		Optional desired joint-state reference with shape `(nx,)`.	`None`
`terminal_state_matrix`		Optional joint-state terminal cost matrix with shape `(nx, nx)`. The matrix must be symmetric and may be indefinite when supported by the downstream solver.	`None`
`terminal_state_target`		Optional desired terminal joint-state reference with shape `(nx,)`.	`None`
`control_matrix`		Optional joint-control running cost matrix with shape `(nu, nu)`. The matrix must be symmetric positive semidefinite.	`None`
`control_target`		Optional desired joint-control reference with shape `(nu,)`.	`None`

Returns:

Type	Description
`QuadraticPlayerCost`	Configured quadratic player cost object.

`player_cost(*, running, terminal=None)` ¶

Create a continuous-time player cost from user-provided callables.

Use this factory for nonlinear games when a player's running and terminal costs are easiest to express as Python callables. The returned object stores those callables in frontend form and lowers them to solver IR when a game is solved.

Parameters:

Name	Type	Description	Default
`running`		Running cost callable of the form: ``running(t, x, u_joint) -> scalar`` The callable receives scalar time `t`, joint state `x`, and the full joint control vector `u_joint`.	required
`terminal`		Optional terminal cost callable of the form: ``terminal(t, x) -> scalar``	`None`

Returns:

Type	Description
`ContinuousPlayerCost`	Generic continuous-time player cost object suitable for nonlinear frontend games.

Notes

The frontend nonlinear-cost contract is intentionally narrower than the lower-level IR: running costs are defined over the joint control vector, just as quadratic frontend costs are. Structural conditions such as player-wise control separability are validated later at the game/solver layer, where player ownership information is available.

`quadratic_cost(*, nx, nu, state_weights=None, state_indices=None, state_target=None, terminal_state_weights=None, terminal_state_indices=None, terminal_state_target=None, control_weights=None, control_indices=None, control_target=None)` ¶

Create a quadratic player cost using semantic frontend arguments.

This factory defines diagonal quadratic running and terminal costs over the joint state and joint control spaces. It is the recommended entry point for linear-quadratic games whose penalties can be described by scalar weights.

Conceptually, the returned cost represents:

``(x - x_ref)^T Qp (x - x_ref)``
``+ (u - u_ref)^T Rp (u - u_ref)``
``+ (x_T - x_ref_terminal)^T Qp_terminal (x_T - x_ref_terminal)``

where Qp, Rp, and Qp_terminal are diagonal matrices built from the provided weights.

Parameters:

Name	Type	Description	Default
`nx`	`int`	Joint state dimension.	required
`nu`	`int`	Joint control dimension.	required
`state_weights`		Optional weights for quadratic state terms. Weights may be positive or negative. If `state_indices` is omitted, this must have length `nx`.	`None`
`state_indices`	`list[int] \| None`	Optional joint-state indices to penalize. If omitted, the state weights apply to all state dimensions.	`None`
`state_target`		Optional desired joint-state reference `x_ref`.	`None`
`terminal_state_weights`		Optional weights for terminal quadratic state terms. Weights may be positive or negative. If `terminal_state_indices` is omitted, this must have length `nx`.	`None`
`terminal_state_indices`	`list[int] \| None`	Optional joint-state indices to penalize at the terminal state. If omitted, the terminal state weights apply to all state dimensions.	`None`
`terminal_state_target`		Optional desired terminal joint-state reference `x_ref_terminal`.	`None`
`control_weights`		Optional nonnegative weights for quadratic control penalties. If `control_indices` is omitted, this must have length `nu`.	`None`
`control_indices`	`list[int] \| None`	Optional joint-control indices to penalize. If omitted, the control weights apply to all control dimensions.	`None`
`control_target`		Optional desired joint-control reference `u_ref`.	`None`

Returns:

Type	Description
`QuadraticPlayerCost`	Configured quadratic player cost object.

`linear_dynamics(*, A, B)` ¶

Create continuous-time linear dynamics for a dynamic game.

The dynamics are defined in joint state and joint control coordinates:

``dx/dt = A x + B u``

Parameters:

Name	Type	Description	Default
`A`	`ndarray`	State matrix with shape `(nx, nx)`, where `nx` is the joint state dimension.	required
`B`	`ndarray`	Control matrix with shape `(nx, nu)`, where `nu` is the joint control dimension.	required

Returns:

Type	Description
`LTIContinuousSystem`	Continuous-time linear time-invariant system with inferred joint state and control dimensions.

Examples:

A scalar system with two players, each controlling one scalar input:

>>> dyn = linear_dynamics(
...     A=jnp.array([[0.0]]),
...     B=jnp.array([[1.0, 1.0]]),
... )
>>> dyn.nx
1
>>> dyn.nu
2

`nonlinear_dynamics(*, nx, nu, dynamics)` ¶

Create continuous-time nonlinear dynamics for a dynamic game.

The dynamics callable is defined in joint state and joint control coordinates:

``dx/dt = f(t, x, u)``

Parameters:

Name	Type	Description	Default
`nx`	`int`	Joint state dimension. Must be positive.	required
`nu`	`int`	Joint control dimension. Must be positive.	required
`dynamics`		Callable of the form `dynamics(t, x, u) -> dxdt`. The callable receives scalar time `t`, joint state `x` with shape `(nx,)`, and joint control `u` with shape `(nu,)`. It must return the state derivative with shape `(nx,)`. Time invariance is not assumed at the frontend layer, which keeps this interface aligned with common ODE-solver conventions.	required

Returns:

Type	Description
`NonlinearContinuousSystem`	Continuous-time nonlinear system with fixed joint state and joint control dimensions.

`game(*, tg, dynamics, players, constraints=None, discretization='zoh')` ¶

Create a frontend game object from semantic modeling inputs.

A game combines a time grid, dynamics, players, and optional constraints into the semantic object consumed by solve(...). This factory chooses the most specific known frontend game type compatible with the supplied modeling ingredients.

Current dispatch rules

LTIContinuousSystem with all LQPlayer objects -> LQGame
NonlinearContinuousSystem with all generic Player objects backed by ContinuousPlayerCost -> NonlinearGame
same nonlinear ingredients plus ConstraintSet -> ConstrainedNonlinearGame

Parameters:

Name	Type	Description	Default
`tg`	`TimeGrid`	Time grid used to sample the game, usually created by `time_grid(...)`.	required
`dynamics`		Frontend dynamics object created by `linear_dynamics(...)` or `nonlinear_dynamics(...)`.	required
`players`	`Sequence`	Sequence of frontend player objects created by `player(...)`. Player control slices must be contiguous, ordered, and cover the full joint control vector.	required
`constraints`	`ConstraintSet \| None`	Optional frontend constraint set. Supplying constraints currently selects the constrained nonlinear frontend game path.	`None`
`discretization`	`Literal['zoh', 'euler']`	Method used to discretize continuous-time dynamics when lowering to solver IR. Currently relevant for `LQGame` construction.	`'zoh'`

Returns:

Type	Description
`object`	Frontend game object compatible with the supplied inputs and suitable for `solve(...)`.

Notes

This factory intentionally hides some frontend type selection from beginners. For example, linear continuous-time dynamics together with quadratic players currently imply LQGame because that is the structurally appropriate frontend game type for that combination.

Advanced users may still instantiate concrete game classes directly when they want precise control over the frontend type.

`player(*, cost, joint_ctrl_slice, name=None, state_view=None)` ¶

Create a frontend player object from semantic inputs.

A player owns a contiguous slice of the joint control vector and carries the cost model used to evaluate that player's objective. This factory chooses the most specific known frontend player type compatible with the supplied cost object.

Current dispatch rules

QuadraticPlayerCost -> LQPlayer
any other AbstractPlayerCost -> generic Player

Parameters:

Name	Type	Description	Default
`cost`	`AbstractPlayerCost`	Player-specific frontend cost model created by `player_cost(...)`, `quadratic_cost(...)`, or another frontend cost factory.	required
`joint_ctrl_slice`	`SliceLike`	Contiguous block of the joint control vector owned by this player. This may be a `slice(start, stop)` or a length-2 sequence such as `(start, stop)`.	required
`name`	`str \| None`	Optional player name used for diagnostics and solution access.	`None`
`state_view`	`Sequence[int] \| None`	Optional joint-state indices associated with this player for plotting and diagnostics. This is metadata only; it does not imply state ownership.	`None`

Returns:

Type	Description
`AbstractPlayer`	The most specific known frontend player object compatible with `cost`.

Notes

This factory intentionally hides some frontend type selection from beginners. For example, quadratic costs currently imply an LQPlayer because that is the structurally appropriate frontend player type for linear-quadratic games.

Advanced users may still instantiate Player or LQPlayer directly when they want precise control over the concrete type.

`solve(game, *, x0=None, method='auto', op0=None, al_state0=None, **solver_kwargs)` ¶

Solve a frontend or IR game object using the appropriate solver family.

This is the primary solver entry point for user-facing workflows. It accepts a semantic frontend game, lowers it to solver IR when needed, chooses a solver family, and returns a normalized solution bundle.

Current dispatch rules

LQGame or LinearQuadraticGameType1 -> LQ solver
NonlinearGame or NonlinearGameType1 -> iLQ solver
ConstrainedNonlinearGame or NonlinearGameType2 -> Augmented Lagrangian solver

Parameters:

Name	Type	Description	Default
`game`		Frontend or IR game object to solve.	required
`x0`		Optional initial joint state. This is required for iLQ solves, and for AL solves unless the caller provides `op0` directly. For LQ, this is optional; if provided, the frontend will propagate the returned feedback strategy from `x0` to produce a trajectory.	`None`
`method`	`SolveMethod`	Solver family selection. `"auto"` infers the method from the game type. Explicit choices are currently `"lq"`, `"ilq"`, and `"al"`.	`'auto'`
`op0`	`FixedStepPrimalDualTrajectory \| None`	Optional initial primal-dual trajectory for the AL solver.	`None`
`al_state0`	`JointAugmentedLagrangianState \| None`	Optional initial augmented Lagrangian state for the AL solver.	`None`
`**solver_kwargs`		Additional keyword arguments forwarded to the selected low-level solver implementation.	`{}`

Returns:

Type	Description
`SolveResult`	Minimal normalized frontend solution bundle.

Notes

This wrapper focuses on:

method dispatch
lowering frontend games to IR when needed
simple default initialization for AL solves
returning a consistent top-level container

Solver-family structural assumptions still matter:

iLQ currently expects unconstrained nonlinear games whose running costs are defined over the JOINT control vector and whose declared control structure is compatible with the LQ approximation solved inside iLQ. In practice, that means no GENERAL mixed-control block structure across player-owned control partitions.
AL currently expects constrained nonlinear games whose running costs are expressed in each player's LOCAL control variables and are LOCAL_ONLY by control structure.

Higher-level conveniences such as named player-control access, plotting hooks, and richer solver logs can be layered on top of this normalized result without changing the basic dispatch contract.

API Reference¶

Top-Level API¶

pydgens ¶

time_grid(*, nt, dt, t0=0.0) ¶

linear_dynamics(*, A, B) ¶

nonlinear_dynamics(*, nx, nu, dynamics) ¶

player_cost(*, running, terminal=None) ¶

quadratic_cost(*, nx, nu, state_weights=None, state_indices=None, state_target=None, terminal_state_weights=None, terminal_state_indices=None, terminal_state_target=None, control_weights=None, control_indices=None, control_target=None) ¶

matrix_quadratic_cost(*, nx, nu, state_matrix=None, state_target=None, terminal_state_matrix=None, terminal_state_target=None, control_matrix=None, control_target=None) ¶

control_bounds(*, lower=None, upper=None, indices=None, steps=None) ¶

state_bounds(*, lower=None, upper=None, indices=None, steps=None, include_terminal=True) ¶

constraint_set(*items) ¶

player(*, cost, joint_ctrl_slice, name=None, state_view=None) ¶

game(*, tg, dynamics, players, constraints=None, discretization='zoh') ¶

solve(game, *, x0=None, method='auto', op0=None, al_state0=None, **solver_kwargs) ¶

Frontend API¶

frontend ¶

time_grid(*, nt, dt, t0=0.0) ¶

constraint_set(*items) ¶

control_bounds(*, lower=None, upper=None, indices=None, steps=None) ¶

state_bounds(*, lower=None, upper=None, indices=None, steps=None, include_terminal=True) ¶

matrix_quadratic_cost(*, nx, nu, state_matrix=None, state_target=None, terminal_state_matrix=None, terminal_state_target=None, control_matrix=None, control_target=None) ¶

player_cost(*, running, terminal=None) ¶

quadratic_cost(*, nx, nu, state_weights=None, state_indices=None, state_target=None, terminal_state_weights=None, terminal_state_indices=None, terminal_state_target=None, control_weights=None, control_indices=None, control_target=None) ¶

linear_dynamics(*, A, B) ¶

nonlinear_dynamics(*, nx, nu, dynamics) ¶

game(*, tg, dynamics, players, constraints=None, discretization='zoh') ¶

player(*, cost, joint_ctrl_slice, name=None, state_view=None) ¶

solve(game, *, x0=None, method='auto', op0=None, al_state0=None, **solver_kwargs) ¶

`pydgens` ¶

`time_grid(*, nt, dt, t0=0.0)` ¶

`linear_dynamics(*, A, B)` ¶

`nonlinear_dynamics(*, nx, nu, dynamics)` ¶

`player_cost(*, running, terminal=None)` ¶

`quadratic_cost(*, nx, nu, state_weights=None, state_indices=None, state_target=None, terminal_state_weights=None, terminal_state_indices=None, terminal_state_target=None, control_weights=None, control_indices=None, control_target=None)` ¶

`matrix_quadratic_cost(*, nx, nu, state_matrix=None, state_target=None, terminal_state_matrix=None, terminal_state_target=None, control_matrix=None, control_target=None)` ¶

`control_bounds(*, lower=None, upper=None, indices=None, steps=None)` ¶

`state_bounds(*, lower=None, upper=None, indices=None, steps=None, include_terminal=True)` ¶

`constraint_set(*items)` ¶

`player(*, cost, joint_ctrl_slice, name=None, state_view=None)` ¶

`game(*, tg, dynamics, players, constraints=None, discretization='zoh')` ¶

`solve(game, *, x0=None, method='auto', op0=None, al_state0=None, **solver_kwargs)` ¶

`frontend` ¶

`time_grid(*, nt, dt, t0=0.0)` ¶

`constraint_set(*items)` ¶

`control_bounds(*, lower=None, upper=None, indices=None, steps=None)` ¶

`state_bounds(*, lower=None, upper=None, indices=None, steps=None, include_terminal=True)` ¶

`matrix_quadratic_cost(*, nx, nu, state_matrix=None, state_target=None, terminal_state_matrix=None, terminal_state_target=None, control_matrix=None, control_target=None)` ¶

`player_cost(*, running, terminal=None)` ¶

`quadratic_cost(*, nx, nu, state_weights=None, state_indices=None, state_target=None, terminal_state_weights=None, terminal_state_indices=None, terminal_state_target=None, control_weights=None, control_indices=None, control_target=None)` ¶

`linear_dynamics(*, A, B)` ¶

`nonlinear_dynamics(*, nx, nu, dynamics)` ¶

`game(*, tg, dynamics, players, constraints=None, discretization='zoh')` ¶

`player(*, cost, joint_ctrl_slice, name=None, state_view=None)` ¶

`solve(game, *, x0=None, method='auto', op0=None, al_state0=None, **solver_kwargs)` ¶