define environment

Author: thowell

README.md

@@ -85,7 +85,7 @@ pkg> add Dojo#main
 
 ## Citing
 ```
-@article{howell2022dojo,
+@article{howelllecleach2022dojo,
 	title={Dojo: {A} {D}ifferentiable {S}imulator for {R}obotics},
 	author={Howell, Taylor A. and Le Cleac'h, Simon and Kolter, J. Zico and Schwager, Mac and Manchester, Zachary},
 	year={2022}

docs/make.jl

@@ -1,6 +1,6 @@
 push!(LOAD_PATH, "../src/")
 
-using Documenter#, Dojo
+using Documenter, Dojo
 
 makedocs(
     modules = [Dojo],

docs/src/citing.md

@@ -2,7 +2,7 @@
 
 If you find Dojo useful in your project, we kindly request that you cite the following paper:
 ```
-@article{howell2022dojo,
+@article{howelllecleach2022dojo,
 	title={Dojo: {A} {D}ifferentiable {S}imulator for {R}obotics},
 	author={Howell, Taylor A. and Le Cleac'h, Simon and and Kolter, J. Zico and Schwager, Mac and Manchester, Zachary},
 	year={2022}

docs/src/contact_models.md

@@ -11,10 +11,10 @@ Three contact models are implemented in Dojo:
 - [`LinearContact`](@ref) enforces contact with a linearized cone of friction (pyramidal cone).
 ![linearized_cone](./assets/linearized_cone.png)
 
-All 3 of these contact models implement hard contact i.e. no interpenetration. This means that for both the nonlinear and linearized cones, we concatenate the constraints resulting from friction with the impact constraints.
+All 3 of these contact models implement hard contact i.e., no interpenetration. This means that for both the nonlinear and linearized cones, we concatenate the constraints resulting from friction with the impact constraints.
 
 ### Implementation
-Dojo currently supports contact constraints occurring between a sphere and the ground i.e. a horizontal half-space of altitude 0.0. Each spherical contact is attached to a single [`Body`](@ref).
+Dojo currently supports contact constraints occurring between a sphere and the ground i.e., a horizontal half-space of altitude 0.0. Each spherical contact is attached to a single [`Body`](@ref).
 
 To create a new point of contact, we need to define:
 - the [`Body`](@ref) to which the contact constraint is attached

docs/src/contributing.md

@@ -1,11 +1,24 @@
 # Contributing
 
-Contributions are always welcome:
+Contributions are always welcome!
 
 * If you want to contribute features, bug fixes, etc, please take a look at our __Code Style Guide__ below
 * Please report any issues and bugs that you encounter in [Issues](https://github.com/dojo-sim/Dojo.jl/issues)
 * As an open source project we are also interested in any projects and applications that use Dojo. Please let us know via email to: thowell@stanford.edu or simonlc@stanford.edu
 
+## Potentially Useful Contributions 
+Here are a list of current to-do's that would make awesome contributions:
+
+- improved parsing of URDF files
+    - joint limits, friction coefficients
+- improved collision detection 
+    - body-to-body contact 
+    - general convex shapes 
+    - curved surfaces 
+- GPU support 
+- nice REPL interface
+- interactive GUI
+
 ## Code Style Guide
 
 The code in this repository follows the naming and style conventions of [Julia Base](https://docs.julialang.org/en/v1.0/manual/style-guide/#Style-Guide-1) with a few modifications. This style guide is heavily "inspired" by the guides of [John Myles White](https://github.com/johnmyleswhite/Style.jl), [JuMP](http://www.juliaopt.org/JuMP.jl/latest/style), and [COSMO](https://github.com/oxfordcontrol/COSMO.jl)

docs/src/define_controller.md

@@ -1,6 +1,6 @@
 # Defining a Controller
 Here, we explain how to write a controller and simulate its effect on a dynamical system
-i.e. a [`Mechanism`](@ref).
+i.e., a [`Mechanism`](@ref).
 We focus on a simple pendulum swing-up.
 
 Load Dojo and use the pendulum mechanism with desired simulation time step, desired gravity and desired damping at the joint.
@@ -16,12 +16,12 @@ mechanism = get_mechanism(:pendulum,
 
 Define the controller. This is a method that takes 2 input arguments:
 - a [`Mechanism`](@ref),
-- an integer `k` indicating the current simulation step.
+- an integer `t` indicating the current simulation step.
 The controller computes the control inputs based on the current state `x`, the goal state `x_goal` and a proportional gain `K`.
 
 
 ```julia
-function controller!(mechanism, k)
+function controller!(mechanism, t)
     ## Target state
     x_goal = [1.0 * π; 0.0]
 

docs/src/define_environment.md

@@ -214,4 +214,21 @@ Determine if simulation should terminate:
 function is_done(env::Environment{Ant}, x) 
     !(all(isfinite.(env.state)) && (env.state[3] >= 0.2) && (env.state[3] <= 1.0))
 end
-```
+```
+
+# Random controls
+
+We apply random controls to the robot via the environment interface:
+```julia
+y = [copy(env.state)] # state trajectory
+for t = 1:100
+    step(env, env.state, randn(env.num_inputs))
+    push!(y, copy(env.state)) 
+end
+visualize(env, y)
+```
+
+The result should be something like this:
+```@raw html
+<img src="./../../examples/animations/ant_random.gif" width="300"/>
+```

docs/src/define_simulation.md

@@ -1,10 +1,9 @@
 # Defining a Simulation
-Here, we explain how to simulate a dynamical system i.e. a [`Mechanism`](@ref) forward in time.
+Here, we explain how to simulate a dynamical system i.e., a [`Mechanism`](@ref) forward in time.
 The example that we are trying to replicate the Dzhanibekov effect shown below.
 
 ![dzhanibekov](./assets/dzhanibekov_nasa.gif)
 
-
 Load the `Dojo` package.
 ```julia
 using Dojo
@@ -25,13 +24,13 @@ mech = get_mechanism(:dzhanibekov,
 
 We initialize the system with a given initial angular velocity.
 ```julia
-initialize_dzhanibekov!(mech,
+initialize!(mech, :dzhanibekov,
     angular_velocity=[15.0; 0.01; 0.0])
 ```
 
-We simulate this system for 4 seconds, we record the resulting trajectory in `storage`,
+We simulate this system for 5 seconds, we record the resulting trajectory in `storage`,
 ```julia
-storage = simulate!(mech, 4.00,
+storage = simulate!(mech, 5.0,
     record=true,
     verbose=false)
 ```

docs/src/index.md

@@ -32,7 +32,7 @@ __Primary Development__
 
 * [Zico Kolter](https://zicokolter.com/)
 * [Mac Schwager](https://web.stanford.edu/~schwager/)
-* [Zachary Manchester](https://www.ri.cmu.edu/ri-faculty/zachary-manchester/) 
+* [Zachary Manchester](https://www.ri.cmu.edu/ri-faculty/zachary-manchester/) (principal investigator)
 
 Development by the [Robotic Exploration Lab](https://roboticexplorationlab.org/).
 

docs/src/linearized_friction.md

@@ -7,7 +7,7 @@ For a single contact point, this physical phenomenon can be modeled by the follo
 
 ```math
 \begin{align*}
-\text{minimize}_{b} & \quad v^T b \\
+\underset{b}{\text{minimize}} & \quad v^T b \\
 \text{subject to}   & \quad \|b\|_2 \leq \mu \gamma,
 \end{align*}
 ```
@@ -19,7 +19,7 @@ This above problem is naturally a convex second-order cone program, and can be e
 
 ```math
 \begin{align*}
-\text{minimize}_{\beta} & \quad [v^T  -v^T] \beta, \\
+\underset{\beta}{\text{minimize}} & \quad [v^T  -v^T] \beta, \\
 \text{subject to}       & \quad \beta^T \mathbf{1} \leq \mu \gamma, \\
                         & \quad \beta \geq 0,
 \end{align*}