From edd47999b3b1e2dcbdb16dabaeda972bedbede9b Mon Sep 17 00:00:00 2001 From: Mo8it Date: Tue, 8 Feb 2022 21:34:06 +0100 Subject: [PATCH] Add animation documentation --- README.adoc | 65 ++++++++++++++++++++++------------ src/RL/latex_table.jl | 4 +-- src/Visualization/Animation.jl | 34 ++++++++++++++---- 3 files changed, 72 insertions(+), 31 deletions(-) diff --git a/README.adoc b/README.adoc index 66b0b06..e22f65f 100644 --- a/README.adoc +++ b/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() diff --git a/src/RL/latex_table.jl b/src/RL/latex_table.jl index 74b5a8b..22a159e 100644 --- a/src/RL/latex_table.jl +++ b/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 \ No newline at end of file diff --git a/src/Visualization/Animation.jl b/src/Visualization/Animation.jl index 46a7cf8..c1055fd 100644 --- a/src/Visualization/Animation.jl +++ b/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; ) + +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, - show_center_of_mass::Bool=false, - show_interaction_circle::Bool=false, - show_skin_circle::Bool=false, - show_frame_diff::Bool=false, - show_progress::Bool=true, + framerate::Int64=DEFAULT_FRAMERATE, + show_center_of_mass::Bool=DEFAULT_SHOW_CENTER_OF_MASS, + show_interaction_circle::Bool=DEFAULT_SHOW_INTERACTION_CIRCLE, + show_skin_circle::Bool=DEFAULT_SHOW_SKIN_CIRCLE, + show_frame_diff::Bool=DEFAULT_SHOW_FRAME_DIFF, + show_progress::Bool=DEFAULT_SHOW_PROGRESS, ) println("Initializing GLMakie...")