From 0b01c5162e23e913501a3d8ae620c32934a9203d Mon Sep 17 00:00:00 2001 From: schillic Date: Sat, 25 Jan 2025 20:58:09 +0100 Subject: [PATCH] use DocumenterCitations for bibliography --- docs/Project.toml | 2 + docs/make.jl | 10 +- docs/src/assets/citations.css | 17 +++ docs/src/bibliography.md | 4 + docs/src/refs.bib | 107 ++++++++++++++++++ models/ACC/ACC.jl | 10 +- models/AttitudeControl/AttitudeControl.jl | 8 +- models/Quadrotor/Quadrotor.jl | 7 +- models/SpacecraftDocking/SpacecraftDocking.jl | 10 +- models/TORA/TORA.jl | 8 +- models/Unicycle/Unicycle.jl | 8 +- models/VerticalCAS/VerticalCAS.jl | 14 +-- 12 files changed, 144 insertions(+), 61 deletions(-) create mode 100644 docs/src/assets/citations.css create mode 100644 docs/src/bibliography.md create mode 100644 docs/src/refs.bib diff --git a/docs/Project.toml b/docs/Project.toml index f82b9cb5..8d0d0d02 100644 --- a/docs/Project.toml +++ b/docs/Project.toml @@ -1,6 +1,7 @@ [deps] DisplayAs = "0b91fe84-8a4c-11e9-3e1d-67c38462b6d6" Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4" +DocumenterCitations = "daee34ce-89f3-4625-b898-19384cb65244" Literate = "98b081ad-f1c9-55d3-8b20-4c87d4299306" OrdinaryDiffEq = "1dea7af3-3e70-54e6-95c3-0bf5283fa5ed" Plots = "91a5bcdd-55d7-5caf-9e0b-520d859cae80" @@ -10,6 +11,7 @@ ReachabilityBase = "379f33d0-9447-4353-bd03-d664070e549f" [compat] DisplayAs = "0.1" Documenter = "1" +DocumenterCitations = "1.3" Literate = "2" OrdinaryDiffEq = "6" Plots = "1" diff --git a/docs/make.jl b/docs/make.jl index b1c0d481..2d3a3c84 100644 --- a/docs/make.jl +++ b/docs/make.jl @@ -1,4 +1,4 @@ -using Documenter, ClosedLoopReachability +using Documenter, ClosedLoopReachability, DocumenterCitations DocMeta.setdocmeta!(ClosedLoopReachability, :DocTestSetup, :(using ClosedLoopReachability); recursive=true) @@ -6,12 +6,15 @@ DocMeta.setdocmeta!(ClosedLoopReachability, :DocTestSetup, # generate models include("generate.jl") +bib = CitationBibliography(joinpath(@__DIR__, "src", "refs.bib"); style=:alpha) + makedocs(; sitename="ClosedLoopReachability.jl", modules=[ClosedLoopReachability], format=Documenter.HTML(; prettyurls=get(ENV, "CI", nothing) == "true", collapselevel=1, - assets=["assets/aligned.css"]), + assets=["assets/aligned.css", "assets/citations.css"]), pagesonly=true, + plugins=[bib], pages=["Home" => "index.md", "Examples" => Any[ # @@ -28,7 +31,8 @@ makedocs(; sitename="ClosedLoopReachability.jl", # ], "API Reference" => Any["Problem types" => "lib/problems.md", - "Solvers" => "lib/solvers.md"]]) + "Solvers" => "lib/solvers.md"], + "Bibliography" => "bibliography.md"]) deploydocs(; repo="github.com/JuliaReach/ClosedLoopReachability.jl.git", push_preview=true) diff --git a/docs/src/assets/citations.css b/docs/src/assets/citations.css new file mode 100644 index 00000000..b0c63267 --- /dev/null +++ b/docs/src/assets/citations.css @@ -0,0 +1,17 @@ +.citation dl { + display: grid; + grid-template-columns: max-content auto; } +.citation dt { + grid-column-start: 1; } +.citation dd { + grid-column-start: 2; + margin-bottom: 0.75em; } +.citation ul { + padding: 0 0 2.25em 0; + margin: 0; + list-style: none !important;} +.citation ul li { + text-indent: -2.25em; + margin: 0.33em 0.5em 0.5em 2.25em;} +.citation ol li { + padding-left:0.75em;} diff --git a/docs/src/bibliography.md b/docs/src/bibliography.md new file mode 100644 index 00000000..a987675a --- /dev/null +++ b/docs/src/bibliography.md @@ -0,0 +1,4 @@ +# Bibliography + +```@bibliography +``` diff --git a/docs/src/refs.bib b/docs/src/refs.bib new file mode 100644 index 00000000..ed70b7de --- /dev/null +++ b/docs/src/refs.bib @@ -0,0 +1,107 @@ +@article{TranCLMJK19, + author = {Hoang{-}Dung Tran and + Feiyang Cai and + Diego Manzanas Lopez and + Patrick Musau and + Taylor T. Johnson and + Xenofon D. Koutsoukos}, + title = {Safety Verification of Cyber-Physical Systems with Reinforcement Learning + Control}, + journal = {Transactions on Embedded Computing Systems}, + volume = {18}, + number = {5s}, + pages = {105:1--105:22}, + year = {2019}, + url = {https://doi.org/10.1145/3358230}, + doi = {10.1145/3358230} +} + +@article{PrajnaPR04, + author = {Stephen Prajna and + Pablo A. Parrilo and + Anders Rantzer}, + title = {Nonlinear control synthesis by convex optimization}, + journal = {Transactions on Automatic Control}, + volume = {49}, + number = {2}, + pages = {310--314}, + year = {2004}, + url = {https://doi.org/10.1109/TAC.2003.823000}, + doi = {10.1109/TAC.2003.823000} +} + +@techreport{Beard08, + title={Quadrotor dynamics and control}, + author={Beard, Randal W}, + institution={Brigham Young University}, + number={1325}, + year={2008}, + url={https://scholarsarchive.byu.edu/facpub/1325} +} + +@inproceedings{RavaioliCMGDH22, + title={Safe reinforcement learning benchmark environments for aerospace control systems}, + author={Ravaioli, Umberto J and Cunningham, James and McCarroll, John and Gangal, Vardaan and Dunlap, Kyle and Hobbs, Kerianne L}, + booktitle={Aerospace Conference ({AERO})}, + pages={1--20}, + year={2022}, + organization={IEEE} +} + +@article{JankovicFK96, + author = {Mrdjan Jankovic and + Daniel Fontaine and + Petar V. Kokotovic}, + title = {{TORA} example: cascade- and passivity-based control designs}, + journal = {Transactions on Control Systems Technology}, + volume = {4}, + number = {3}, + pages = {292--297}, + year = {1996}, + url = {https://doi.org/10.1109/87.491203}, + doi = {10.1109/87.491203} +} + +@inproceedings{AlthoffKM17, + author = {Matthias Althoff and + Markus Koschi and + Stefanie Manzinger}, + title = {{CommonRoad}: Composable benchmarks for motion planning on roads}, + booktitle = {Intelligent Vehicles ({IV})}, + pages = {719--726}, + publisher = {{IEEE}}, + year = {2017}, + url = {https://doi.org/10.1109/IVS.2017.7995802}, + doi = {10.1109/IVS.2017.7995802} +} + +@article{JulianK19, + author = {Kyle D. Julian and + Mykel J. Kochenderfer}, + title = {A Reachability Method for Verifying Dynamical Systems with Deep Neural + Network Controllers}, + journal = {CoRR}, + volume = {abs/1903.00520}, + year = {2019}, + url = {http://arxiv.org/abs/1903.00520}, + eprinttype = {arXiv}, + eprint = {1903.00520} +} + +@inproceedings{AkintundeBKL20, + author = {Michael E. Akintunde and + Elena Botoeva and + Panagiotis Kouvaros and + Alessio Lomuscio}, + editor = {Amal El Fallah Seghrouchni and + Gita Sukthankar and + Bo An and + Neil Yorke{-}Smith}, + title = {Formal Verification of Neural Agents in Non-deterministic Environments}, + booktitle = {Autonomous Agents and Multiagent Systems ({AAMAS})}, + pages = {25--33}, + publisher = {IFAAMAS}, + year = {2020}, + url = {http://ifaamas.org/Proceedings/aamas2020/pdfs/p25.pdf}, + doi = {10.5555/3398761.3398770} +} diff --git a/models/ACC/ACC.jl b/models/ACC/ACC.jl index 288f585a..55c3169f 100644 --- a/models/ACC/ACC.jl +++ b/models/ACC/ACC.jl @@ -2,7 +2,7 @@ # # The Adaptive Cruise Control (ACC) benchmark models a car that drives at a set # velocity and maintains a safe distance from a lead car by adjusting the -# longitudinal acceleration [^TCMMJK]. +# longitudinal acceleration [TranCLMJK19](@cite). # # ![](ACC_explanation.png) @@ -258,11 +258,3 @@ fig = DisplayAs.Text(DisplayAs.PNG(fig)) end #jl nothing #jl - -# ## References - -# [^TCMMJK]: Hoang-Dung Tran, Feiyang Cai, Diego Manzanas Lopez, Patrick Musau, -# Taylor T. Johnson, and Xenofon D. Koutsoukos (2019). *Safety -# verification of cyber-physical systems with reinforcement learning -# control*. In -# [ACM Trans. Embed. Comput. Syst.](https://doi.org/10.1145/3358230) diff --git a/models/AttitudeControl/AttitudeControl.jl b/models/AttitudeControl/AttitudeControl.jl index 96c1e419..a1ebcfae 100755 --- a/models/AttitudeControl/AttitudeControl.jl +++ b/models/AttitudeControl/AttitudeControl.jl @@ -1,6 +1,6 @@ # # Attitude Control # -# The Attitude Control benchmark models a rigid-body system [^PPR]. +# The Attitude Control benchmark models a rigid-body system [PrajnaPR04](@cite). module AttitudeControl #jl @@ -165,9 +165,3 @@ fig = DisplayAs.Text(DisplayAs.PNG(fig)) end #jl nothing #jl - -# ## References - -# [^PPR]: Stephen Prajna, Pablo A. Parrilo, and Anders Rantzer (2004). -# *Nonlinear control synthesis by convex optimization*. In -# [IEEE Trans. Autom. Control](https://doi.org/10.1109/TAC.2003.823000). diff --git a/models/Quadrotor/Quadrotor.jl b/models/Quadrotor/Quadrotor.jl index a55af86e..cf6c10b7 100755 --- a/models/Quadrotor/Quadrotor.jl +++ b/models/Quadrotor/Quadrotor.jl @@ -21,7 +21,7 @@ using Plots: plot, plot! # ``(x_7, x_8, x_9)`` is the (roll, pitch, yaw) angle, and # ``(x_{10}, x_{11}, x_{12})`` is the (roll, pitch, yaw) rate. The control # inputs ``(u_1, u_2, u_3)`` represent the torque. For more details we refer to -# [^B]. +# [Beard08](@citet). vars_idx = Dict(:states => 1:12, :controls => 13:15) @@ -192,8 +192,3 @@ fig = DisplayAs.Text(DisplayAs.PNG(fig)) end #jl nothing #jl - -# ## References - -# [^B]: Randal Beard (2008). *Quadrotor dynamics and control*. -# [Technical report](https://scholarsarchive.byu.edu/facpub/1325/). diff --git a/models/SpacecraftDocking/SpacecraftDocking.jl b/models/SpacecraftDocking/SpacecraftDocking.jl index 8276343c..40fc8975 100644 --- a/models/SpacecraftDocking/SpacecraftDocking.jl +++ b/models/SpacecraftDocking/SpacecraftDocking.jl @@ -16,7 +16,7 @@ using Plots: plot, plot! # There are 4 state variables ``(s_x, s_y, \dot{s}_x, \dot{s}_y)``, where # ``(s_x, s_y)`` is the position and ``(\dot{s}_x, \dot{s}_y)`` is the velocity -# of the spacecraft [^RCMGDH]. +# of the spacecraft [RavaioliCMGDH22](@cite). vars_idx = Dict(:states => 1:4, :controls => 5:6) @@ -161,11 +161,3 @@ fig = DisplayAs.Text(DisplayAs.PNG(fig)) end #jl nothing #jl - -# ## References - -# [^RCMGDH]: Umberto J. Ravaioli, James Cunningham, John McCarroll, Vardaan -# Gangal, Kyle Dunlap, and Kerianne L. Hobbs (2022). *Safe -# reinforcement learning benchmark environments for aerospace control -# systems*. In -# [IEEE Aerospace Conference](https://doi.org/10.1109/AERO53065.2022.9843750). diff --git a/models/TORA/TORA.jl b/models/TORA/TORA.jl index bdce4e67..6718cd4d 100644 --- a/models/TORA/TORA.jl +++ b/models/TORA/TORA.jl @@ -3,7 +3,7 @@ # The TORA benchmark models a cart attached to a wall with a spring. The cart is # free to move on a friction-less surface and has a weight attached to an arm, # which is free to rotate about an axis. This serves as the control input to -# stabilize the cart at the origin ``x = 0`` [^JFK]. +# stabilize the cart at the origin ``x = 0`` [JankovicFK96](@cite). # # ![](TORA_explanation.png) # @@ -320,9 +320,3 @@ fig = DisplayAs.Text(DisplayAs.PNG(fig)) end #jl nothing #jl - -# ## References - -# [^JFK]: Mrdjan Jankovic, Daniel Fontaine, and Petar V. Kokotovic. *TORA -# example: cascade- and passivity-based control designs*. In -# [IEEE Trans. Control. Syst. Technol.](https://doi.org/10.1109/87.491203) diff --git a/models/Unicycle/Unicycle.jl b/models/Unicycle/Unicycle.jl index 0a63f8ac..1c64a2d7 100644 --- a/models/Unicycle/Unicycle.jl +++ b/models/Unicycle/Unicycle.jl @@ -1,6 +1,6 @@ # # Unicycle # -# The Unicycle benchmark models a unicycle vehicle [^AKM]. +# The Unicycle benchmark models a unicycle vehicle [AlthoffKM17](@cite). # # ![](Unicycle_explanation.png) @@ -202,9 +202,3 @@ fig = DisplayAs.Text(DisplayAs.PNG(fig)) end #jl nothing #jl - -# ## References - -# [^AKM]: Matthias Althoff, Markus Koschi, and Stefanie Manzinger (2017). -# *CommonRoad: Composable benchmarks for motion planning on roads.* In -# [IEEE Intelligent Vehicles Symposium](https://doi.org/10.1109/IVS.2017.7995802). diff --git a/models/VerticalCAS/VerticalCAS.jl b/models/VerticalCAS/VerticalCAS.jl index f371257b..2c45b7f6 100644 --- a/models/VerticalCAS/VerticalCAS.jl +++ b/models/VerticalCAS/VerticalCAS.jl @@ -2,7 +2,7 @@ # # The VerticalCAS benchmark considers a collision avoidance system (CAS), # required for commercial aircraft, which gives vertical climbrate advisories -# to pilots [^JK][^ABKL]. +# to pilots [JulianK19, AkintundeBKL20](@cite). module VerticalCAS #jl @@ -371,15 +371,3 @@ fig = DisplayAs.Text(DisplayAs.PNG(fig)) end #jl nothing #jl - -# ## References - -# [^JK]: Kyle D. Julian and Mykel J. Kochenderfer (2019). *A reachability method -# for verifying dynamical systems with deep neural network controllers*. -# [arXiv:1903.00520](https://arxiv.org/pdf/1903.00520.pdf). -# -# [^ABKL]: Michael E. Akintunde, Elena Botoeva, Panagiotis Kouvaros, and Alessio -# Lomuscio (2020). *Formal verification of neural agents in -# non-deterministic environments*. In [Proceedings of the 19th -# International Conference on Autonomous Agents and Multiagent -# Systems](http://ifaamas.org/Proceedings/aamas2020/pdfs/p25.pdf).