Small documentation issue (actionable)

[damianodegaspari]

First of all let me quickly say that I am new to Julia, new to GitHub, new to programming in general. If I'm showing inappropriate/inefficient/incorrect behaviour and/or actions please let me know. Among other considerations, I'm asking this as a question because of the following

10. You may not get a response here for packages with a very narrow audience. In that case, you may want to consider opening an issue on Github (or Gitlab, etc) for the package repository, just to ask a question. Most packages are OK with this.

in Tamas_Papp's post Please read: make it easier to help you" on Julia Discourse.

I was going through the DiffEqNoiseProcess.jl documentation and stumbled upon the following problem.

Trying to execute the blocks of code in the Direct Simulation of the Noise Process section, I get (from a fresh start of Julia):

julia> using DifferentialEquations

julia> μ = 1.0
1.0

julia> σ = 2.0
2.0

julia> W = GeometricBrownianMotionProcess(μ, σ, 0.0, 1.0, 1.0)
t: 1-element Vector{Float64}:
 0.0
u: 1-element Vector{Float64}:
 1.0

julia> prob = NoiseProblem(W, (0.0, 1.0))
NoiseProblem with WType Float64 and tType Float64. In-place: false
timespan: (0.0, 1.0)

julia> sol = solve(prob; dt = 0.1)
t: 11-element Vector{Float64}:
 0.0
 0.1
 0.2
 0.30000000000000004
 0.4
 0.5
 0.6
 0.7
 0.7999999999999999
 0.8999999999999999
 0.9999999999999999
u: 11-element Vector{Float64}:
 1.0
 0.45358738849107394
 0.17952397022691163
 0.13843702026586097
 0.15892086024998012
 0.12726817194665152
 0.05589566907491762
 0.04653757976133095
 0.02799639432864082
 0.02190658557517465
 0.010375593646497911

julia> enprob = EnsembleProblem(prob)
EnsembleProblem with problem NoiseProblem

julia> sol = solve(enprob; dt = 0.1, num_monte = 100)
ERROR: UndefKeywordError: keyword argument `trajectories` not assigned
Stacktrace:
 [1] __solve(prob::EnsembleProblem{NoiseProblem{NoiseProcess{Float64, 1, Float64, Float64, Float64, Vector{Float64}, DiffEqNoiseProcess.GeometricBrownianMotion{Float64, Float64}, DiffEqNoiseProcess.var"#34#35"{DiffEqNoiseProcess.GeometricBrownianMotion{Float64, Float64}}, false, ResettableStacks.ResettableStack{Tuple{Float64, Float64, Float64}, false}, ResettableStacks.ResettableStack{Tuple{Float64, Float64, Float64}, false}, RSWM{Float64}, Nothing, RandomNumbers.Xorshifts.Xoroshiro128Plus}, Tuple{Float64, Float64}, Base.Pairs{Symbol, Union{}, Tuple{}, NamedTuple{(), Tuple{}}}}, typeof(SciMLBase.DEFAULT_PROB_FUNC), typeof(SciMLBase.DEFAULT_OUTPUT_FUNC), typeof(SciMLBase.DEFAULT_REDUCTION), Nothing}, alg::Nothing; kwargs::Base.Pairs{Symbol, Real, Tuple{Symbol, Symbol}, NamedTuple{(:dt, :num_monte), Tuple{Float64, Int64}}})
   @ SciMLBase ~/.julia/packages/SciMLBase/2HZ5m/src/ensemble/basic_ensemble_solve.jl:100
 [2] solve(::EnsembleProblem{NoiseProblem{NoiseProcess{Float64, 1, Float64, Float64, Float64, Vector{Float64}, DiffEqNoiseProcess.GeometricBrownianMotion{Float64, Float64}, DiffEqNoiseProcess.var"#34#35"{DiffEqNoiseProcess.GeometricBrownianMotion{Float64, Float64}}, false, ResettableStacks.ResettableStack{Tuple{Float64, Float64, Float64}, false}, ResettableStacks.ResettableStack{Tuple{Float64, Float64, Float64}, false}, RSWM{Float64}, Nothing, RandomNumbers.Xorshifts.Xoroshiro128Plus}, Tuple{Float64, Float64}, Base.Pairs{Symbol, Union{}, Tuple{}, NamedTuple{(), Tuple{}}}}, typeof(SciMLBase.DEFAULT_PROB_FUNC), typeof(SciMLBase.DEFAULT_OUTPUT_FUNC), typeof(SciMLBase.DEFAULT_REDUCTION), Nothing}; kwargs::Base.Pairs{Symbol, Real, Tuple{Symbol, Symbol}, NamedTuple{(:dt, :num_monte), Tuple{Float64, Int64}}})
   @ DiffEqBase ~/.julia/packages/DiffEqBase/eTCPy/src/solve.jl:1075
 [3] top-level scope
   @ REPL[9]:1

I was also reading the section Ensemble Simulations in the documentation of the DifferentialEquation.jl package. With that knowledge I tried to run the following:

julia> sol = solve(enprob; dt = 0.1, trajectories = 100)
EnsembleSolution Solution of length 100 with uType:
NoiseProcess{Float64, 1, Float64, Float64, Float64, Vector{Float64}, DiffEqNoiseProcess.GeometricBrownianMotion{Float64, Float64}, DiffEqNoiseProcess.var"#34#35"{DiffEqNoiseProcess.GeometricBrownianMotion{Float64, Float64}}, false, ResettableStacks.ResettableStack{Tuple{Float64, Float64, Float64}, false}, ResettableStacks.ResettableStack{Tuple{Float64, Float64, Float64}, false}, RSWM{Float64}, Nothing, RandomNumbers.Xorshifts.Xoroshiro128Plus}

which seemed to work.

Additional outputs that are asked about in the GitHub section about opening a bug:

julia> using Pkg; Pkg.status()
Status `~/.julia/environments/v1.9/Project.toml`
  [0c46a032] DifferentialEquations v7.12.0
  [c3e4b0f8] Pluto v0.19.37

julia> using Pkg; Pkg.status(; mode = PKGMODE_MANIFEST)
Status `~/.julia/environments/v1.9/Manifest.toml`
  [47edcb42] ADTypes v0.2.6
⌅ [79e6a3ab] Adapt v3.7.2
  [ec485272] ArnoldiMethod v0.2.0
  [4fba245c] ArrayInterface v7.7.0
  [4c555306] ArrayLayouts v1.5.2
  [aae01518] BandedMatrices v1.4.0
  [6e4b80f9] BenchmarkTools v1.4.0
  [d1d4a3ce] BitFlags v0.1.8
  [62783981] BitTwiddlingConvenienceFunctions v0.1.5
⌃ [764a87c0] BoundaryValueDiffEq v5.6.0
  [fa961155] CEnum v0.5.0
  [2a0fbf3d] CPUSummary v0.2.4
  [49dc2e85] Calculus v0.5.1
  [fb6a15b2] CloseOpenIntervals v0.1.12
  [523fee87] CodecBzip2 v0.8.1
  [944b1d66] CodecZlib v0.7.3
  [38540f10] CommonSolve v0.2.4
  [bbf7d656] CommonSubexpressions v0.3.0
  [34da2185] Compat v4.12.0
  [2569d6c7] ConcreteStructs v0.2.3
  [f0e56b4a] ConcurrentUtilities v2.3.0
  [5218b696] Configurations v0.17.6
  [187b0558] ConstructionBase v1.5.4
  [adafc99b] CpuId v0.3.1
  [9a962f9c] DataAPI v1.16.0
  [864edb3b] DataStructures v0.18.16
  [e2d170a0] DataValueInterfaces v1.0.0
⌃ [bcd4f6db] DelayDiffEq v5.45.1
⌃ [2b5f629d] DiffEqBase v6.145.6
  [459566f4] DiffEqCallbacks v2.36.1
  [77a26b50] DiffEqNoiseProcess v5.20.0
  [163ba53b] DiffResults v1.1.0
  [b552c78f] DiffRules v1.15.1
  [0c46a032] DifferentialEquations v7.12.0
  [b4f34e82] Distances v0.10.11
  [31c24e10] Distributions v0.25.107
  [ffbed154] DocStringExtensions v0.9.3
  [fa6b7ba4] DualNumbers v0.6.8
  [4e289a0a] EnumX v1.0.4
  [f151be2c] EnzymeCore v0.6.5
  [460bff9d] ExceptionUnwrapping v0.1.10
  [d4d017d3] ExponentialUtilities v1.25.0
  [e2ba6199] ExprTools v0.1.10
  [21656369] ExpressionExplorer v1.0.0
  [55351af7] ExproniconLite v0.10.5
  [9d29842c] FastAlmostBandedMatrices v0.1.0
  [7034ab61] FastBroadcast v0.2.8
  [9aa1b823] FastClosures v0.3.2
  [29a986be] FastLapackInterface v2.0.0
  [1a297f60] FillArrays v1.9.3
  [6a86dc24] FiniteDiff v2.22.0
  [f6369f11] ForwardDiff v0.10.36
  [069b7b12] FunctionWrappers v1.1.3
  [77dc65aa] FunctionWrappersWrappers v0.1.3
  [d9f16b24] Functors v0.4.5
  [fb4132e2] FuzzyCompletions v0.5.3
⌃ [46192b85] GPUArraysCore v0.1.5
  [c145ed77] GenericSchur v0.5.3
  [86223c79] Graphs v1.9.0
  [cd3eb016] HTTP v1.10.1
  [3e5b6fbb] HostCPUFeatures v0.1.16
  [34004b35] HypergeometricFunctions v0.3.23
  [ac1192a8] HypertextLiteral v0.9.5
  [615f187c] IfElse v0.1.1
  [d25df0c9] Inflate v0.1.4
  [92d709cd] IrrationalConstants v0.2.2
  [82899510] IteratorInterfaceExtensions v1.0.0
  [692b3bcd] JLLWrappers v1.5.0
  [682c06a0] JSON v0.21.4
  [ccbc3e58] JumpProcesses v9.10.1
  [ef3ab10e] KLU v0.4.1
  [ba0b0d4f] Krylov v0.9.5
  [10f19ff3] LayoutPointers v0.1.15
  [0e77f7df] LazilyInitializedFields v1.2.2
  [50d2b5c4] Lazy v0.15.1
  [5078a376] LazyArrays v1.8.3
  [2d8b4e74] LevyArea v1.0.0
  [d3d80556] LineSearches v7.2.0
  [7ed4a6bd] LinearSolve v2.22.1
  [2ab3a3ac] LogExpFunctions v0.3.26
  [e6f89c97] LoggingExtras v1.0.3
  [bdcacae8] LoopVectorization v0.12.166
  [6c6e2e6c] MIMEs v0.1.4
  [1914dd2f] MacroTools v0.5.13
  [36869731] Malt v1.1.1
  [d125e4d3] ManualMemory v0.1.8
  [b8f27783] MathOptInterface v1.25.1
  [a3b82374] MatrixFactorizations v2.1.0
  [bb5d69b7] MaybeInplace v0.1.1
  [739be429] MbedTLS v1.1.9
  [e1d29d7a] Missings v1.1.0
  [99f44e22] MsgPack v1.2.1
  [46d2c3a1] MuladdMacro v0.2.4
  [d8a4904e] MutableArithmetics v1.4.0
  [d41bc354] NLSolversBase v7.8.3
  [2774e3e8] NLsolve v4.5.1
  [77ba4419] NaNMath v1.0.2
⌅ [8913a72c] NonlinearSolve v3.4.0
  [6fe1bfb0] OffsetArrays v1.13.0
  [4d8831e6] OpenSSL v1.4.1
  [429524aa] Optim v1.8.0
  [bac558e1] OrderedCollections v1.6.3
⌅ [1dea7af3] OrdinaryDiffEq v6.66.0
  [90014a1f] PDMats v0.11.31
  [65ce6f38] PackageExtensionCompat v1.0.2
  [d96e819e] Parameters v0.12.3
  [69de0a69] Parsers v2.8.1
  [c3e4b0f8] Pluto v0.19.37
  [e409e4f3] PoissonRandom v0.4.4
  [f517fe37] Polyester v0.7.9
  [1d0040c9] PolyesterWeave v0.2.1
  [85a6dd25] PositiveFactorizations v0.2.4
⌅ [d236fae5] PreallocationTools v0.4.13
  [91cefc8d] PrecompileSignatures v3.0.3
  [aea7be01] PrecompileTools v1.2.0
  [21216c6a] Preferences v1.4.1
  [1fd47b50] QuadGK v2.9.4
  [74087812] Random123 v1.6.2
  [e6cf234a] RandomNumbers v1.5.3
  [3cdcf5f2] RecipesBase v1.3.4
⌅ [731186ca] RecursiveArrayTools v3.3.3
  [f2c3362d] RecursiveFactorization v0.2.21
  [189a3867] Reexport v1.2.2
  [2792f1a3] RegistryInstances v0.1.0
  [05181044] RelocatableFolders v1.0.1
  [ae029012] Requires v1.3.0
  [ae5879a3] ResettableStacks v1.1.1
  [79098fc4] Rmath v0.7.1
  [7e49a35a] RuntimeGeneratedFunctions v0.5.12
  [94e857df] SIMDTypes v0.1.0
  [476501e8] SLEEFPirates v0.6.42
⌃ [0bca4576] SciMLBase v2.15.2
  [c0aeaf25] SciMLOperators v0.3.7
  [6c6a2e73] Scratch v1.2.1
  [efcf1570] Setfield v1.1.1
  [777ac1f9] SimpleBufferStream v1.1.0
  [727e6d20] SimpleNonlinearSolve v1.3.1
  [699a6c99] SimpleTraits v0.9.4
  [ce78b400] SimpleUnPack v1.1.0
  [a2af1166] SortingAlgorithms v1.2.1
  [47a9eef4] SparseDiffTools v2.16.0
  [e56a9233] Sparspak v0.3.9
  [276daf66] SpecialFunctions v2.3.1
  [aedffcd0] Static v0.8.8
  [0d7ed370] StaticArrayInterface v1.5.0
  [90137ffa] StaticArrays v1.9.1
  [1e83bf80] StaticArraysCore v1.4.2
  [82ae8749] StatsAPI v1.7.0
  [2913bbd2] StatsBase v0.34.2
  [4c63d2b9] StatsFuns v1.3.0
  [9672c7b4] SteadyStateDiffEq v2.0.1
  [789caeaf] StochasticDiffEq v6.64.0
  [7792a7ef] StrideArraysCore v0.5.2
  [c3572dad] Sundials v4.23.1
⌅ [2efcf032] SymbolicIndexingInterface v0.3.1
  [3783bdb8] TableTraits v1.0.1
  [bd369af6] Tables v1.11.1
  [8290d209] ThreadingUtilities v0.5.2
  [3bb67fe8] TranscodingStreams v0.10.2
  [d5829a12] TriangularSolve v0.1.20
  [410a4b4d] Tricks v0.1.8
  [781d530d] TruncatedStacktraces v1.4.0
  [5c2747f8] URIs v1.5.1
  [3a884ed6] UnPack v1.0.2
  [3d5dd08c] VectorizationBase v0.21.65
  [19fa3120] VertexSafeGraphs v0.2.0
  [6e34b625] Bzip2_jll v1.0.8+1
  [1d5cc7b8] IntelOpenMP_jll v2024.0.2+0
  [856f044c] MKL_jll v2024.0.0+0
  [458c3c95] OpenSSL_jll v3.0.12+0
  [efe28fd5] OpenSpecFun_jll v0.5.5+0
  [f50d1b31] Rmath_jll v0.4.0+0
⌅ [fb77eaff] Sundials_jll v5.2.1+0
  [0dad84c5] ArgTools v1.1.1
  [56f22d72] Artifacts
  [2a0f44e3] Base64
  [ade2ca70] Dates
  [8ba89e20] Distributed
  [f43a241f] Downloads v1.6.0
  [7b1f6079] FileWatching
  [9fa8497b] Future
  [b77e0a4c] InteractiveUtils
  [4af54fe1] LazyArtifacts
  [b27032c2] LibCURL v0.6.3
  [76f85450] LibGit2
  [8f399da3] Libdl
  [37e2e46d] LinearAlgebra
  [56ddb016] Logging
  [d6f4376e] Markdown
  [a63ad114] Mmap
  [ca575930] NetworkOptions v1.2.0
  [44cfe95a] Pkg v1.9.2
  [de0858da] Printf
  [9abbd945] Profile
  [3fa0cd96] REPL
  [9a3f8284] Random
  [ea8e919c] SHA v0.7.0
  [9e88b42a] Serialization
  [1a1011a3] SharedArrays
  [6462fe0b] Sockets
  [2f01184e] SparseArrays
  [10745b16] Statistics v1.9.0
  [4607b0f0] SuiteSparse
  [fa267f1f] TOML v1.0.3
  [a4e569a6] Tar v1.10.0
  [8dfed614] Test
  [cf7118a7] UUIDs
  [4ec0a83e] Unicode
  [e66e0078] CompilerSupportLibraries_jll v1.0.5+0
  [deac9b47] LibCURL_jll v7.84.0+0
  [29816b5a] LibSSH2_jll v1.10.2+0
  [c8ffd9c3] MbedTLS_jll v2.28.2+0
  [14a3606d] MozillaCACerts_jll v2022.10.11
  [4536629a] OpenBLAS_jll v0.3.21+4
  [05823500] OpenLibm_jll v0.8.1+0
  [bea87d4a] SuiteSparse_jll v5.10.1+6
  [83775a58] Zlib_jll v1.2.13+0
  [8e850b90] libblastrampoline_jll v5.8.0+0
  [8e850ede] nghttp2_jll v1.48.0+0
  [3f19e933] p7zip_jll v17.4.0+0
Info Packages marked with ⌃ and ⌅ have new versions available, but those with ⌅ are restricted by compatibility constraints from upgrading. To see why use `status --outdated -m`

julia> versioninfo()
Julia Version 1.9.2
Commit e4ee485e90 (2023-07-05 09:39 UTC)
Platform Info:
  OS: Linux (x86_64-redhat-linux)
  CPU: 12 × AMD Ryzen 5 PRO 4650U with Radeon Graphics
  WORD_SIZE: 64
  LIBM: libopenlibm
  LLVM: libLLVM-14.0.6 (ORCJIT, znver2)
  Threads: 1 on 12 virtual cores

Moreover, on that same page, one can read the following sentence: " For some noise process W, you can get its ith timepoint like W[i] and the associated time W.t[i]. If the NoiseProcess has a bridging distribution defined, it can be interpolated to arbitrary time points using W(t) " In my experiments this is true AFTER I define a NoiseProblem and solve it, whereas it is not true if I try to do it immediately after, e.g.

W = GeometricBrownianMotionProcess(μ, σ, 0.0, 1.0, 1.0)

This confused me at first, so I would rephrase that sentence. However, it is also very much possible that I was confused because I just started with all of this and still learning basic things.

Finally, I noticed that there are some "missing docstrings". I don't want to blame anybody, but I assume at some points those will be filled in. When that happens, I would suggest to also review and improve the already existing ones. Two small improvements I would make:

• specify what each letter is. For example, in the DiffEqNoiseProcess.WienerProcess, while it is clear (to me at least) what t0 and W0 are supposed to be, I didn't understand what Z0 is, and I could not find that information anywhere else. Nor could I say what the keyword arguments could be (maybe I didn't search long enough?) EDIT: One can find what Z0 is, in general, on the page The Standard AbstractNoiseProcess of the documentation. Sorry for that.
• one discovers that the aforementioned function allows one to use a complex brownian motion only when reading the docstring of DiffEqNoiseProcess.RealWienerProcess. I would add the comment made there for the function in my bullet point above.

I hope that I didn't go too long, either in not splitting this into two separate questions of in the effort of providing all the details I could think of.

[ChrisRackauckas]

It was a bit hard to find out what the actual question is in here, but I think it's addressed in https://github.com/SciML/DiffEqNoiseProcess.jl/pull/196

I didn't understand what Z0 is, and I could not find that information anywhere else.

This is an extra Brownian, used in SDE adpativity.

one discovers that the aforementioned function allows one to use a complex brownian motion only when reading the docstring of DiffEqNoiseProcess.RealWienerProcess. I would add the comment made there for the function in my bullet point above.

Which comment?