Merge pull request #892 from sathvikbhagavan/sb/docstrings

ChrisRackauckas · web-flow · commit 661ba48eb5af · 2023-12-25T00:11:35.000-05:00
docs: clean up docstrings to fix rendering issues
diff --git a/docs/src/layers/BasisLayers.md b/docs/src/layers/BasisLayers.md
@@ -1,6 +1,6 @@
 # Classical Basis Layers
 
-The following basis are helper functions for easily building arrays of the form [f_0(x), ..., f_{n-1}(x)], where f is the corresponding function of the basis (e.g, Chebyshev Polynomials, Legendre Polynomials, etc.)
+The following basis are helper functions for easily building arrays of the form [f\_0(x), ..., f\_{n-1}(x)], where f is the corresponding function of the basis (e.g, Chebyshev Polynomials, Legendre Polynomials, etc.)
 
 ```@docs
 ChebyshevBasis
diff --git a/docs/src/layers/SplineLayer.md b/docs/src/layers/SplineLayer.md
@@ -1,13 +1,5 @@
 # Spline Layer
 
-Constructs a Spline Layer. At a high-level, it performs the following:
-
- 1. Takes as input a one-dimensional training dataset, a time span, a time step and
-    an interpolation method.
- 2. During training, adjusts the values of the function at multiples of the time-step
-    such that the curve interpolated through these points has minimum loss on the corresponding
-    one-dimensional dataset.
-
 ```@docs
 SplineLayer
 ```
diff --git a/docs/src/layers/TensorLayer.md b/docs/src/layers/TensorLayer.md
@@ -1,10 +1,5 @@
 # Tensor Product Layer
 
-The following layer is a helper function for easily constructing a TensorLayer, which
-takes as input an array of n tensor product basis, ``[B_1, B_2, ..., B_n]``, a data
-point x, computes ``z[i] = W[i,:] ⨀ [B_1(x[1]) ⨂ B_2(x[2]) ⨂ ... ⨂ B_n(x[n])]``,
-where W is the layer's weight, and returns [z[1], ..., z[out]].
-
 ```@docs
 TensorLayer
 ```
diff --git a/docs/src/utilities/Collocation.md b/docs/src/utilities/Collocation.md
@@ -13,7 +13,7 @@ accumulate through time, is not as exact as other methods.
     
     This is one of many methods for calculating the collocation coefficients
     for the training process. For a more comprehensive set of collocation
-    methods, see the [JuliaSimModelOptimizer](https://help.juliahub.com/jsmo/stable/manual/collocation/).
+    methods, see [JuliaSimModelOptimizer](https://help.juliahub.com/jsmo/stable/manual/collocation/).
 
 ```@docs
 collocate_data
diff --git a/docs/src/utilities/MultipleShooting.md b/docs/src/utilities/MultipleShooting.md
@@ -2,7 +2,7 @@
 
 !!! note
     
-    The form of multiple shooting found here is a specialized form for implicit layer deep learning (known as data shooting) which assumes full observability of the underlying dynamics and lack of noise. For a more general implementation of multiple shooting, see the [JuliaSimModelOptimizer](https://help.juliahub.com/jsmo/stable/). For an implementation more directly tied to parameter estimation against data, see [DiffEqParamEstim.jl](https://docs.sciml.ai/DiffEqParamEstim/stable/).
+    The form of multiple shooting found here is a specialized form for implicit layer deep learning (known as data shooting) which assumes full observability of the underlying dynamics and lack of noise. For a more general implementation of multiple shooting, see [JuliaSimModelOptimizer](https://help.juliahub.com/jsmo/stable/). For an implementation more directly tied to parameter estimation against data, see [DiffEqParamEstim.jl](https://docs.sciml.ai/DiffEqParamEstim/stable/).
 
 ```@docs
 multiple_shoot
diff --git a/src/collocation.jl b/src/collocation.jl
@@ -65,7 +65,7 @@ For kernels, the following exist:
 https://www.ncbi.nlm.nih.gov/pmc/articles/PMC2631937/
 
 Additionally, we can use interpolation methods from
-[DataInterpolations.jl](https://github.com/PumasAI/DataInterpolations.jl) to generate
+[DataInterpolations.jl](https://github.com/SciML/DataInterpolations.jl) to generate
 data from intermediate timesteps. In this case, pass any of the methods like
 `QuadraticInterpolation` as `interp`, and the timestamps to sample from as `tpoints_sample`.
 """
diff --git a/src/ffjord.jl b/src/ffjord.jl
@@ -10,14 +10,14 @@ via adjoints [1] and specialized for density estimation based on continuous
 normalizing flows (CNF) [2] with a stochastic approach [2] for the computation of the trace
 of the dynamics' jacobian. At a high level this corresponds to the following steps:
 
-1. Parameterize the variable of interest x(t) as a function f(z, θ, t) of a base variable z(t) with known density p_z;
-2. Use the transformation of variables formula to predict the density p_x as a function of the density p_z and the trace of the Jacobian of f;
-3. Choose the parameter θ to minimize a loss function of p_x (usually the negative likelihood of the data);
+1. Parameterize the variable of interest x(t) as a function f(z, θ, t) of a base variable z(t) with known density p\\_z.
+2. Use the transformation of variables formula to predict the density p\\_x as a function of the density p\\_z and the trace of the Jacobian of f.
+3. Choose the parameter θ to minimize a loss function of p\\_x (usually the negative likelihood of the data).
 
-After these steps one may use the NN model and the learned θ to predict the density p_x for new values of x.
+After these steps one may use the NN model and the learned θ to predict the density p\\_x for new values of x.
 
 Arguments:
-- `model`: A Flux.Chain or Lux.AbstractExplicitLayer neural network that defines the dynamics of the model.
+- `model`: A `Flux.Chain` or `Lux.AbstractExplicitLayer` neural network that defines the dynamics of the model.
 - `basedist`: Distribution of the base variable. Set to the unit normal by default.
 - `input_dims`: Input Dimensions of the model.
 - `tspan`: The timespan to be solved on.
@@ -236,9 +236,9 @@ by `pdf` or `logpdf` (from `Distributions.jl`).
 
 Arguments:
 
-- `model`: A FFJORD instance
-- `regularize`: Whether we use regularization (default: `false`)
-- `monte_carlo`: Whether we use monte carlo (default: `true`)
+- `model`: A FFJORD instance.
+- `regularize`: Whether we use regularization (default: `false`).
+- `monte_carlo`: Whether we use monte carlo (default: `true`).
 """
 @concrete struct FFJORDDistribution{F <: FFJORD} <: ContinuousMultivariateDistribution
     model::F
diff --git a/src/hnn.jl b/src/hnn.jl
@@ -16,7 +16,7 @@ Arguments:
 1. `model`: A `Flux.Chain` or `Lux.AbstractExplicitLayer` neural network that returns the
    Hamiltonian of the system.
 2. `ad`: The autodiff framework to be used for the internal Hamiltonian computation. The
-   default is `AutoForwardDiff()`
+   default is `AutoForwardDiff()`.
 
 !!! note
     If training with Zygote, ensure that the `chunksize` for `AutoForwardDiff` is set to
diff --git a/src/multiple_shooting.jl b/src/multiple_shooting.jl
@@ -96,20 +96,18 @@ Arguments:
 - `ode_data`: Original Data to be modelled.
 - `tsteps`: Timesteps on which ode_data was calculated.
 - `ensemble_prob`: Ensemble problem that the Neural Network attempts to solve.
-- `ensemble_alg`: Ensemble algorithm, e.g. `EnsembleThreads()`
+- `ensemble_alg`: Ensemble algorithm, e.g. `EnsembleThreads()`.
 - `prob`: ODE problem that the Neural Network attempts to solve.
 - `loss_function`: Any arbitrary function to calculate loss.
 - `continuity_loss`: Function that takes states ``\\hat{u}_{end}`` of group ``k`` and
-``u_{0}`` of group ``k+1`` as input and calculates prediction continuity loss between
-them. If no custom `continuity_loss` is specified, `sum(abs, û_end - u_0)` is used.
+  ``u_{0}`` of group ``k+1`` as input and calculates prediction continuity loss between
+  them. If no custom `continuity_loss` is specified, `sum(abs, û_end - u_0)` is used.
 - `solver`: ODE Solver algorithm.
 - `group_size`: The group size achieved after splitting the ode_data into equal sizes.
-- `continuity_term`: Weight term to ensure continuity of predictions throughout
-different groups.
+- `continuity_term`: Weight term to ensure continuity of predictions throughout different groups.
 - `kwargs`: Additional arguments splatted to the ODE solver. Refer to the
-[Local Sensitivity Analysis](https://docs.sciml.ai/SciMLSensitivity/stable/) and
-[Common Solver Arguments](https://docs.sciml.ai/DiffEqDocs/stable/basics/common_solver_opts/)
-documentation for more details.
+  [Local Sensitivity Analysis](https://docs.sciml.ai/SciMLSensitivity/stable/) and
+  [Common Solver Arguments](https://docs.sciml.ai/DiffEqDocs/stable/basics/common_solver_opts/) documentation for more details.
 
 !!! note
 
@@ -190,8 +188,8 @@ the reminding observations.
 
 Arguments:
 
-- `datasize`: amount of data points to be partitioned
-- `groupsize`: maximum amount of observations in each group
+- `datasize`: amount of data points to be partitioned.
+- `groupsize`: maximum amount of observations in each group.
 
 Example:
 ```julia-repl
diff --git a/src/neural_de.jl b/src/neural_de.jl
@@ -62,9 +62,9 @@ Constructs a neural stochastic differential equation (neural SDE) with diagonal
 
 Arguments:
 
-- `drift`: A Flux.Chain or Lux.AbstractExplicitLayer neural network that defines the drift
+- `drift`: A `Flux.Chain` or `Lux.AbstractExplicitLayer` neural network that defines the drift
   function.
-- `diffusion`: A Flux.Chain or Lux.AbstractExplicitLayer neural network that defines the
+- `diffusion`: A `Flux.Chain` or `Lux.AbstractExplicitLayer` neural network that defines the
   diffusion function. Should output a vector of the same size as the input.
 - `tspan`: The timespan to be solved on.
 - `alg`: The algorithm used to solve the ODE. Defaults to `nothing`, i.e. the
@@ -110,12 +110,12 @@ Constructs a neural stochastic differential equation (neural SDE).
 
 Arguments:
 
-- `drift`: A Flux.Chain or Lux.AbstractExplicitLayer neural network that defines the drift
+- `drift`: A `Flux.Chain` or `Lux.AbstractExplicitLayer` neural network that defines the drift
   function.
-- `diffusion`: A Flux.Chain or Lux.AbstractExplicitLayer neural network that defines the
+- `diffusion`: A `Flux.Chain` or `Lux.AbstractExplicitLayer` neural network that defines the
   diffusion function. Should output a matrix that is `nbrown x size(x, 1)`.
 - `tspan`: The timespan to be solved on.
-- `nbrown`: The number of Brownian processes
+- `nbrown`: The number of Brownian processes.
 - `alg`: The algorithm used to solve the ODE. Defaults to `nothing`, i.e. the
   default algorithm from DifferentialEquations.jl.
 - `sensealg`: The choice of differentiation algorithm used in the backpropogation.
@@ -162,7 +162,7 @@ Constructs a neural delay differential equation (neural DDE) with constant delay
 
 Arguments:
 
-- `model`: A Flux.Chain or Lux.AbstractExplicitLayer neural network that defines the
+- `model`: A `Flux.Chain` or `Lux.AbstractExplicitLayer` neural network that defines the
   derivative function. Should take an input of size `[x; x(t - lag_1); ...; x(t - lag_n)]`
   and produce and output shaped like `x`.
 - `tspan`: The timespan to be solved on.
@@ -215,7 +215,7 @@ Constructs a neural differential-algebraic equation (neural DAE).
 
 Arguments:
 
-- `model`: A Flux.Chain or Lux.AbstractExplicitLayer neural network that defines the
+- `model`: A `Flux.Chain` or `Lux.AbstractExplicitLayer` neural network that defines the
   derivative function. Should take an input of size `x` and produce the residual of
   `f(dx,x,t)` for only the differential variables.
 - `constraints_model`: A function `constraints_model(u,p,t)` for the fixed
@@ -285,11 +285,11 @@ constraint equations.
 
 Arguments:
 
-- `model`: A Flux.Chain or Lux.AbstractExplicitLayer neural network that defines the ̇`f(u,p,t)`
+- `model`: A `Flux.Chain` or `Lux.AbstractExplicitLayer` neural network that defines the ̇`f(u,p,t)`
 - `constraints_model`: A function `constraints_model(u,p,t)` for the fixed constraints to
   impose on the algebraic equations.
 - `tspan`: The timespan to be solved on.
-- `mass_matrix`: The mass matrix associated with the DAE
+- `mass_matrix`: The mass matrix associated with the DAE.
 - `alg`: The algorithm used to solve the ODE. Defaults to `nothing`, i.e. the default
   algorithm from DifferentialEquations.jl. This method requires an implicit ODE solver
   compatible with singular mass matrices. Consult the
@@ -340,8 +340,8 @@ Constructs an Augmented Neural Differential Equation Layer.
 
 Arguments:
 
-- `nde`: Any Neural Differential Equation Layer
-- `adim`: The number of dimensions the initial conditions should be lifted
+- `nde`: Any Neural Differential Equation Layer.
+- `adim`: The number of dimensions the initial conditions should be lifted.
 
 References:
 
diff --git a/src/spline_layer.jl b/src/spline_layer.jl
@@ -16,7 +16,7 @@ Arguments:
 - `spline_basis`: Interpolation method to be used yb the basis (current supported
   interpolation methods: `ConstantInterpolation`, `LinearInterpolation`,
   `QuadraticInterpolation`, `QuadraticSpline`, `CubicSpline`).
-- 'init_saved_points': values of the function at multiples of the time step. Initialized by
+- `init_saved_points`: values of the function at multiples of the time step. Initialized by
   default to a random vector sampled from the unit normal. Alternatively, can take a
   function with the signature `init_saved_points(rng, time_span, time_step)`.
 """
diff --git a/src/tensor_product.jl b/src/tensor_product.jl
@@ -10,7 +10,7 @@ end
 """
     ChebyshevBasis(n)
 
-Constructs a Chebyshev basis of the form [T_{0}(x), T_{1}(x), ..., T_{n-1}(x)] where T_j(.)
+Constructs a Chebyshev basis of the form [T\\_{0}(x), T\\_{1}(x), ..., T\\_{n-1}(x)] where T\\_j(.)
 is the j-th Chebyshev polynomial of the first kind.
 
 Arguments:
@@ -24,7 +24,7 @@ __chebyshev(i, x) = cos(i * acos(x))
 """
     SinBasis(n)
 
-Constructs a sine basis of the form [sin(x), sin(2*x), ..., sin(n*x)].
+Constructs a sine basis of the form [sin(x), sin(2x), ..., sin(nx)].
 
 Arguments:
 
@@ -35,7 +35,7 @@ SinBasis(n) = TensorProductBasisFunction(sin ∘ *, n)
 """
     CosBasis(n)
 
-Constructs a cosine basis of the form [cos(x), cos(2*x), ..., cos(n*x)].
+Constructs a cosine basis of the form [cos(x), cos(2x), ..., cos(nx)].
 
 Arguments:
 
@@ -47,7 +47,7 @@ CosBasis(n) = TensorProductBasisFunction(cos ∘ *, n)
     FourierBasis(n)
 
 Constructs a Fourier basis of the form
-F_j(x) = j is even ? cos((j÷2)*x) : sin((j÷2)*x) => [F_0(x), F_1(x), ..., F_n(x)].
+F\\_j(x) = j is even ? cos((j÷2)x) : sin((j÷2)x) => [F\\_0(x), F\\_1(x), ..., F\\_n(x)].
 
 Arguments:
 
@@ -60,8 +60,8 @@ __fourier(i::Int, x) = ifelse(iseven(i), cos(i * x / 2), sin(i * x / 2))
 """
     LegendreBasis(n)
 
-Constructs a Legendre basis of the form [P_{0}(x), P_{1}(x), ..., P_{n-1}(x)] where
-P_j(.) is the j-th Legendre polynomial.
+Constructs a Legendre basis of the form [P\\_{0}(x), P\\_{1}(x), ..., P\\_{n-1}(x)] where
+P\\_j(.) is the j-th Legendre polynomial.
 
 Arguments:
 
@@ -102,13 +102,13 @@ __polynomial(i, x) = x^(i - 1)
     TensorLayer(model, out_dim::Int, init_p::F = randn) where {F <: Function}
 
 Constructs the Tensor Product Layer, which takes as input an array of n tensor
-product basis, [B_1, B_2, ..., B_n] a data point x, computes
-z[i] = W[i,:] ⨀ [B_1(x[1]) ⨂ B_2(x[2]) ⨂ ... ⨂ B_n(x[n])], where W is the layer's weight,
+product basis, [B\\_1, B\\_2, ..., B\\_n] a data point x, computes
+z[i] = W[i, :] ⨀ [B\\_1(x[1]) ⨂ B\\_2(x[2]) ⨂ ... ⨂ B\\_n(x[n])], where W is the layer's weight,
 and returns [z[1], ..., z[out]].
 
 Arguments:
 
-- `model`: Array of TensorProductBasis [B_1(n_1), ..., B_k(n_k)], where k corresponds to the
+- `model`: Array of TensorProductBasis [B\\_1(n\\_1), ..., B\\_k(n\\_k)], where k corresponds to the
   dimension of the input.
 - `out`: Dimension of the output.
 - `p`: Optional initialization of the layer's weight. Initialized to standard normal by
