Package: pysimenv
python-sim-envpython-sim-envis a framework for performing numerical simulation of dynamic systems based on python.python-sim-envprovides several essential components including systems, controllers, and simulators. The motivation ofpython-sim-envcan be summarized asTo make easier to develop code for defining a new dynamic system, controller and simulation model.To make it easier to perform a simulation.To enhance re-usability of the already developed code.To require less computation time for performing a simulation.To provide a easy way to utilize simulation data.python-sim-envachieves the goal by:Clarifying the role of each component.Making sure that each component only contains its essential parts.Supporting various types of systems and various ways of writing code.Basic UsageExample 1: Step response of a linear systemIn this example, we will learn the following things.Defining a dynamic system.Performing a numerical simulation.Retrieving the simulation data.First, let's import modules required for the simulation.importnumpyasnpimportmatplotlib.pyplotaspltfrompysimenv.core.baseimportDynSystemfrompysimenv.core.simulatorimportSimulatorWe need aDynSystemobject for defining the linear system and aSimulatorfor performing the simulation.Consider the standard second-order system defined by a transfer function of
$$
G(s)=\frac{\omega_{n}^{2}}{s^{2} + 2\zeta\omega_{n} + \omega_{n}^{2}}
$$
where $\omega_{n}$ is the natural frequency and $\zeta$ is the damping ratio. The system can be expressed in state-space equation as
$$
\dot{x} = \begin{bmatrix}
0 & 1 \ -\omega_{n}^{2} & -2\zeta\omega_{n}
\end{bmatrix} x + \begin{bmatrix}
0 \ \omega_{n}^{2}
\end{bmatrix}u
$$
where $x=[x_{1},x_{2}]^{T}$ is the state and $u$ is the control input.Inside the main function, we define a function named asderiv_funrepresenting the right-hand side of the equation. We use values of $\omega_{n}=1$, $\zeta=0.8$.defderiv_fun(x,u):omega=1.zeta=0.8A=np.array([[0,1.],[-omega**2,-2*zeta*omega]])B=np.array([[0.],[omega**2]])x_dot=A.dot(x)+B.dot(u)return{'x':x_dot}We define a dynamic system object usingDynSystemclass where the initial state is set as $x(0)=[0,0]^{T}$.sys=DynSystem(initial_states={'x':np.zeros(2)},deriv_fun=deriv_fun)Then, we define a simulator and perform a numerical simulation with the integration interval $dt=0.01$, final time $t_{f}=10$, and unit step input for $u$.simulator=Simulator(sys)simulator.propagate(dt=0.01,time=10.,save_history=True,u=np.array([1.]))After the simulation, the time history, state history and input history can be retrieved ast = sys.history('t')
    x = sys.history('x')
    u = sys.history('u')where the output ofhistorymethod is returned innumpy.ndarray. The first axis of each array corresponds to the time index, and the second axis of each array corresponds to the state index. Therefore, we can visualize the simulation data asfig,ax=plt.subplots()foriinrange(2):ax.plot(t,x[:,i],label="x_"+str(i+1))ax.set_xlabel("Time (s)")ax.set_ylabel("x")ax.grid()ax.legend()fig,ax=plt.subplots()ax.plot(t,u)ax.set_xlabel("Time (s)")ax.set_ylabel("u")ax.grid()plt.show()The entire code is written asimportnumpyasnpimportmatplotlib.pyplotaspltfrompysimenv.core.baseimportDynSystemfrompysimenv.core.simulatorimportSimulatordefmain():defderiv_fun(x,u):omega=1.zeta=0.8A=np.array([[0,1.],[-omega**2,-2*zeta*omega]])B=np.array([[0.],[omega**2]])x_dot=A.dot(x)+B.dot(u)return{'x':x_dot}sys=DynSystem(initial_states={'x':np.zeros(2)},deriv_fun=deriv_fun)simulator=Simulator(sys)simulator.propagate(dt=0.01,time=10.,save_history=True,u=np.array([1.]))t=sys.history('t')x=sys.history('x')u=sys.history('u')fig,ax=plt.subplots()foriinrange(2):ax.plot(t,x[:,i],label="x_"+str(i+1))ax.set_xlabel("Time (s)")ax.set_ylabel("x")ax.grid()ax.legend()fig,ax=plt.subplots()ax.plot(t,u)ax.set_xlabel("Time (s)")ax.set_ylabel("u")ax.grid()plt.show()if__name__=="__main__":main()The following figures show the simulation result.Example 2: LQR(Linear  Quadratic Regulator) control of a linear system-Part 1In this example, we will learn the following things.Defining a closed-loop dynamic system.We begin with importing modules required for the simulation.importnumpyasnpimportscipy.linalgaslinfrompysimenv.core.baseimportDynSystem,SimObjectfrompysimenv.core.simulatorimportSimulatorDynSystemis used for defining a linear system, andSimObjectis used for defining the closed-loop system.Let us define the structure of the closed-loop system as a class inheriting fromSimObject.classClosedLoopSys(SimObject):def__init__(self):super(ClosedLoopSys,self).__init__()The open-loop system is defined as# open-loop systemzeta=0.1omega=1.A=np.array([[0.,1.],[-omega**2,-2*zeta*omega]])B=np.array([[0.],[omega**2]])self.linear_sys=DynSystem(initial_states={'x':[0.,1.]},deriv_fun=lambdax,u:{'x':A.dot(x)+B.dot(u)},name="linear_sys")The control gain is calculated as# control gainQ=np.identity(2)R=np.identity(1)P=lin.solve_continuous_are(A,B,Q,R)self.K=np.linalg.inv(R).dot(B.transpose().dot(P))Any instance ofany subclassofSimObjectdefined insideany subclassofSimObjectmust be added to the list of simulation objects at the initialization phase. (The list of subclasses inheritingSimObjectcan be found in Overview section.)DynSystemclass inheritsSimObject, which means thatself.linear_sysis also an instance ofSimObject. Therefore, addself.linear_sysasself._add_sim_objs([self.linear_sys])We define the feedback structure by implementing_forwardmethod.def_forward(self):x=self.linear_sys.state('x')u_lqr=-self.K.dot(x)self.linear_sys.forward(u=u_lqr)Now, we are ready to perform a simulation. The main function looks like:defmain():model=ClosedLoopSys()simulator=Simulator(model)simulator.propagate(dt=0.01,time=10.,save_history=True)model.linear_sys.default_plot(show=True)We useddefault_plotmethod defined inDynSystemto simply visualize the simulation result.The entire code is written asimportnumpyasnpimportscipy.linalgaslinfrompysimenv.core.baseimportDynSystem,SimObjectfrompysimenv.core.simulatorimportSimulatorclassClosedLoopSys(SimObject):def__init__(self):super(ClosedLoopSys,self).__init__()# open-loop systemzeta=0.1omega=1.A=np.array([[0.,1.],[-omega**2,-2*zeta*omega]])B=np.array([[0.],[omega**2]])self.linear_sys=DynSystem(initial_states={'x':[0.,1.]},deriv_fun=lambdax,u:{'x':A.dot(x)+B.dot(u)},name="linear_sys")# control gainQ=np.identity(2)R=np.identity(1)P=lin.solve_continuous_are(A,B,Q,R)self.K=np.linalg.inv(R).dot(B.transpose().dot(P))self._add_sim_objs([self.linear_sys])# implementdef_forward(self):x=self.linear_sys.state('x')u_lqr=-self.K.dot(x)self.linear_sys.forward(u=u_lqr)defmain():model=ClosedLoopSys()simulator=Simulator(model)simulator.propagate(dt=0.01,time=10.,save_history=True)model.linear_sys.default_plot(show=True)if__name__=="__main__":main()The following figures show the simulation result.Example 3: LQR(Linear  Quadratic Regulator) control of a linear system-Part 2In this example, we will learn the following things.Defining a controller usingStaticObject.Modifying the sampling interval of the controller.We begin with importing modules required for the simulation.importnumpyasnpimportscipy.linalgaslinfrompysimenv.core.baseimportStaticObject,SimObject,DynSystemfrompysimenv.core.simulatorimportSimulatorWe follow the same procedure as in Example 2. The difference is that now we use an object ofStaticObjectclass instead of simply defining a control gain.# controllerQ=np.identity(2)R=np.identity(1)P=lin.solve_continuous_are(A,B,Q,R)K=np.linalg.inv(R).dot(B.transpose().dot(P))self.lqr_control=StaticObject(interval=0.05,eval_fun=lambdax:-K.dot(x))To illustrate the usefulness ofStaticObjectclass, the sampling interval (intervalproperty) is intentionally set as 0.2(seconds) corresponding to sampling frequency of 5(Hz).DynSystemandStaticObjectboth inheritSimObjectclass. Therefore, add both the system objectself.linear_sysand controller objectself.lqr_controlto the list of simulation objects.self._add_sim_objs([self.linear_sys,self.lqr_control])Then, we define the system structure by implementing_forwardmethod.# implementdef_forward(self):x=self.linear_sys.state('x')u_lqr=self.lqr_control.forward(x=x)self.linear_sys.forward(u=u_lqr)The rest of the code is similar to that of Example 2. The entire code is written asimportnumpyasnpimportscipy.linalgaslinfrompysimenv.core.baseimportStaticObject,SimObject,DynSystemfrompysimenv.core.simulatorimportSimulatorclassClosedLoopSys(SimObject):def__init__(self):super(ClosedLoopSys,self).__init__()# open-loop systemzeta=0.1omega=1.A=np.array([[0.,1.],[-omega**2,-2*zeta*omega]])B=np.array([[0.],[omega**2]])self.linear_sys=DynSystem(initial_states={'x':[0.,1.]},deriv_fun=lambdax,u:{'x':A.dot(x)+B.dot(u)},name="linear_sys")# controllerQ=np.identity(2)R=np.identity(1)P=lin.solve_continuous_are(A,B,Q,R)K=np.linalg.inv(R).dot(B.transpose().dot(P))self.lqr_control=StaticObject(interval=0.2,eval_fun=lambdax:-K.dot(x))self._add_sim_objs([self.linear_sys,self.lqr_control])# implementdef_forward(self):x=self.linear_sys.state('x')u_lqr=self.lqr_control.forward(x=x)self.linear_sys.forward(u=u_lqr)defmain():model=ClosedLoopSys()simulator=Simulator(model)simulator.propagate(dt=0.01,time=10.,save_history=True)model.linear_sys.default_plot(show=True)if__name__=="__main__":main()The following figure shows the simulation result.Example 4: Simulation of a projectileIn this example, we will learn the following things.Defining a dynamic system with multiple state variables.Defining a stop condition for simulation.An object that is projected near the ground moves along a curved path under the action of gravity, which is called projectile motion. We examine the effect of air resistance to the projectile through numerical simulation.The equations of motion can be written as
$$
\begin{align*}
\dot{p} &= v \
\dot{v} &= a_{\text{grav}} + a_{\text{air}}
= \begin{bmatrix}
0 \ -g
\end{bmatrix} - \mu \Vert v \Vert v
\end{align*}
$$
where $p=[p_x, p_{y}]^{T}$ is the position, $v=[v_{x}, v_{y}]^{T}$ is the velocity, $g=9.807,(\rm{m/s^2})$ is the gravitational acceleration, and $\mu$ is a constant related to air resistance. $\mu$ is determined by
$$
\mu = \frac{c\rho A}{2m}
$$
where $c$ is the drag coefficient, $\rho$ is the air density, $A$ is the cross sectional area of the projectile, and $m$ is the mass of the projectile. A parameter set of $c=0.6$, $\rho=1.204 ,(\rm{kg/m^3})$, $A=0.065 ,(\rm{m^2})$, and $m=0.056, (\rm{kg})$ is used in the simulation, which approximately models the aerodynamic effect on the tennis ball. The resulting value of $\mu$ is $\mu=0.0214, (\rm{m^{-1}})$.ImportDynObjectclass frompysimenv.core.base.importnumpyasnpimportmatplotlib.pyplotaspltfrompysimenv.core.baseimportDynSystemfrompysimenv.core.simulatorimportSimulatorDefine a class calledProjectilethat inheritsDynSystem.classProjectile(DynSystem):def__init__(self,p_0,v_0,mu=0.):super(Projectile,self).__init__(initial_states={'p':p_0,'v':v_0})self.mu=muProjectileclass is defined to have two state variables with keyspandv, and no input variables. The equations of motion is translated into_derivmethod as# implementdef_deriv(self,p,v):p_dot=v.copy()v_dot=np.array([0.,-9.807])-self.mu*np.linalg.norm(v)*vreturn{'p':p_dot,'v':v_dot}We want to finish the simulation when an instance ofProjectilereaches the ground ($p_y < 0$). Therefore, implement_stop_conditionmethod as# implementdef_check_stop_condition(self):p_y=self.state('p')[1]returnp_y<0.Define a simulator and perform the numerical simulation in the main function. We perform the numerical simulation twice, one without considering any effect of the drag ($\mu=0$) and one with considering the effect of the drag ($\mu=0.0214$).defmain():mu_list={'no_drag':0.,'air':0.0214}data_list=dict()theta_0=np.deg2rad(30.)p_0=np.zeros(2)v_0=np.array([20.*np.cos(theta_0),20.*np.sin(theta_0)])forkey,muinmu_list.items():projectile=Projectile(p_0=p_0,v_0=v_0,mu=mu)simulator=Simulator(projectile)simulator.propagate(dt=0.01,time=10.,save_history=True)data=projectile.history('t','p','v')data_list[key]=dataAfter the simulation, the history of the time, position, and velocity is obtained by callinghistorymethod and passing the corresponding keys as arguments. Note thathistorymethod returns the data as a dictionary variable when more than one argument are passed.The entire code is written asimportnumpyasnpimportmatplotlib.pyplotaspltfrompysimenv.core.baseimportDynSystemfrompysimenv.core.simulatorimportSimulatorclassProjectile(DynSystem):def__init__(self,p_0,v_0,mu=0.):super(Projectile,self).__init__(initial_states={'p':p_0,'v':v_0})self.mu=mu# implementdef_deriv(self,p,v):p_dot=v.copy()v_dot=np.array([0.,-9.807])-self.mu*np.linalg.norm(v)*vreturn{'p':p_dot,'v':v_dot}# implementdef_check_stop_condition(self):p_y=self.state('p')[1]returnp_y<0.defmain():mu_list={'no_drag':0.,'air':0.0214}data_list=dict()theta_0=np.deg2rad(30.)p_0=np.zeros(2)v_0=np.array([20.*np.cos(theta_0),20.*np.sin(theta_0)])forkey,muinmu_list.items():projectile=Projectile(p_0=p_0,v_0=v_0,mu=mu)simulator=Simulator(projectile)simulator.propagate(dt=0.01,time=10.,save_history=True)data=projectile.history('t','p','v')data_list[key]=datacolor={'no_drag':'k','air':'b'}fig,ax=plt.subplots(3,1)forkeyindata_list.keys():data=data_list[key]ax[0].plot(data['p'][:,0],data['p'][:,1],color=color[key],label=key)ax[1].plot(data['t'],data['v'][:,0],color=color[key],label=key)ax[2].plot(data['t'],data['v'][:,1],color=color[key],label=key)ax[0].set_xlabel("Distance (m)")ax[0].set_ylabel("Height (m)")ax[0].set_title("Trajectory")ax[0].grid()ax[0].legend()ax[1].set_xlabel("Time (s)")ax[1].set_ylabel("v_x (m/s)")ax[1].set_title("Horizontal velocity")ax[1].grid()ax[1].legend()ax[2].set_xlabel("Time (s)")ax[2].set_ylabel("v_y (m/s)")ax[2].set_title("Vertical velocity")ax[2].grid()ax[2].legend()fig.tight_layout()plt.show()if__name__=="__main__":main()The following figures show the simulation result.Example 5: Cruise control of a vehicle using PI controlIn this example, we will learn the following things.Defining a controller with internal state.Logging history of a variable using aLoggerobject.The contents of this example is based on K. J. Astrom, 2002,Control System Design Lecture Notes for ME 155A, lecture notes, Simple Controllers, University of California.The purpose of the cruise control is to keep the speed of a car constant. We will define a model for simulating the cruise control of a car moving on the road. The dynamic model is modeled based on a momentum balance. Let $v$ denote the velocity (speed) of the car, $F$ the force generated by the engine, and $\theta$ the slope of the road. The momentum balance can be written as
$$
m\frac{dv}{dt}+cv = F - mg\theta
$$
where $m$ is the mass of the car, $c$ is the coefficient for air resistance, and $g$ is the gravitational acceleration. The equation can be rewritten as
$$
\frac{dv}{dt} = -\frac{c}{m}v + \frac{F}{m} - g\theta \
$$
Normalize each parameter and variable using the mass as
$$
\frac{dv}{dt} = -\hat{c}v + u - g\theta
$$
Values of parameters are $\hat{c}=0.02$, $g=9.81$. The control signal $u$ is limited to be in the interval $0 \le u \le 1$ and the slope of the road is assumed to be less than 10%, which corresponds to $\theta=0.1$.The following PI control law will be implemented
$$
u = k_{p}e + k_{i} \int_{0}^{t}e(\tau) ,d\tau
$$
where $e=v_{r} - v$ is the velocity error between the commanded velocity $v_{r}$ and actual velocity $v$.ImportSimObjectclass frompysimenv.core.base.importnumpyasnpimportmatplotlib.pyplotaspltfrompysimenv.core.baseimportSimObject,DynSystemfrompysimenv.core.simulatorimportSimulatorDefine a classPIControllerthat inherits fromSimObjectclass.PIControllerclass is defined to have a state named ase_ibecause we need to keep track the integral value of the error. The initial integral value is set as zero.classPIController(SimObject):def__init__(self,k_p,k_i):super(PIController,self).__init__()self._add_state_vars(e_i=np.array([0.]))self.k_p=k_pself.k_i=k_iThe_forwardmethod of the class is written as# implementdef_forward(self,e):self.state_vars['e_i'].set_deriv(deriv=e)e_i=self.state('e_i')u_pi=self.k_p*e+self.k_i*e_ireturnu_piNote thatset_derivmethod of the state variable should be called at each time when_forwardmethod is called as in the following to properly update the integral value.self.state_vars['e_i'].set_deriv(deriv=e)Now define the closed-loop system. The closed-loop system includes the open-loop dynamic model of the car and the PI controller.classCCCar(SimObject):"""Cruise-controlled car"""def__init__(self,k_p,k_i,v_0):super(CCCar,self).__init__()# mass-normalized parametersc=0.02g=9.81defderiv_fun(v,u,theta):v_dot=-c*v+u-g*thetareturn{'v':v_dot}self.vel_dyn=DynSystem(initial_states={'v':v_0},deriv_fun=deriv_fun)# PI Controllerself.pi_control=PIController(k_p=k_p,k_i=k_i)self._add_sim_objs([self.vel_dyn,self.pi_control])Implement_forwardmethod of the closed-loop system.# implementdef_forward(self,v_r,theta):# tracking errorv=self.vel_dyn.state('v')e=v_r-v# PI control inputu_pi=self.pi_control.forward(e=e)u=np.clip(u_pi,0.,1.)# update dynamicself.vel_dyn.forward(u=u,theta=theta)# log velocity error and control signalself._logger.append(t=self.time,e=e,u=u)The reference speedv_rand the slope of the roadthetaare passed from the outside of the system. The PI control inputu_piis clipped to have a value between 0 and 1. A property named as_loggeris used for logging the history of the time, velocity error, and control signal as in the following.# log velocity error and control signalself._logger.append(t=self.time,e=e,u=u)_loggerproperty is aLoggerobject defined in every instance ofSimObjectclass. The history of any variable can be logged just by callingappendmethod and passing the corresponding key-value as an argument.To determine the appropriate value fork_pandk_i, derive the equation for the error dynamics. Assuming that $v_{r}$ is constant and using the relation $e=v_{r}-v$, the error dynamics can be expressed as
$$
\dot{e} + \left(\hat{c} + k_{p} \right)e + k_{i} \int_{0}^{t}e(\tau),d\tau=g\theta + \hat{c}v_{r}
$$
The characteristic polynomial of the closed-loop system is
$$
s^{2} + \left(\hat{c} + k_{p} \right)s + k_{i} = 0
$$
Specify the desired response of the closed-loop system by choosing the value of natural frequency $\omega_{0}$ and damping ratio $\zeta$. Then, choose values of  $k_{p}$ and $k_{i}$ as
$$
k_{p} = 2\zeta\omega_{0} - \hat{c},, k_{i} = \omega_{0}^{2}
$$
We are ready to code the main function. The main function simulates the controller for various values of $\omega_{0}=0.05, 0.1, 0.2$ with $\zeta=1$ and compare the results. The initial velocity and reference velocity of the car is set as 5(m/s). The slope of the road is assumed to suddenly change by 4% from a flat surface. The following code is portion of the main function.defmain():zeta=1.omega_0_list=[0.05,0.1,0.2]v_r=5.theta=0.04# 4% slopedata_list=[]foromega_0inomega_0_list:k_p=2*zeta*omega_0-0.02k_i=omega_0**2car=CCCar(k_p=k_p,k_i=k_i,v_0=v_r)simulator=Simulator(car)simulator.propagate(dt=0.01,time=100,save_history=True,v_r=v_r,theta=theta)data=car.history('t','e','u')# returns dictionary when the number of variable is greater than 1data_list.append(data)After each simulation, the history of the time, velocity error, and control signal is obtained by callinghistorymethod and passing the corresponding keys as arguments.historymethod returns a dictionary variable when the number of arguments is greater than 1.data=car.history('t','e','u')# returns dictionary when the number of variable is greater than 1The entire code is written asimportnumpyasnpimportmatplotlib.pyplotaspltfrompysimenv.core.baseimportSimObject,DynSystemfrompysimenv.core.simulatorimportSimulatorclassPIController(SimObject):def__init__(self,k_p,k_i):super(PIController,self).__init__()self._add_state_vars(e_i=np.array([0.]))self.k_p=k_pself.k_i=k_i# implementdef_forward(self,e):self.state_vars['e_i'].set_deriv(deriv=e)e_i=self.state('e_i')u_pi=self.k_p*e+self.k_i*e_ireturnu_piclassCCCar(SimObject):"""Cruise-controlled car"""def__init__(self,k_p,k_i,v_0):super(CCCar,self).__init__()# mass-normalized parametersc=0.02g=9.81defderiv_fun(v,u,theta):v_dot=-c*v+u-g*thetareturn{'v':v_dot}self.vel_dyn=DynSystem(initial_states={'v':v_0},deriv_fun=deriv_fun)# PI Controllerself.pi_control=PIController(k_p=k_p,k_i=k_i)self._add_sim_objs([self.vel_dyn,self.pi_control])# implementdef_forward(self,v_r,theta):# tracking errorv=self.vel_dyn.state('v')e=v_r-v# PI control inputu_pi=self.pi_control.forward(e=e)u=np.clip(u_pi,0.,1.)# update dynamicself.vel_dyn.forward(u=u,theta=theta)# log velocity error and control signalself._logger.append(t=self.time,e=e,u=u)defmain():zeta=1.omega_0_list=[0.05,0.1,0.2]v_r=5.theta=0.04# 4% slopedata_list=[]foromega_0inomega_0_list:k_p=2*zeta*omega_0-0.02k_i=omega_0**2car=CCCar(k_p=k_p,k_i=k_i,v_0=v_r)simulator=Simulator(car)simulator.propagate(dt=0.01,time=100,save_history=True,v_r=v_r,theta=theta)data=car.history('t','e','u')# returns dictionary when the number of variable is greater than 1data_list.append(data)fig,ax=plt.subplots(2,1)lines=[':','-','--']foriinrange(3):data=data_list[i]ax[0].plot(data['t'],data['e'],color='b',linestyle=lines[i])ax[1].plot(data['t'],data['u'],color='b',linestyle=lines[i])ax[0].set_xlabel("Time")ax[0].set_ylabel("Velocity error")ax[1].set_xlabel("Time")ax[1].set_ylabel("Control signal")ax[0].set_xticks(np.linspace(0.,100.,11))ax[0].set_yticks(np.linspace(0.,4.,5))ax[1].set_xticks(np.linspace(0.,100.,11))ax[1].set_yticks(np.linspace(0.,0.6,7))fig.tight_layout()plt.show()if__name__=="__main__":main()The following figures show the simulation result.The dotted line is for the case where $\omega_{0}=0.05$, the full line is for $\omega_{0}=0.1$, and the dashed line is for $\omega_{0}=0.2$.OverviewImportant classes and methodsMain components for modeling dynamic systems are summarized in the following diagram. Only the essential attributes and methods are listed in the figure. Mostly used attributes and methods when modeling dynamic systems are expressed in bold font.System classes inheritingSimObjectareStaticObject,DynSystem,TimeVaryingDynSystem.