Problem: The current code (e.g., simulate_multistage.jl) bundles simulation, parameter-setting, and manual differentiation logic in a single file. Functions use generic vector arguments (state_param_in/out) and manually coded rrules, making it difficult for new users to understand or extend the package.
Proposed solution:
-
Separate modules: Create submodules within DecisionRules.jl (e.g., Simulation, Policies, Training). Move simulate_multistage and helper functions into a dedicated Simulation module. Similarly, group neural network–related functions in a Policies module.
-
Define clear types: Introduce typed structs for the problem (e.g., DecisionRuleProblem) encapsulating state variables, control variables, constraints, and cost functions. A DecisionRulePolicy struct can wrap the neural network or linear rule.
-
Expose high‑level functions: Provide a high‑level API, such as simulate(problem, policy, initial_state, uncertainties), that hides internal parameter-setting and solver calls. Users should not need to manipulate subproblem parameters manually.
-
Docstrings and examples: Add comprehensive docstrings for each public function and provide minimal working examples in the examples/ folder (e.g., the battery test case).
-
Testing: Add unit tests covering the new high‑level functions, ensuring they match the current logic and outputs.
-
Documentation: Fix readme and possibly also add documentation already.
Problem: The current code (e.g.,
simulate_multistage.jl) bundles simulation, parameter-setting, and manual differentiation logic in a single file. Functions use generic vector arguments (state_param_in/out) and manually coded rrules, making it difficult for new users to understand or extend the package.Proposed solution:
Separate modules: Create submodules within
DecisionRules.jl(e.g.,Simulation,Policies,Training). Movesimulate_multistageand helper functions into a dedicatedSimulationmodule. Similarly, group neural network–related functions in aPoliciesmodule.Define clear types: Introduce typed structs for the problem (e.g.,
DecisionRuleProblem) encapsulating state variables, control variables, constraints, and cost functions. ADecisionRulePolicystruct can wrap the neural network or linear rule.Expose high‑level functions: Provide a high‑level API, such as
simulate(problem, policy, initial_state, uncertainties), that hides internal parameter-setting and solver calls. Users should not need to manipulate subproblem parameters manually.Docstrings and examples: Add comprehensive docstrings for each public function and provide minimal working examples in the
examples/folder (e.g., the battery test case).Testing: Add unit tests covering the new high‑level functions, ensuring they match the current logic and outputs.
Documentation: Fix readme and possibly also add documentation already.