From 1e0c26c1ded7684d0da2f8695b17417cfbebe923 Mon Sep 17 00:00:00 2001 From: Shunichi09 Date: Sun, 3 May 2020 12:01:48 +0900 Subject: [PATCH] Add: Quick start guide --- .../configs/__init__.py | 6 ++ .../controllers/__init__.py | 14 ++++ PythonLinearNonlinearControl/envs/__init__.py | 8 ++ .../models/__init__.py | 6 ++ .../planners/__init__.py | 4 + .../plotters/__init__.py | 4 + .../plotters/animator.py | 13 ++- .../runners/__init__.py | 2 + README.md | 83 +++++++++++++++---- scripts/quickstart/quickstart.md | 52 ++++++++++++ scripts/simple_run.py | 2 +- 11 files changed, 175 insertions(+), 19 deletions(-) create mode 100644 scripts/quickstart/quickstart.md diff --git a/PythonLinearNonlinearControl/configs/__init__.py b/PythonLinearNonlinearControl/configs/__init__.py index e69de29..50a079f 100644 --- a/PythonLinearNonlinearControl/configs/__init__.py +++ b/PythonLinearNonlinearControl/configs/__init__.py @@ -0,0 +1,6 @@ +from PythonLinearNonlinearControl.configs.cartpole \ + import CartPoleConfigModule # NOQA +from PythonLinearNonlinearControl.configs.first_order_lag \ + import FirstOrderLagConfigModule # NOQA +from PythonLinearNonlinearControl.configs.two_wheeled \ + import TwoWheeledConfigModule # NOQA \ No newline at end of file diff --git a/PythonLinearNonlinearControl/controllers/__init__.py b/PythonLinearNonlinearControl/controllers/__init__.py index e69de29..e86efff 100644 --- a/PythonLinearNonlinearControl/controllers/__init__.py +++ b/PythonLinearNonlinearControl/controllers/__init__.py @@ -0,0 +1,14 @@ +from PythonLinearNonlinearControl.controllers.cem \ + import CEM # NOQA +from PythonLinearNonlinearControl.controllers.mppi \ + import MPPI # NOQA +from PythonLinearNonlinearControl.controllers.mppi_williams \ + import MPPIWilliams # NOQA +from PythonLinearNonlinearControl.controllers.random \ + import RandomShooting # NOQA +from PythonLinearNonlinearControl.controllers.ilqr \ + import iLQR # NOQA +from PythonLinearNonlinearControl.controllers.ddp \ + import DDP # NOQA +from PythonLinearNonlinearControl.controllers.mpc \ + import LinearMPC # NOQA \ No newline at end of file diff --git a/PythonLinearNonlinearControl/envs/__init__.py b/PythonLinearNonlinearControl/envs/__init__.py index e69de29..837b5d8 100644 --- a/PythonLinearNonlinearControl/envs/__init__.py +++ b/PythonLinearNonlinearControl/envs/__init__.py @@ -0,0 +1,8 @@ +from PythonLinearNonlinearControl.envs.cartpole \ + import CartPoleEnv # NOQA +from PythonLinearNonlinearControl.envs.first_order_lag \ + import FirstOrderLagEnv # NOQA +from PythonLinearNonlinearControl.envs.two_wheeled \ + import TwoWheeledConstEnv # NOQA +from PythonLinearNonlinearControl.envs.two_wheeled \ + import TwoWheeledTrackEnv # NOQA \ No newline at end of file diff --git a/PythonLinearNonlinearControl/models/__init__.py b/PythonLinearNonlinearControl/models/__init__.py index e69de29..0c95ac6 100644 --- a/PythonLinearNonlinearControl/models/__init__.py +++ b/PythonLinearNonlinearControl/models/__init__.py @@ -0,0 +1,6 @@ +from PythonLinearNonlinearControl.models.cartpole \ + import CartPoleModel # NOQA +from PythonLinearNonlinearControl.models.first_order_lag \ + import FirstOrderLagModel # NOQA +from PythonLinearNonlinearControl.models.two_wheeled \ + import TwoWheeledModel # NOQA \ No newline at end of file diff --git a/PythonLinearNonlinearControl/planners/__init__.py b/PythonLinearNonlinearControl/planners/__init__.py index e69de29..3e1cc4f 100644 --- a/PythonLinearNonlinearControl/planners/__init__.py +++ b/PythonLinearNonlinearControl/planners/__init__.py @@ -0,0 +1,4 @@ +from PythonLinearNonlinearControl.planners.const_planner \ + import ConstantPlanner # NOQA +from PythonLinearNonlinearControl.planners.closest_point_planner \ + import ClosestPointPlanner # NOQA \ No newline at end of file diff --git a/PythonLinearNonlinearControl/plotters/__init__.py b/PythonLinearNonlinearControl/plotters/__init__.py index e69de29..e385584 100644 --- a/PythonLinearNonlinearControl/plotters/__init__.py +++ b/PythonLinearNonlinearControl/plotters/__init__.py @@ -0,0 +1,4 @@ +from PythonLinearNonlinearControl.plotters.animator \ + import Animator +from PythonLinearNonlinearControl.plotters.plot_func \ + import plot_results \ No newline at end of file diff --git a/PythonLinearNonlinearControl/plotters/animator.py b/PythonLinearNonlinearControl/plotters/animator.py index 8446229..14cf14e 100644 --- a/PythonLinearNonlinearControl/plotters/animator.py +++ b/PythonLinearNonlinearControl/plotters/animator.py @@ -10,12 +10,17 @@ logger = getLogger(__name__) class Animator(): """ animation class """ - def __init__(self, args, env): + def __init__(self, env, args=None): """ """ - self.env_name = args.env - self.result_dir = args.result_dir - self.controller_type = args.controller_type + self.env_name = "Env" + self.result_dir = "./result" + self.controller_type = "controller" + + if args is not None: + self.env_name = args.env + self.result_dir = args.result_dir + self.controller_type = args.controller_type self.interval = env.config["dt"] * 1000. # to ms self.plot_func = env.plot_func diff --git a/PythonLinearNonlinearControl/runners/__init__.py b/PythonLinearNonlinearControl/runners/__init__.py index e69de29..8fd5521 100644 --- a/PythonLinearNonlinearControl/runners/__init__.py +++ b/PythonLinearNonlinearControl/runners/__init__.py @@ -0,0 +1,2 @@ +from PythonLinearNonlinearControl.runners.runner \ + import ExpRunner # NOQA \ No newline at end of file diff --git a/README.md b/README.md index 06fb0d3..80ddcf5 100644 --- a/README.md +++ b/README.md @@ -3,9 +3,9 @@ [![GitHub issues open](https://img.shields.io/github/issues/Shunichi09/PythonLinearNonlinearControl.svg)]() [![Build Status](https://travis-ci.org/Shunichi09/PythonLinearNonlinearControl.svg?branch=master&service=github)](https://travis-ci.org/Shunichi09/PythonLinearNonlinearControl) -# PythonLinearNonLinearControl +# PythonLinearNonlinearControl -PythonLinearNonLinearControl is a library implementing the linear and nonlinear control theories in python. +PythonLinearNonlinearControl is a library implementing the linear and nonlinear control theories in python. Due to use only basic libralies (scipy, numpy), this library is easy to extend for your own situations.
@@ -78,7 +78,7 @@ All states and inputs of environments are continuous. You could know abount our environmets more in [Environments.md](Environments.md) -# Usage +# Installation ## To install this package @@ -104,16 +104,6 @@ or pip install -e . ``` -## Run Experiments - -You can run the experiments as follows: - -``` -python scripts/simple_run.py --env FirstOrderLag --controller CEM -``` - -**figures and animations are saved in the ./result folder.** - # Basic concepts When we design control systems, we should have **Model**, **Planner**, **Controller** and **Runner** as shown in the figure. @@ -141,6 +131,71 @@ Runner runs the simulation. Please, see more detail in each scripts. +# Getting started + +## [QuickStart Guide](scripts/quickstart/quickstart.md) + +This is a quickstart guide for users who just want to try PythonLinearNonlinearControl. +If you have not installed PythonLinearNonLinearControl, please see the section of "how to setup" in README.md + +When we design control systems, we should have Environment, Model, Planner, Controller and Runner. +Therefore your script contains those Modules. + +First, import each Modules from PythonLinearNonlinearControl. + +```py +from PythonLinearNonlinearControl import configs +from PythonLinearNonlinearControl import envs +from PythonLinearNonlinearControl import models +from PythonLinearNonlinearControl import planners +from PythonLinearNonlinearControl import controllers +from PythonLinearNonlinearControl import runners +``` + +Configs contains each modules configurations such as cost functions, prediction length, ...etc. + +Then you can make each module. (This is example about CEM and CartPole env) + +```py +config = configs.CartPoleConfigModule() +env = envs.CartPoleEnv() +model = models.CartPoleModel(config) +planner = controllers.CEM(config, model) +runner = planners.ConstantPlanner(config) +controller = runners.ExpRunner() +``` + +The preparation for experiment has done! +Please run the runner. + +```py +history_x, history_u, history_g = runner.run(env, controller, planner) +``` + +You can get the results of history of state, history of input and history of goal. +Use that histories to visualize the Animation or Figures. +(Note FirstOrderEnv does not support animation) + +```py +# plot results +plot_results(args, history_x, history_u, history_g=history_g) +save_plot_data(args, history_x, history_u, history_g=history_g) + +# create animation +animator = Animator(args, env) +animator.draw(history_x, history_g) +``` + +## Run Experiments + +You can run the experiments as follows: + +``` +python scripts/simple_run.py --env CartPole --controller CEM --save_anim 1 +``` + +**figures and animations are saved in the ./result folder.** + # Old version If you are interested in the old version of this library, that was not a library just examples, please see [v1.0](https://github.com/Shunichi09/PythonLinearNonlinearControl/tree/v1.0) @@ -168,4 +223,4 @@ author = {Shunichi Sekiguchi}, title = {PythonLinearNonlinearControl}, note = "\url{https://github.com/Shunichi09/PythonLinearNonlinearControl}", } -``` +``` \ No newline at end of file diff --git a/scripts/quickstart/quickstart.md b/scripts/quickstart/quickstart.md new file mode 100644 index 0000000..2c936e8 --- /dev/null +++ b/scripts/quickstart/quickstart.md @@ -0,0 +1,52 @@ +# PythonLinearnNonlinearControl Quickstart Guide + +This is a quickstart guide for users who just want to try PythonLinearNonlinearControl. +If you have not installed PythonLinearNonLinearControl, please see the section of "how to setup" in README.md + +When we design control systems, we should have Environment, Model, Planner, Controller and Runner. +Therefore your script contains those Modules. + +First, import each Modules from PythonLinearNonlinearControl. + +```py +from PythonLinearNonlinearControl import configs +from PythonLinearNonlinearControl import envs +from PythonLinearNonlinearControl import models +from PythonLinearNonlinearControl import planners +from PythonLinearNonlinearControl import controllers +from PythonLinearNonlinearControl import runners +``` + +Configs contains each modules configurations such as cost functions, prediction length, ...etc. + +Then you can make each module. (This is example about CEM and CartPole env) + +```py +config = configs.CartPoleConfigModule() +env = envs.CartPoleEnv() +model = models.CartPoleModel(config) +planner = controllers.CEM(config, model) +runner = planners.ConstantPlanner(config) +controller = runners.ExpRunner() +``` + +The preparation for experiment has done! +Please run the runner. + +```py +history_x, history_u, history_g = runner.run(env, controller, planner) +``` + +You can get the results of history of state, history of input and history of goal. +Use that histories to visualize the Animation or Figures. +(Note FirstOrderEnv does not support animation) + +```py +# plot results +plot_results(args, history_x, history_u, history_g=history_g) +save_plot_data(args, history_x, history_u, history_g=history_g) + +# create animation +animator = Animator(args, env) +animator.draw(history_x, history_g) +``` \ No newline at end of file diff --git a/scripts/simple_run.py b/scripts/simple_run.py index 4181f8f..b049075 100644 --- a/scripts/simple_run.py +++ b/scripts/simple_run.py @@ -41,7 +41,7 @@ def run(args): save_plot_data(args, history_x, history_u, history_g=history_g) if args.save_anim: - animator = Animator(args, env) + animator = Animator(env, args=args) animator.draw(history_x, history_g) def main():