Add animation documentation

README.adoc

@@ -1,4 +1,6 @@
 = ReCo.jl
+:source-highlighter: highlight.js
+:highlightjs-languages: bash, julia
 
 image:https://img.shields.io/badge/code%20style-blue-4495d1.svg[Code Style: Blue, link=https://github.com/invenia/BlueStyle]
 
@@ -12,7 +14,7 @@ The steps from the setup have to be followed before running anything in the foll
 
 To activate the environment, navigate to the main directory `/ReCo.jl` and then run the following to launch Julia:
 
-[source, bash]
+[source,bash]
 ----
 cd ReCo.jl
 julia --threads auto
@@ -20,11 +22,11 @@ julia --threads auto
 
 `auto` automatically sets the number of threads to use. If you want to use a specific number `N` of threads, replace `auto` with `N`.
 
-=== Acitivating environment
+=== Activating environment
 
 After launching Julia, the package environment has to be activated by running the follwing in the REPL:
 
-[source, julia]
+[source,julia]
 ----
 using Pkg
 Pkg.activate(".")
@@ -32,9 +34,9 @@ Pkg.activate(".")
 
 === Install dependencies
 
-After activating the package environment, run the follwing to install the package dependencies:
+After activating the package environment, run the following to install the package dependencies:
 
-[source, julia]
+[source,julia]
 ----
 Pkg.instantiate()
 ----
@@ -43,36 +45,47 @@ Pkg.instantiate()
 
 You can import the package by running:
 
-[source, julia]
+[source,julia]
 ----
 using ReCo
 ----
 
-This will export the package methods that are intended to be used by the end user.
+This will export the package's methods that are intended to be used by the end user.
+
+== Help mode
+
+To access the documentation of the presented package methods further in this README, run `using ReCo` first. Then, enter the help mode by pressing `?` in the REPL. Now, enter the method's name followed by enter to see its documentation.
 
 == Run simulation
 
 Initialize a simulation with 100 particles having a self-propulsion velocity of 40.0 and return the relative path to the simulation directory:
 
-[source, julia]
+[source,julia]
 ----
 sim_dir = init_sim(100, 40.0)
 ----
 
 Run the simulation:
 
-[source, julia]
+[source,julia]
 ----
 run_sim(sim_dir, duration=20.0)
 ----
 
-The values for the number of particles, self-propulsion velocity and simulation duration are used here as an example. For more information about possible values and other optional arguments, press `?` in the REPL after running `using ReCo`. Then type `init_sim` or `run_sim` followed by pressing enter. This will show the method's documention.
+The values for the number of particles, self-propulsion velocity and simulation duration are used here as an example. For more information about possible values and other optional arguments, see the documentation of `init_sim` or `run_sim`.
 
 == Simulation visualization
 
 === Animation
 
-//TODO
+To generate an animation of a simulation, run the following:
+
+[source,julia]
+----
+animate(sim_dir)
+----
+
+The method's documentation includes all possible optional arguments.
 
 === Snapshot plot
 
@@ -81,50 +94,56 @@ The values for the number of particles, self-propulsion velocity and simulation
 == Run reinforcement learning
 
 Run a reinforcement learning process and return the environment helper and the the path of the process directory relative to the directory `ReCo.jl`:
-[source, julia]
+[source,julia]
 ----
 env_helper, rl_dir = run_rl(ENVTYPE)
 ----
 
-ENVTYPE has to be replaced by one of the environments named after the file names in the directory `ReCo.jl/RL/Envs`, for example: `LocalCOMEnv`. A description of an environment is included at the beginning of the corresponding file.
+`ENVTYPE` has to be replaced by one of the environments named after the file names in the directory `ReCo.jl/RL/Envs`, for example: `LocalCOMEnv`. A description of an environment is included at the beginning of the corresponding file.
 //TODO: Descriptions of envs
 
-For more information about all possible optional arguments, press `?` in the REPL after running `using ReCo`. Then type `run_rl` followed by pressing enter.
+The documentation of `run_rl` includes all possible optional arguments.
+
+=== Q-matrix
 
 `env_helper` has the abstract type `EnvHelper`. To access the Q-matrix, enter the following:
 
-[source, julia]
+[source,julia]
 ----
 env_helper.shared.agent.policy.learner.approximator.table
 ----
 
 To generate a LaTeX table with the states and actions combintation names for the Q-matrix, run the follwing:
 
-[source, julia]
+[source,julia]
 ----
 include("src/RL/latex_table.jl")
 latex_rl_table(env_helper, FILENAME)
 ----
 
-FILENAME has to be replaced by the wanted file name of the `.tex` file. This file can then be found under `ReCo.jl/exports/FILENAME`.
+`FILENAME` has to be replaced by the wanted file name without extension of the `.tex` file. This file can then be found under `ReCo.jl/exports/FILENAME.tex`.
+
+=== Rewards
 
 To access the rewards, run the following:
 
-[source, julia]
+[source,julia]
 ----
 env_helper.shared.hook.rewards
 ----
 
 To plot the rewards, run the following:
 
-[source, julia]
+[source,julia]
 ----
 plot_rewards(rl_dir)
 ----
 
+=== Mean kappa
+
 To plot the mean of kappa as the ratio of the eigenvalues of the gyration tensor, run the following:
 
-[source, julia]
+[source,julia]
 ----
 include("analysis/mean_kappa.jl")
 plot_mean_kappa(; rl_dir=rl_dir, n_last_episodes=N_LAST_EPISODES)
@@ -134,11 +153,11 @@ plot_mean_kappa(; rl_dir=rl_dir, n_last_episodes=N_LAST_EPISODES)
 
 == Run analysis
 
-After running the following command blocks in the REPL, the output can be found in the directory `exports/graphics`.
+After running the following command blocks in the REPL, the output can be found in the directory `ReCo.jl/exports/graphics`.
 
 === Mean squared displacement
 
-[source, julia]
+[source,julia]
 ----
 include("analysis/mean_squared_displacement.jl")
 run_msd_analysis()
@@ -147,7 +166,7 @@ run_random_walk()
 
 === Radial distribution function
 
-[source, julia]
+[source,julia]
 ----
 include("analysis/radial_distribution_function/radial_distribution_function.jl")
 run_radial_distribution_analysis()

src/RL/latex_table.jl

@@ -11,7 +11,7 @@ function latex_table(
     return nothing
 end
 
-function latex_rl_table(env_helper, filename::String)
+function latex_rl_table(env_helper, filename_without_extension::String)
     table = copy(env_helper.shared.agent.policy.learner.approximator.table)
 
     for col in 1:size(table)[2]
@@ -40,7 +40,7 @@ function latex_rl_table(env_helper, filename::String)
     df = DataFrames.DataFrame(table, states)
     DataFrames.insertcols!(df, 1, :Actions => actions)
 
-    latex_table(df, filename)
+    latex_table(df, "$filename_without_extension.tex")
 
     return nothing
 end

src/Visualization/Animation.jl

@@ -12,6 +12,13 @@ using ..ReCo: ReCo
 
 include("common.jl")
 
+const DEFAULT_FRAMERATE = 10
+const DEFAULT_SHOW_CENTER_OF_MASS = false
+const DEFAULT_SHOW_INTERACTION_CIRCLE = false
+const DEFAULT_SHOW_SKIN_CIRCLE = false
+const DEFAULT_SHOW_FRAME_DIFF = false
+const DEFAULT_SHOW_PROGRESS = false
+
 function animate_bundle!(args, sim_consts::ReCo.SimConsts)
     bundle_t = args.bundle.t
     bundle_c = args.bundle.c
@@ -141,14 +148,29 @@ function animate_bundle!(args, sim_consts::ReCo.SimConsts)
     return nothing
 end
 
+"""
+    animate(sim_dir::String; <keyword arguments>)
+
+Animate a simulation.
+
+The output is `sim_dir/animation.mkv`.
+
+# Arguments
+- `framerate::Int64=$DEFAULT_FRAMERATE`: Framerate
+- `show_center_of_mass::Bool=$DEFAULT_SHOW_CENTER_OF_MASS`: Show center of mass as transparent white circle.
+- `show_interaction_circle::Bool=$DEFAULT_SHOW_INTERACTION_CIRCLE`: Show the interaction radius with a circle around every particle.
+- `show_skin_circle::Bool=$DEFAULT_SHOW_SKIN_CIRCLE`: Show the skin radius with a circle around every particle.
+- `show_frame_diff::Bool=$DEFAULT_SHOW_FRAME_DIFF`: Show translation of particles between two frames as lines connecting the old and new position. This is helpful to recognize unwanted jumps.
+- `show_progress::Bool=$DEFAULT_SHOW_PROGRESS`: Show animation progress bar.
+"""
 function animate(
     sim_dir::String;
-    framerate::Int64=1,
+    framerate::Int64=DEFAULT_FRAMERATE,
-    show_center_of_mass::Bool=false,
+    show_center_of_mass::Bool=DEFAULT_SHOW_CENTER_OF_MASS,
-    show_interaction_circle::Bool=false,
+    show_interaction_circle::Bool=DEFAULT_SHOW_INTERACTION_CIRCLE,
-    show_skin_circle::Bool=false,
+    show_skin_circle::Bool=DEFAULT_SHOW_SKIN_CIRCLE,
-    show_frame_diff::Bool=false,
+    show_frame_diff::Bool=DEFAULT_SHOW_FRAME_DIFF,
-    show_progress::Bool=true,
+    show_progress::Bool=DEFAULT_SHOW_PROGRESS,
 )
     println("Initializing GLMakie...")