Skip to content

Engine

engine

Abstract class for Engines to evolve Dynamic Systems.

EngineABC(runner=_no_run_func)

Bases: ABC

Abstract class for Engines to evolve Dynamic Systems.

Initialize an EngineABC from a runner function.

Parameters:

Name Type Description Default
runner EngineProtocol

The runner function for the engine. Defaults to a function that raises NotImplementedError.

 _no_run_func
Source code in src/flepimop2/engine/abc.py 
28
29
30
31
32
33
34
35
36
def __init__(self, runner: EngineProtocol = _no_run_func) -> None:
    """
    Initialize an `EngineABC` from a runner function.

    Args:
        runner: The runner function for the engine. Defaults to a function that
            raises `NotImplementedError`.
    """
    self._runner = runner

run(system, eval_times, initial_state, params, **kwargs)

Run the engine with the provided system and parameters.

Parameters:

Name Type Description Default
system SystemABC

The dynamic system to be evolved.

 required
eval_times NDArray[float64]

Array of time points for evaluation.

 required
initial_state NDArray[float64]

The initial state array.

 required
params dict[str, Any]

Additional parameters for the stepper.

 required
**kwargs Any

Additional keyword arguments for the engine.

 {}

Returns:

Type Description
NDArray[float64]

The evolved time x state array.
Source code in src/flepimop2/engine/abc.py 
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
def run(
    self,
    system: SystemABC,
    eval_times: NDArray[np.float64],
    initial_state: NDArray[np.float64],
    params: dict[str, Any],
    **kwargs: Any,
) -> NDArray[np.float64]:
    """
    Run the engine with the provided system and parameters.

    Args:
        system: The dynamic system to be evolved.
        eval_times: Array of time points for evaluation.
        initial_state: The initial state array.
        params: Additional parameters for the stepper.
        **kwargs: Additional keyword arguments for the engine.

    Returns:
        The evolved time x state array.
    """
    return self._runner(
        system.stepper,
        eval_times,
        initial_state,
        params,
        **kwargs,
    )

EngineProtocol

Bases: Protocol

Type-definition (Protocol) for engine runner functions.

__call__(stepper, times, state, params, **kwargs)

Protocol for engine runner functions.

Parameters:

Name Type Description Default
stepper SystemProtocol

The system stepper function.

 required
times NDArray[float64]

Array of time points.

 required
state NDArray[float64]

The current state array.

 required
params dict[str, Any]

Additional parameters for the stepper.

 required
**kwargs Any

Additional keyword arguments for the engine.

 {}

Returns:

Type Description
NDArray[float64]

The evolved time x state array.
Source code in src/flepimop2/engine/protocol.py 
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
def __call__(
    self,
    stepper: SystemProtocol,
    times: NDArray[np.float64],
    state: NDArray[np.float64],
    params: dict[str, Any],
    **kwargs: Any,
) -> NDArray[np.float64]:
    """
    Protocol for engine runner functions.

    Args:
        stepper: The system stepper function.
        times: Array of time points.
        state: The current state array.
        params: Additional parameters for the stepper.
        **kwargs: Additional keyword arguments for the engine.

    Returns:
        The evolved time x state array.
    """
    ...

build(config)

Build a EngineABC from a configuration dictionary.

Parameters:

Name Type Description Default
config dict[str, Any] | EngineProtocol

Configuration dictionary or a EngineProtocol. In dict mode, it contains a 'module' key, it will be used to lookup the Engine module path. The module will have "flepimop2.engine." prepended.

 required

Returns:

Type Description
EngineABC

The constructed engine instance.

Raises:

Type Description
TypeError

If the built engine is not an instance of EngineABC.
Source code in src/flepimop2/engine/abc.py 
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
def build(config: dict[str, Any] | EngineProtocol) -> EngineABC:
    """Build a `EngineABC` from a configuration dictionary.

    Args:
        config: Configuration dictionary or a EngineProtocol. In dict mode, it contains
            a 'module' key, it will be used to lookup the Engine module path. The module
            will have "flepimop2.engine." prepended.

    Returns:
        The constructed engine instance.

    Raises:
        TypeError: If the built engine is not an instance of EngineABC.
    """
    if isinstance(config, EngineProtocol):
        return EngineABC(config)
    builder = _load_builder(f"flepimop2.engine.{config.pop('module', 'wrapper')}")
    engine = builder.build(**config)
    if not isinstance(engine, EngineABC):
        msg = "The built engine is not an instance of EngineABC."
        raise TypeError(msg)
    return engine

abc

Abstract class for Engines to evolve Dynamic Systems.

EngineABC(runner=_no_run_func)

Bases: ABC

Abstract class for Engines to evolve Dynamic Systems.

Initialize an EngineABC from a runner function.

Parameters:

Name Type Description Default
runner EngineProtocol

The runner function for the engine. Defaults to a function that raises NotImplementedError.

 _no_run_func
Source code in src/flepimop2/engine/abc.py 
28
29
30
31
32
33
34
35
36
def __init__(self, runner: EngineProtocol = _no_run_func) -> None:
    """
    Initialize an `EngineABC` from a runner function.

    Args:
        runner: The runner function for the engine. Defaults to a function that
            raises `NotImplementedError`.
    """
    self._runner = runner
run(system, eval_times, initial_state, params, **kwargs)

Run the engine with the provided system and parameters.

Parameters:

Name Type Description Default
system SystemABC

The dynamic system to be evolved.

 required
eval_times NDArray[float64]

Array of time points for evaluation.

 required
initial_state NDArray[float64]

The initial state array.

 required
params dict[str, Any]

Additional parameters for the stepper.

 required
**kwargs Any

Additional keyword arguments for the engine.

 {}

Returns:

Type Description
NDArray[float64]

The evolved time x state array.
Source code in src/flepimop2/engine/abc.py 
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
def run(
    self,
    system: SystemABC,
    eval_times: NDArray[np.float64],
    initial_state: NDArray[np.float64],
    params: dict[str, Any],
    **kwargs: Any,
) -> NDArray[np.float64]:
    """
    Run the engine with the provided system and parameters.

    Args:
        system: The dynamic system to be evolved.
        eval_times: Array of time points for evaluation.
        initial_state: The initial state array.
        params: Additional parameters for the stepper.
        **kwargs: Additional keyword arguments for the engine.

    Returns:
        The evolved time x state array.
    """
    return self._runner(
        system.stepper,
        eval_times,
        initial_state,
        params,
        **kwargs,
    )

build(config)

Build a EngineABC from a configuration dictionary.

Parameters:

Name Type Description Default
config dict[str, Any] | EngineProtocol

Configuration dictionary or a EngineProtocol. In dict mode, it contains a 'module' key, it will be used to lookup the Engine module path. The module will have "flepimop2.engine." prepended.

 required

Returns:

Type Description
EngineABC

The constructed engine instance.

Raises:

Type Description
TypeError

If the built engine is not an instance of EngineABC.
Source code in src/flepimop2/engine/abc.py 
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
def build(config: dict[str, Any] | EngineProtocol) -> EngineABC:
    """Build a `EngineABC` from a configuration dictionary.

    Args:
        config: Configuration dictionary or a EngineProtocol. In dict mode, it contains
            a 'module' key, it will be used to lookup the Engine module path. The module
            will have "flepimop2.engine." prepended.

    Returns:
        The constructed engine instance.

    Raises:
        TypeError: If the built engine is not an instance of EngineABC.
    """
    if isinstance(config, EngineProtocol):
        return EngineABC(config)
    builder = _load_builder(f"flepimop2.engine.{config.pop('module', 'wrapper')}")
    engine = builder.build(**config)
    if not isinstance(engine, EngineABC):
        msg = "The built engine is not an instance of EngineABC."
        raise TypeError(msg)
    return engine

protocol

Type-definition (Protocol) for engine runner functions.

EngineProtocol

Bases: Protocol

Type-definition (Protocol) for engine runner functions.

__call__(stepper, times, state, params, **kwargs)

Protocol for engine runner functions.

Parameters:

Name Type Description Default
stepper SystemProtocol

The system stepper function.

 required
times NDArray[float64]

Array of time points.

 required
state NDArray[float64]

The current state array.

 required
params dict[str, Any]

Additional parameters for the stepper.

 required
**kwargs Any

Additional keyword arguments for the engine.

 {}

Returns:

Type Description
NDArray[float64]

The evolved time x state array.
Source code in src/flepimop2/engine/protocol.py 
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
def __call__(
    self,
    stepper: SystemProtocol,
    times: NDArray[np.float64],
    state: NDArray[np.float64],
    params: dict[str, Any],
    **kwargs: Any,
) -> NDArray[np.float64]:
    """
    Protocol for engine runner functions.

    Args:
        stepper: The system stepper function.
        times: Array of time points.
        state: The current state array.
        params: Additional parameters for the stepper.
        **kwargs: Additional keyword arguments for the engine.

    Returns:
        The evolved time x state array.
    """
    ...

wrapper

A EngineABC which wraps a user-defined script file.

WrapperEngine(script)

Bases: EngineABC

A EngineABC which wraps a user-defined script file.

Initialize a WrapperEngine from a script file.

Parameters:

Name Type Description Default
script PathLike[str]

Path to a script file which defines a 'runner' function.

 required

Raises:

Type Description
AttributeError

If the module does not have a valid 'runner' function.
Source code in src/flepimop2/engine/wrapper.py 
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
def __init__(self, script: PathLike[str]) -> None:
    """
    Initialize a `WrapperEngine` from a script file.

    Args:
        script: Path to a script file which defines a 'runner' function.

    Raises:
        AttributeError: If the module does not have a valid 'runner' function.
    """
    mod = _load_module(script, "flepimop2.engine.wrapped")
    if not _validate_function(mod, "runner"):
        msg = f"Module at {script} does not have a valid 'runner' function."
        raise AttributeError(msg)
    super().__init__(mod.runner)

build(script)

Build a WrapperEngine from a configuration arguments.

Parameters:

Name Type Description Default
script PathLike[str]

Path to a script file which defines a 'runner' function.

 required

Returns:

Type Description
WrapperEngine

The constructed wrapper engine instance.
Source code in src/flepimop2/engine/wrapper.py 
29
30
31
32
33
34
35
36
37
38
39
def build(script: PathLike[str]) -> WrapperEngine:
    """
    Build a `WrapperEngine` from a configuration arguments.

    Args:
        script: Path to a script file which defines a 'runner' function.

    Returns:
        The constructed wrapper engine instance.
    """
    return WrapperEngine(script)