From d92a6c03a2ae899b8f8c2a5c37447edddb94ce00 Mon Sep 17 00:00:00 2001 From: ErikQQY <2283984853@qq.com> Date: Thu, 30 May 2024 15:59:34 +0800 Subject: [PATCH] Add docs for constructors and populate docs Signed-off-by: ErikQQY <2283984853@qq.com> --- docs/literate/man/constructors.jl | 29 +++++++++++ docs/make.jl | 7 +-- docs/src/generated/man/constructors.md | 39 +++++++++++++++ src/struct_named_trajectory.jl | 66 +++++++++++++++++++++++++- 4 files changed, 137 insertions(+), 4 deletions(-) diff --git a/docs/literate/man/constructors.jl b/docs/literate/man/constructors.jl index ecf9218..e106ea9 100644 --- a/docs/literate/man/constructors.jl +++ b/docs/literate/man/constructors.jl @@ -1 +1,30 @@ # # Constructors + +# To construct a `NamedTrajectory` using NamedTrajectories.jl, we simply need to utilize the `NamedTrajectory` constructor. + +using NamedTrajectories + +## define number of timesteps and timestep +T = 10 +dt = 0.1 + +# build named tuple of components and data matrices. + +components = ( + x = rand(3, T), + u = rand(2, T), + Δt = fill(dt, 1, T), +) + +# we must specify a timestep and control variable for the trajectory. + +timestep = 0.1 +control = :u + +# we can now create a `NamedTrajectory` object. + +traj = NamedTrajectory(components; timestep=timestep, controls=control) + +# Construct `NamedTrajectory` from previous constructed one. + +traj = NamedTrajectory(components, traj) \ No newline at end of file diff --git a/docs/make.jl b/docs/make.jl index c7b6686..20b62a6 100644 --- a/docs/make.jl +++ b/docs/make.jl @@ -7,14 +7,14 @@ push!(LOAD_PATH, joinpath(@__DIR__, "..", "src")) pages = [ "Home" => "index.md", "Quickstart Guide" => "generated/quickstart.md", - # "Manual" => [ - # "generated/man/constructors.md", + "Manual" => [ + "generated/man/constructors.md", # "generated/man/retrieval.md", # "generated/man/add_remove.md", # "generated/man/updating.md", # "generated/man/times.md", # "generated/man/operations.md", - # ], + ], "Plotting" => "generated/plotting.md", "Library" => "lib.md" ] @@ -63,6 +63,7 @@ makedocs(; modules=[NamedTrajectories], authors="Aaron Trowbridge and contributors", sitename="NamedTrajectories.jl", + warnonly = [:missing_docs], format=format, pages=pages, ) diff --git a/docs/src/generated/man/constructors.md b/docs/src/generated/man/constructors.md index 6e42902..dd70e2c 100644 --- a/docs/src/generated/man/constructors.md +++ b/docs/src/generated/man/constructors.md @@ -4,6 +4,45 @@ EditURL = "../../../literate/man/constructors.jl" # Constructors +To construct a `NamedTrajectory` using NamedTrajectories.jl, we simply need to utilize the `NamedTrajectory` constructor. + +````@example constructors +using NamedTrajectories + +# define number of timesteps and timestep +T = 10 +dt = 0.1 +```` + +build named tuple of components and data matrices. + +````@example constructors +components = ( + x = rand(3, T), + u = rand(2, T), + Δt = fill(dt, 1, T), +) +```` + +we must specify a timestep and control variable for the trajectory. + +````@example constructors +timestep = 0.1 +control = :u +```` + +we can now create a `NamedTrajectory` object. + +````@example constructors +traj = NamedTrajectory(components; timestep=timestep, controls=control) +```` + +Construct `NamedTrajectory` from previous constructed one. + +````@example constructors +traj = NamedTrajectory(components, traj) +```` + --- *This page was generated using [Literate.jl](https://github.com/fredrikekre/Literate.jl).* diff --git a/src/struct_named_trajectory.jl b/src/struct_named_trajectory.jl index 2295ecc..ae4222a 100644 --- a/src/struct_named_trajectory.jl +++ b/src/struct_named_trajectory.jl @@ -8,6 +8,9 @@ using OrderedCollections const BoundType = Tuple{AbstractVector{<:Real}, AbstractVector{<:Real}} +""" + NamedTrajectory constructor +""" mutable struct NamedTrajectory{R <: Real} data::AbstractMatrix{R} datavec::AbstractVector{R} @@ -25,7 +28,18 @@ mutable struct NamedTrajectory{R <: Real} control_names::Tuple{Vararg{Symbol}} end - +""" + NamedTrajectory(comp_data; controls=(), timestep=nothing, bounds, initial, final, goal) + + # Arguments + - `comp_data::NamedTuple{names, <:Tuple{Vararg{vals}}} where {names, vals <: AbstractMatrix{R}}`: Components data. + - `controls`: The control variable in comp_data, should be type of `Symbol` among `comp_data`. + - `timestep`: Discretizing time step in `comp_data`, should be type of `Symbol` among `comp_data`. + - `bounds`: Bounds of the trajectory. + - `initial`: Initial values. + - `final`: Final values. + - `goal`: Goal for the states. +""" function NamedTrajectory( comp_data::NamedTuple{names, <:Tuple{Vararg{vals}}} where {names, vals <: AbstractMatrix{R}}; @@ -159,6 +173,13 @@ function NamedTrajectory( ) end +""" + NamedTrajectory(comps; kwargs...) + + # Arguments + - `comp_data::NamedTuple{names, <:Tuple{Vararg{vals}}} where {names, vals <: AbstractMatrix{R}}`: Components data. + - `kwargs...`: The other key word arguments. +""" function NamedTrajectory( comps::NamedTuple; kwargs... @@ -173,7 +194,20 @@ end +""" + NamedTrajectory(datavec, T, comp_data; controls=(), timestep=nothing, bounds, initial, final, goal) + # Arguments + - `datavec::AbstractVector{R} where R <: Real`: Trajectory data. + - `T::Int`: Numbers of time step. + - `comp_data::NamedTuple{names, <:Tuple{Vararg{vals}}} where {names, vals <: AbstractMatrix{R}}`: components data. + - `controls`: The control variable in comp_data, should be type of `Symbol` among `comp_data`. + - `timestep`: Discretizing time step in `comp_data`, should be type of `Symbol` among `comp_data`. + - `bounds`: Bounds of the trajectory. + - `initial`: Initial values. + - `final`: Final values. + - `goal`: Goal for the states. +""" function NamedTrajectory( datavec::AbstractVector{R}, T::Int, @@ -263,6 +297,13 @@ function NamedTrajectory( ) end +""" + NamedTrajectory(comp_data; controls=(), timestep=nothing, bounds, initial, final, goal) + + # Arguments + - `datavec::AbstractVector{R} where R <: Real`: Trajectory data. + - `z`: Constructed `NamedTrajectory`. +""" function NamedTrajectory( datavec::AbstractVector{R}, Z::NamedTrajectory @@ -293,6 +334,13 @@ function NamedTrajectory( ) end +""" + NamedTrajectory(data, traj) + + # Arguments + - `data`: Trajectory data. + - `traj`: Constructed `NamedTrajectory`. +""" function NamedTrajectory( data::AbstractMatrix{R}, traj::NamedTrajectory @@ -323,6 +371,14 @@ function NamedTrajectory( ) end +""" + NamedTrajectory(data, componets; kwargs...) + + # Arguments + - `data::AbstractMatrix{R}`: Trajectory data. + - `components::NamedTuple{names, <:Tuple{Vararg{AbstractVector{Int}}}} where names`: components data. + - `kwargs...` : The other key word arguments. +""" function NamedTrajectory( data::AbstractMatrix{R}, components::NamedTuple{ @@ -336,6 +392,14 @@ function NamedTrajectory( return NamedTrajectory(datavec, T, components; kwargs...) end +""" + NamedTrajectory(comp_data; controls=(), timestep=nothing, bounds, initial, final, goal) + + # Arguments + - `comps::NamedTuple{names, <:Tuple{Vararg{AbstractMatrix{R}}}} where {names}`: components data. + - `traj`: Constructed NamedTrajectory. + - `goal`: Goal for the states. +""" function NamedTrajectory( comps::NamedTuple{ names,