diff --git a/Manifest.toml b/Manifest.toml index 0dd105fc2..4277df10d 100644 --- a/Manifest.toml +++ b/Manifest.toml @@ -365,9 +365,9 @@ version = "0.3.14" [[deps.CategoricalArrays]] deps = ["Compat", "DataAPI", "Future", "Missings", "Printf", "Requires", "Statistics", "Unicode"] -git-tree-sha1 = "73acb4ed51b1855e1b5ce5c610334363a98d13f1" +git-tree-sha1 = "a6f644eb7bbc0171286f0f3ad1ffde8f04be7b83" uuid = "324d7699-5711-5eae-9e2f-1d82baa6b597" -version = "1.0.2" +version = "1.1.0" [deps.CategoricalArrays.extensions] CategoricalArraysArrowExt = "Arrow" @@ -620,13 +620,14 @@ version = "0.4.0" [[deps.DiffEqBase]] deps = ["ArrayInterface", "BracketingNonlinearSolve", "ConcreteStructs", "DocStringExtensions", "FastBroadcast", "FastClosures", "FastPower", "FunctionWrappers", "FunctionWrappersWrappers", "LinearAlgebra", "Logging", "Markdown", "MuladdMacro", "PrecompileTools", "Printf", "RecursiveArrayTools", "Reexport", "SciMLBase", "SciMLOperators", "SciMLStructures", "Setfield", "Static", "StaticArraysCore", "SymbolicIndexingInterface", "TruncatedStacktraces"] -git-tree-sha1 = "1719cd1b0a12e01775dc6db1577dd6ace1798fee" +git-tree-sha1 = "96e0d3006aac4a322691de81f0baedd38b62a0c4" uuid = "2b5f629d-d688-5b77-993f-72d75c75574e" -version = "6.210.1" +version = "6.211.0" [deps.DiffEqBase.extensions] DiffEqBaseCUDAExt = "CUDA" DiffEqBaseChainRulesCoreExt = "ChainRulesCore" + DiffEqBaseDynamicQuantitiesExt = "DynamicQuantities" DiffEqBaseEnzymeExt = ["ChainRulesCore", "Enzyme"] DiffEqBaseFlexUnitsExt = "FlexUnits" DiffEqBaseForwardDiffExt = ["ForwardDiff"] @@ -645,6 +646,7 @@ version = "6.210.1" CUDA = "052768ef-5323-5732-b1bb-66c8b64840ba" ChainRulesCore = "d360d2e6-b24c-11e9-a2a3-2a2ae2dbcce4" Distributions = "31c24e10-a181-5473-b8eb-7969acd0382f" + DynamicQuantities = "06fc5a27-2a28-4c7c-a15d-362465fb6821" Enzyme = "7da242da-08ed-463a-9acd-ee780be4f1d9" FlexUnits = "76e01b6b-c995-4ce6-8559-91e72a3d4e95" ForwardDiff = "f6369f11-7733-5829-9624-2563aa707210" @@ -799,9 +801,9 @@ version = "3.6.0" [[deps.DynamicPPL]] deps = ["ADTypes", "AbstractMCMC", "AbstractPPL", "Accessors", "BangBang", "Bijectors", "Chairmarks", "Compat", "ConstructionBase", "DifferentiationInterface", "Distributions", "DocStringExtensions", "FillArrays", "InteractiveUtils", "LinearAlgebra", "LogDensityProblems", "MacroTools", "OrderedCollections", "PrecompileTools", "Printf", "Random", "Statistics", "Test"] -git-tree-sha1 = "9b4203a175a2b49963711899d4d25e10c25d14ae" +git-tree-sha1 = "14ded43f8a62568b17efc62d9f04491a2d4d8c9b" uuid = "366bfd00-2699-11ea-058f-f148b4cae6d8" -version = "0.40.7" +version = "0.40.14" [deps.DynamicPPL.extensions] DynamicPPLEnzymeCoreExt = ["EnzymeCore"] @@ -833,9 +835,9 @@ version = "1.0.7" [[deps.Enzyme]] deps = ["CEnum", "EnzymeCore", "Enzyme_jll", "GPUCompiler", "InteractiveUtils", "LLVM", "Libdl", "LinearAlgebra", "ObjectFile", "PrecompileTools", "Preferences", "Printf", "Random", "SparseArrays"] -git-tree-sha1 = "ea65d3121f09b5f31102542db9445163b7c99182" +git-tree-sha1 = "03eda226219a3cf21cda8f7b56c5de7ab8c923a6" uuid = "7da242da-08ed-463a-9acd-ee780be4f1d9" -version = "0.13.129" +version = "0.13.131" [deps.Enzyme.extensions] EnzymeBFloat16sExt = "BFloat16s" @@ -866,9 +868,9 @@ weakdeps = ["Adapt", "ChainRulesCore"] [[deps.Enzyme_jll]] deps = ["Artifacts", "JLLWrappers", "LazyArtifacts", "Libdl", "TOML"] -git-tree-sha1 = "fea21cfc452db42e3878aab62a76896e76d54d12" +git-tree-sha1 = "f9e4e3c5c543ba1bcafc103d680e57d95ce1a1cb" uuid = "7cc45869-7501-5eee-bdea-0790c847d4ef" -version = "0.0.249+0" +version = "0.0.251+0" [[deps.EpollShim_jll]] deps = ["Artifacts", "JLLWrappers", "Libdl"] @@ -920,10 +922,10 @@ uuid = "c87230d0-a227-11e9-1b43-d7ebe4e7570a" version = "0.4.5" [[deps.FFMPEG_jll]] -deps = ["Artifacts", "Bzip2_jll", "FreeType2_jll", "FriBidi_jll", "JLLWrappers", "LAME_jll", "Libdl", "Ogg_jll", "OpenSSL_jll", "Opus_jll", "PCRE2_jll", "Zlib_jll", "libaom_jll", "libass_jll", "libfdk_aac_jll", "libvorbis_jll", "x264_jll", "x265_jll"] -git-tree-sha1 = "01ba9d15e9eae375dc1eb9589df76b3572acd3f2" +deps = ["Artifacts", "Bzip2_jll", "FreeType2_jll", "FriBidi_jll", "JLLWrappers", "LAME_jll", "Libdl", "Ogg_jll", "OpenSSL_jll", "Opus_jll", "PCRE2_jll", "Zlib_jll", "libaom_jll", "libass_jll", "libfdk_aac_jll", "libva_jll", "libvorbis_jll", "x264_jll", "x265_jll"] +git-tree-sha1 = "66381d7059b5f3f6162f28831854008040a4e905" uuid = "b22a6f82-2f65-5046-a5b2-351ab43fb4e5" -version = "8.0.1+0" +version = "8.0.1+1" [[deps.FFTA]] deps = ["AbstractFFTs", "DocStringExtensions", "LinearAlgebra", "MuladdMacro", "Primes", "Random", "Reexport"] @@ -1195,9 +1197,9 @@ version = "1.0.2" [[deps.HTTP]] deps = ["Base64", "CodecZlib", "ConcurrentUtilities", "Dates", "ExceptionUnwrapping", "Logging", "LoggingExtras", "MbedTLS", "NetworkOptions", "OpenSSL", "PrecompileTools", "Random", "SimpleBufferStream", "Sockets", "URIs", "UUIDs"] -git-tree-sha1 = "5e6fe50ae7f23d171f44e311c2960294aaa0beb5" +git-tree-sha1 = "51059d23c8bb67911a2e6fd5130229113735fc7e" uuid = "cd3eb016-35fb-5094-929b-558a96fad6f3" -version = "1.10.19" +version = "1.11.0" [[deps.HarfBuzz_jll]] deps = ["Artifacts", "Cairo_jll", "Fontconfig_jll", "FreeType2_jll", "Glib_jll", "Graphite2_jll", "JLLWrappers", "Libdl", "Libffi_jll"] @@ -1399,9 +1401,9 @@ version = "0.10.67" [[deps.Krylov]] deps = ["LinearAlgebra", "Printf", "SparseArrays"] -git-tree-sha1 = "125d65fe5042faf078383312dd060adf11d90802" +git-tree-sha1 = "c4d19f51afc7ba2afbe32031b8f2d21b11c9e26e" uuid = "ba0b0d4f-ebba-5204-a429-3ac8c609bfb7" -version = "0.10.5" +version = "0.10.6" [[deps.LAME_jll]] deps = ["Artifacts", "JLLWrappers", "Libdl"] @@ -1591,9 +1593,9 @@ version = "1.11.0" [[deps.LinearSolve]] deps = ["ArrayInterface", "ChainRulesCore", "ConcreteStructs", "DocStringExtensions", "EnumX", "GPUArraysCore", "InteractiveUtils", "Krylov", "Libdl", "LinearAlgebra", "MKL_jll", "Markdown", "OpenBLAS_jll", "PrecompileTools", "Preferences", "RecursiveArrayTools", "Reexport", "SciMLBase", "SciMLLogging", "SciMLOperators", "Setfield", "StaticArraysCore"] -git-tree-sha1 = "ba64436736405d666e0d22d54ee0e1b04e2e2b02" +git-tree-sha1 = "57a7bea58da7de6906f2621294ea35656cb40c5f" uuid = "7ed4a6bd-45f5-4d41-b270-4a48e9bafcae" -version = "3.64.0" +version = "3.66.0" [deps.LinearSolve.extensions] LinearSolveAMDGPUExt = "AMDGPU" @@ -1985,12 +1987,13 @@ version = "0.8.1" [[deps.Mooncake]] deps = ["ADTypes", "ChainRules", "ChainRulesCore", "DispatchDoctor", "ExprTools", "Graphs", "LinearAlgebra", "MistyClosures", "PrecompileTools", "Random", "Test"] -git-tree-sha1 = "bf6df81be03543cd072367880d729a331c5048a5" +git-tree-sha1 = "1236599308fd233ff4021c71cab859a0207164d7" uuid = "da2b9cff-9c12-43a0-ae48-6db2b0edb7d6" -version = "0.5.17" +version = "0.5.23" [deps.Mooncake.extensions] MooncakeAllocCheckExt = "AllocCheck" + MooncakeBFloat16sExt = "BFloat16s" MooncakeCUDAExt = "CUDA" MooncakeDistributionsExt = "Distributions" MooncakeDynamicExpressionsExt = "DynamicExpressions" @@ -2000,11 +2003,13 @@ version = "0.5.17" MooncakeLogExpFunctionsExt = "LogExpFunctions" MooncakeLuxLibExt = ["LuxLib", "MLDataDevices", "Static"] MooncakeLuxLibSLEEFPiratesExtension = ["LuxLib", "SLEEFPirates"] - MooncakeNNlibExt = ["NNlib", "GPUArraysCore"] + MooncakeNNlibExt = ["NNlib", "GPUArraysCore", "LinearAlgebra"] MooncakeSpecialFunctionsExt = "SpecialFunctions" + MooncakecuDNNExt = ["CUDA", "cuDNN"] [deps.Mooncake.weakdeps] AllocCheck = "9b6a8646-10ed-4001-bbdc-1d2f46dfbb1a" + BFloat16s = "ab4f0b2a-ad5b-11e8-123f-65d77653426b" CUDA = "052768ef-5323-5732-b1bb-66c8b64840ba" Distributions = "31c24e10-a181-5473-b8eb-7969acd0382f" DynamicExpressions = "a40a106e-89c9-4ca8-8020-a735e8728b6b" @@ -2019,6 +2024,7 @@ version = "0.5.17" SLEEFPirates = "476501e8-09a2-5ece-8869-fb82de89a1fa" SpecialFunctions = "276daf66-3868-5448-9aa4-cd146d93841b" Static = "aedffcd0-7271-4cad-89d0-dc628f76c6d3" + cuDNN = "02a925ec-e4fe-4b08-9a7e-0d78e3d38ccd" [[deps.Moshi]] deps = ["ExproniconLite", "Jieko"] @@ -2298,42 +2304,46 @@ uuid = "7f7a1694-90dd-40f0-9382-eb1efda571ba" version = "5.5.0" [[deps.OptimizationBase]] -deps = ["ADTypes", "ArrayInterface", "DifferentiationInterface", "DocStringExtensions", "FastClosures", "LinearAlgebra", "PDMats", "PrecompileTools", "Reexport", "SciMLBase", "SciMLLogging", "SparseArrays", "SparseConnectivityTracer", "SparseMatrixColorings"] -git-tree-sha1 = "710cce5771c03bf11e133bc4353c342acdf7cc29" +deps = ["ADTypes", "ArrayInterface", "DifferentiationInterface", "DocStringExtensions", "FastClosures", "LinearAlgebra", "PDMats", "PrecompileTools", "Reexport", "SciMLBase", "SciMLLogging", "SparseArrays", "SparseConnectivityTracer", "SparseMatrixColorings", "SymbolicIndexingInterface"] +git-tree-sha1 = "a3d7837832e515111c95a02df7dc55edbdf17d8a" uuid = "bca83a33-5cc9-4baa-983d-23429ab6bcbb" -version = "5.0.0" +version = "5.1.0" [deps.OptimizationBase.extensions] - OptimizationEnzymeExt = "Enzyme" + OptimizationChainRulesCoreExt = "ChainRulesCore" + OptimizationEnzymeExt = ["ChainRulesCore", "Enzyme"] OptimizationFiniteDiffExt = "FiniteDiff" OptimizationForwardDiffExt = "ForwardDiff" OptimizationMLDataDevicesExt = "MLDataDevices" OptimizationMLUtilsExt = "MLUtils" + OptimizationMooncakeExt = "Mooncake" OptimizationReverseDiffExt = "ReverseDiff" OptimizationSymbolicAnalysisExt = "SymbolicAnalysis" OptimizationZygoteExt = "Zygote" [deps.OptimizationBase.weakdeps] + ChainRulesCore = "d360d2e6-b24c-11e9-a2a3-2a2ae2dbcce4" Enzyme = "7da242da-08ed-463a-9acd-ee780be4f1d9" FiniteDiff = "6a86dc24-6348-571c-b903-95158fe2bd41" ForwardDiff = "f6369f11-7733-5829-9624-2563aa707210" MLDataDevices = "7e8f7934-dd98-4c1a-8fe8-92b47a384d40" MLUtils = "f1d291b0-491e-4a28-83b9-f70985020b54" + Mooncake = "da2b9cff-9c12-43a0-ae48-6db2b0edb7d6" ReverseDiff = "37e2e3b7-166d-5795-8a7a-e32c996b4267" SymbolicAnalysis = "4297ee4d-0239-47d8-ba5d-195ecdf594fe" Zygote = "e88e6eb3-aa80-5325-afca-941959d7151f" [[deps.OptimizationNLopt]] deps = ["NLopt", "OptimizationBase", "Random", "Reexport", "SciMLBase"] -git-tree-sha1 = "127bbb0ed9968f8d93a73d60ff7eaaa48947726c" +git-tree-sha1 = "c266ab38c83b58dc5bb74f718f4b33d24d2dc0b6" uuid = "4e6fcdb7-1186-4e1f-a706-475e75c168bb" -version = "0.3.9" +version = "0.3.10" [[deps.OptimizationOptimJL]] deps = ["Optim", "OptimizationBase", "Reexport", "SciMLBase", "SparseArrays"] -git-tree-sha1 = "615ffed7e1e032fd000aabb5046dc4c976a4afca" +git-tree-sha1 = "eb89577770d4a956010745f182ebea9d8ea714f8" uuid = "36348300-93cb-4f02-beb5-3c3902f8871e" -version = "0.4.10" +version = "0.4.11" [[deps.Opus_jll]] deps = ["Artifacts", "JLLWrappers", "Libdl"] @@ -2366,9 +2376,9 @@ version = "1.22.0" [[deps.OrdinaryDiffEqCore]] deps = ["ADTypes", "Accessors", "Adapt", "ArrayInterface", "ConcreteStructs", "DataStructures", "DiffEqBase", "DocStringExtensions", "EnumX", "EnzymeCore", "FastBroadcast", "FastClosures", "FastPower", "FillArrays", "FunctionWrappersWrappers", "InteractiveUtils", "LinearAlgebra", "Logging", "MacroTools", "MuladdMacro", "Polyester", "PrecompileTools", "Preferences", "Random", "RecursiveArrayTools", "Reexport", "SciMLBase", "SciMLLogging", "SciMLOperators", "SciMLStructures", "Static", "StaticArrayInterface", "StaticArraysCore", "SymbolicIndexingInterface", "TruncatedStacktraces"] -git-tree-sha1 = "e051c1fb69b1cb1511a00161b97e7a79e0b70687" +git-tree-sha1 = "b4a8d9b96931c2fc69126233bbe6d1a11b053d77" uuid = "bbf590c4-e513-4bbe-9b18-05decba2e5d8" -version = "3.17.0" +version = "3.22.0" weakdeps = ["Mooncake", "SparseArrays"] [deps.OrdinaryDiffEqCore.extensions] @@ -2811,9 +2821,9 @@ weakdeps = ["FixedPointNumbers"] [[deps.ReactantCore]] deps = ["ExpressionExplorer", "MacroTools"] -git-tree-sha1 = "f3e31b90afcd152578a6c389eae46dd38b9a4f38" +git-tree-sha1 = "f40fa78679f0d5584f6b83abed10e78c34d8bd9d" uuid = "a3311ec8-5e00-46d5-b541-4f83e724a433" -version = "0.1.16" +version = "0.1.17" [[deps.RealDot]] deps = ["LinearAlgebra"] @@ -2953,9 +2963,9 @@ version = "0.6.1" [[deps.SciMLBase]] deps = ["ADTypes", "Accessors", "Adapt", "ArrayInterface", "CommonSolve", "ConstructionBase", "Distributed", "DocStringExtensions", "EnumX", "FunctionWrappersWrappers", "IteratorInterfaceExtensions", "LinearAlgebra", "Logging", "Markdown", "Moshi", "PreallocationTools", "PrecompileTools", "Preferences", "Printf", "RecipesBase", "RecursiveArrayTools", "Reexport", "RuntimeGeneratedFunctions", "SciMLLogging", "SciMLOperators", "SciMLPublic", "SciMLStructures", "StaticArraysCore", "Statistics", "SymbolicIndexingInterface"] -git-tree-sha1 = "4675d321bfebe190d22dc4d9de6af7e318d5174a" +git-tree-sha1 = "0be0208add9b6836a701e0ac3ad30bda72fee51d" uuid = "0bca4576-84f4-4d90-8ffe-ffa030f20462" -version = "2.148.0" +version = "2.150.0" [deps.SciMLBase.extensions] SciMLBaseChainRulesCoreExt = "ChainRulesCore" @@ -3030,9 +3040,9 @@ version = "1.0.1" [[deps.SciMLSensitivity]] deps = ["ADTypes", "Accessors", "Adapt", "ArrayInterface", "ChainRulesCore", "ConstructionBase", "DiffEqBase", "DiffEqCallbacks", "DiffEqNoiseProcess", "Distributions", "Enzyme", "FastBroadcast", "FiniteDiff", "ForwardDiff", "FunctionProperties", "FunctionWrappersWrappers", "Functors", "GPUArraysCore", "LinearAlgebra", "LinearSolve", "Markdown", "OrdinaryDiffEqCore", "PreallocationTools", "QuadGK", "Random", "RandomNumbers", "RecursiveArrayTools", "Reexport", "ReverseDiff", "SciMLBase", "SciMLJacobianOperators", "SciMLLogging", "SciMLStructures", "SparseArrays", "StaticArrays", "StaticArraysCore", "Statistics", "SymbolicIndexingInterface", "Tracker", "Zygote"] -git-tree-sha1 = "d8861efbd815a4d461f547d9010d5ef920de5f9e" +git-tree-sha1 = "06508b66e7cbef5d15d53dbe5d05c4ad97df1f11" uuid = "1ed8b502-d754-442c-8d5d-10ac956f44a1" -version = "7.98.1" +version = "7.99.0" [deps.SciMLSensitivity.extensions] SciMLSensitivityMooncakeExt = "Mooncake" @@ -3056,9 +3066,9 @@ version = "3.1.0" [[deps.ScopedValues]] deps = ["HashArrayMappedTries", "Logging"] -git-tree-sha1 = "c3b2323466378a2ba15bea4b2f73b081e022f473" +git-tree-sha1 = "ac4b837d89a58c848e85e698e2a2514e9d59d8f6" uuid = "7e506255-f358-4e82-b7e4-beb19740aa63" -version = "1.5.0" +version = "1.6.0" [[deps.Scratch]] deps = ["Dates"] @@ -3163,9 +3173,9 @@ version = "0.1.2" [[deps.SparseMatrixColorings]] deps = ["ADTypes", "DocStringExtensions", "LinearAlgebra", "PrecompileTools", "Random", "SparseArrays"] -git-tree-sha1 = "7b2263c87aa890bf6d18ae05cedbe259754e3f34" +git-tree-sha1 = "fa43a02c01e3e3cb065c89bf9b648b89e3c06f18" uuid = "0a514795-09f3-496d-8182-132a7b665d35" -version = "0.4.24" +version = "0.4.25" [deps.SparseMatrixColorings.extensions] SparseMatrixColoringsCUDAExt = "CUDA" @@ -3221,9 +3231,9 @@ weakdeps = ["OffsetArrays", "StaticArrays"] [[deps.StaticArrays]] deps = ["LinearAlgebra", "PrecompileTools", "Random", "StaticArraysCore"] -git-tree-sha1 = "0f529006004a8be48f1be25f3451186579392d47" +git-tree-sha1 = "246a8bb2e6667f832eea063c3a56aef96429a3db" uuid = "90137ffa-7385-5640-81b9-e52037218182" -version = "1.9.17" +version = "1.9.18" weakdeps = ["ChainRulesCore", "Statistics"] [deps.StaticArrays.extensions] @@ -3355,16 +3365,18 @@ version = "0.3.1" [[deps.StructUtils]] deps = ["Dates", "UUIDs"] -git-tree-sha1 = "28145feabf717c5d65c1d5e09747ee7b1ff3ed13" +git-tree-sha1 = "b4075a491f3cb24e3beea0c192959292f80e1ad8" uuid = "ec057cc2-7a8d-4b58-b3b3-92acb9f63b42" -version = "2.6.3" +version = "2.7.0" [deps.StructUtils.extensions] StructUtilsMeasurementsExt = ["Measurements"] + StructUtilsStaticArraysCoreExt = ["StaticArraysCore"] StructUtilsTablesExt = ["Tables"] [deps.StructUtils.weakdeps] Measurements = "eff96d63-e80a-5855-80a2-b1b0885c5ab7" + StaticArraysCore = "1e83bf80-4336-4d27-bf5d-d5a4f845583c" Tables = "bd369af6-aec1-5ad0-b16a-f7cc5008161c" [[deps.StyledStrings]] @@ -3543,9 +3555,9 @@ version = "1.6.0" [[deps.Turing]] deps = ["ADTypes", "AbstractMCMC", "AbstractPPL", "Accessors", "AdvancedHMC", "AdvancedMH", "AdvancedPS", "AdvancedVI", "BangBang", "Bijectors", "Compat", "DataStructures", "DifferentiationInterface", "Distributions", "DocStringExtensions", "DynamicPPL", "EllipticalSliceSampling", "ForwardDiff", "Libtask", "LinearAlgebra", "LogDensityProblems", "MCMCChains", "Optimization", "OptimizationOptimJL", "OrderedCollections", "Printf", "Random", "Reexport", "SciMLBase", "SpecialFunctions", "Statistics", "StatsAPI", "StatsBase", "StatsFuns"] -git-tree-sha1 = "45ddf0d7564c7723760ff22e39fde90a87cd12c5" +git-tree-sha1 = "05e4dd6cfcaaa38e423c054a82aa3a43abd9a5b3" uuid = "fce5fe82-541a-59a6-adf8-730c64b5f9a0" -version = "0.43.0" +version = "0.43.2" weakdeps = ["DynamicHMC"] [deps.Turing.extensions] @@ -3718,6 +3730,12 @@ git-tree-sha1 = "7ed9347888fac59a618302ee38216dd0379c480d" uuid = "ea2f1a96-1ddc-540d-b46f-429655e07cfa" version = "0.9.12+0" +[[deps.Xorg_libpciaccess_jll]] +deps = ["Artifacts", "JLLWrappers", "Libdl", "Zlib_jll"] +git-tree-sha1 = "4909eb8f1cbf6bd4b1c30dd18b2ead9019ef2fad" +uuid = "a65dc6b1-eb27-53a1-bb3e-dea574b5389e" +version = "0.18.1+0" + [[deps.Xorg_libxcb_jll]] deps = ["Artifacts", "JLLWrappers", "Libdl", "Xorg_libXau_jll", "Xorg_libXdmcp_jll"] git-tree-sha1 = "bfcaf7ec088eaba362093393fe11aa141fa15422" @@ -3854,6 +3872,12 @@ git-tree-sha1 = "9bf7903af251d2050b467f76bdbe57ce541f7f4f" uuid = "1183f4f0-6f2a-5f1a-908b-139f9cdfea6f" version = "0.2.2+0" +[[deps.libdrm_jll]] +deps = ["Artifacts", "JLLWrappers", "Libdl", "Xorg_libpciaccess_jll"] +git-tree-sha1 = "63aac0bcb0b582e11bad965cef4a689905456c03" +uuid = "8e53e030-5e6c-5a89-a30b-be5b7263a166" +version = "2.4.125+1" + [[deps.libevdev_jll]] deps = ["Artifacts", "JLLWrappers", "Libdl"] git-tree-sha1 = "56d643b57b188d30cccc25e331d416d3d358e557" @@ -3878,6 +3902,12 @@ git-tree-sha1 = "e015f211ebb898c8180887012b938f3851e719ac" uuid = "b53b4c65-9356-5827-b1ea-8c7a1a84506f" version = "1.6.55+0" +[[deps.libva_jll]] +deps = ["Artifacts", "JLLWrappers", "Libdl", "Xorg_libX11_jll", "Xorg_libXext_jll", "Xorg_libXfixes_jll", "libdrm_jll"] +git-tree-sha1 = "7dbf96baae3310fe2fa0df0ccbb3c6288d5816c9" +uuid = "9a156e7d-b971-5f62-b2c9-67348b8fb97c" +version = "2.23.0+0" + [[deps.libvorbis_jll]] deps = ["Artifacts", "JLLWrappers", "Libdl", "Ogg_jll"] git-tree-sha1 = "11e1772e7f3cc987e9d3de991dd4f6b2602663a5" diff --git a/_quarto.yml b/_quarto.yml index d9e4f38f7..883be4de2 100644 --- a/_quarto.yml +++ b/_quarto.yml @@ -108,10 +108,17 @@ website: - tutorials/gaussian-processes-introduction/index.qmd - tutorials/gaussian-process-latent-variable-models/index.qmd - - section: "Developers" + - section: "Contributing" contents: - - developers/contributing/index.qmd + - contributing/start-contributing/index.qmd + - contributing/documentation/index.qmd + - contributing/tests/index.qmd + - contributing/code-formatting/index.qmd + - contributing/pull-requests/index.qmd + - contributing/core-developers/index.qmd + - section: "Developers" + contents: - section: "DynamicPPL's Compiler" collapse-level: 1 contents: @@ -214,7 +221,12 @@ usage-tracking-extra-quantities: usage/tracking-extra-quantities usage-troubleshooting: usage/troubleshooting usage-varnamedtuple: usage/varnamedtuple -contributing-guide: developers/contributing +contributing-start: contributing/start-contributing +contributing-documentation: contributing/documentation +contributing-tests: contributing/tests +contributing-pull-requests: contributing/pull-requests +contributing-code-formatting: contributing/code-formatting +contributing-core-developers: contributing/core-developers dev-model-manual: developers/compiler/model-manual contexts: developers/compiler/minituring-contexts minituring: developers/compiler/minituring-compiler diff --git a/contributing/code-formatting/index.qmd b/contributing/code-formatting/index.qmd new file mode 100644 index 000000000..19a1f3c76 --- /dev/null +++ b/contributing/code-formatting/index.qmd @@ -0,0 +1,72 @@ +--- +title: Code Formatting +--- + +The TuringLang ecosystem currently uses [JuliaFormatter.jl](https://github.com/domluna/JuliaFormatter.jl) to ensure consistent code style across the codebase. +All code must be formatted before submitting a pull request, and ideally with every commit. + +# Basic usage + +We use v1 of JuliaFormatter (as of the time of writing, JuliaFormatter v2 is still somewhat unreliable). +Make sure to install it in your *global* Julia environment (not the project environment, as adding it to the `Project.toml` would make it an invalid dependency of the project): + +```julia +# Do not include `--project=...` here +julia -e 'using Pkg; Pkg.add(name="JuliaFormatter", version="1"); Pkg.pin("JuliaFormatter")' +``` + +To format all Julia files in the current directory and subdirectories: + +```julia +julia -e 'using JuliaFormatter; format(".")' +``` + +Run this command from the root of the repository before committing your changes. + +# Faster Formatting + +:::{.callout-note} +This section is optional, but highly recommended if you are comfortable with Julia and are working on Turing codebases regularly. +::: + +Running `julia -e ...`, especially on v1 of JuliaFormatter, can be very slow due to Julia's TTFX. +To get around this, you can use [PackageCompiler.jl](https://julialang.github.io/PackageCompiler.jl/) to create a custom sysimage, which already includes cached compiled versions of JuliaFormatter's functions. +In our experience, this has led to drastic improvements in formatting speed: for example, on DynamicPPL.jl it slashes the formatting time from around 6 seconds to 0.5 seconds. + +The easiest way to do so is to directly copy [the code in this GitHub Gist](https://gist.github.com/penelopeysm/9338c160eeb05437205535c2edcf80ee) into your shell configuration file (e.g. `~/.bash_profile`). +You can of course modify this as you see fit. +Once you have done this (and started a new shell session), you can simply use the `jf1` command to format your code, which will be *much* faster than the previous method. + +# Pre-commit hook + +We do not currently have [pre-commit hooks](https://pre-commit.com/) for code formatting, but you can include your own if you wish. + +To do so, add this to `.pre-commit-config.yaml` at the top level of the repository, and then run `pre-commit install` to set up the hook. + +```yaml +repos: +- repo: "https://github.com/domluna/JuliaFormatter.jl" + rev: "v1.0.62" + hooks: + - id: "julia-formatter" +``` + +:::{.callout-note} +If you are intending to format on every commit, you will likely find that the basic `julia -e ...` method is intolerably slow! +We therefore recommend using the PackageCompiler-enabled method for the pre-commit hook. +::: + +If you are using the faster PackageCompiler-enabled method, use the following instead (adapt as necessary if you made any changes to the function): + +```yaml +repos: +- repo: local + hooks: + - id: format + name: format + language: system + entry: bash -c 'source ~/.bash_profile; jf1' +``` + +However, in either case, please make sure that you do not commit this file to the repository. +To avoid accidentally doing so, you can add `.pre-commit-config.yaml` to `.git/info/exclude` (which is like a local `.gitignore` that is not part of source control). \ No newline at end of file diff --git a/contributing/core-developers/index.qmd b/contributing/core-developers/index.qmd new file mode 100644 index 000000000..d24a45d3f --- /dev/null +++ b/contributing/core-developers/index.qmd @@ -0,0 +1,34 @@ +--- +title: For Core Developers +--- + +This page contains notes that are specific to core developers of TuringLang. +Everything on the other Contributing pages applies to core devs too; this is just the extra stuff. + +# Branches and PRs + +You don't need to make your own fork of the package you are editing. +Just make a new branch on the main repository, usually named `your-username/change-you-are-making` (we don't strictly enforce this convention though). +You should definitely still make a branch and a PR, and never push directly to `main` or `breaking`. + +All code should generally be reviewed by another core developer and pass continuous integration (CI) checks. +Exceptions can be made in some cases though, such as ignoring failing CI checks where the cause is known and not due to the current pull request, or skipping code review when the pull request author is an experienced developer of the package and the changes are trivial. + +# Making a release + +You can make a release of the package after your work is merged into `main`. +This is done by leaving a comment on the latest commit on `main`, saying + +``` +@JuliaRegistrator register + +Release notes: + +[YOUR RELEASE NOTES HERE] +``` + +It is often easiest to take the release notes right from the `HISTORY.md` file (which is why we ask that PRs include changelog entries). + +If you are making a breaking release, your release notes must also contain the string `Breaking changes` somewhere in them (this is mandated by the `@JuliaRegistrator` bot). + +The `@JuliaRegistrator` bot will handle creating a pull request into the Julia central package repository and tagging a new release in the repository. diff --git a/contributing/documentation/index.qmd b/contributing/documentation/index.qmd new file mode 100644 index 000000000..f46de53bd --- /dev/null +++ b/contributing/documentation/index.qmd @@ -0,0 +1,75 @@ +--- +title: Documentation +--- + +# Navigating Turing's documentation system + +Each of the packages in the Turing ecosystem (see [Libraries](/library)) has its own documentation, which is typically found in the `docs` folder of the corresponding package. +For example, the source code for DynamicPPL's documentation can be found in [its repository](https://github.com/TuringLang/DynamicPPL.jl). + +On top of the library-specific documentation, we also have a general documentation repository, which is what builds the website you are currently reading! +Anything that appears in `turinglang.org/docs` is built from the [`docs` repository](https://github.com/TuringLang/docs). + +Other sections of the website (anything that isn't a package, or a tutorial) – for example, the list of libraries – is built from the [`turinglang.github.io` repository](https://github.com/TuringLang/turinglang.github.io). + +*In general, we prefer documentation for Turing users to be written on the `docs` repository.* +This is because it is more easily discoverable for users via the search bar and sidebar. + +Documentation written on the individual package repositories can be found via the main site's search bar (due to a GitHub workflow that scrapes all the packages' contents and indexes them here), but once you navigate to a package's documentation, you cannot then use the sidebar to come back to the main documentation site. +As such, we tend to only use package-specific documentation for developer notes and API docs. + +## Documenting unreleased features + +There are sometimes cases where it is not possible to add docs to the `docs` repository. +In particular, because the `docs` repo builds from a released version of Turing and all its dependencies, new features in unreleased versions cannot be documented here. +However, it's always better to document things as you go along rather than to wait for a release and then play catch-up! + +In such instances, we recommend first adding documentation to the relevant package's internal documentation (using Documenter.jl as usual), and later copying it over to the main `docs` repository (adjusting for the Quarto format) once the new version is released. +Note that because the `docs` repository is tied to a specific version of Turing.jl, if you have updated the documentation for a new dependency of Turing (e.g. DynamicPPL or Bijectors), you also need to ensure that there is a version of Turing.jl that is compatible with that new version. + +# How to contribute to the docs repo + +## Local development + +The `TuringLang/docs` repository uses Quarto. +You can add a new page by creating a new `.qmd` file and including its filepath in the top-level `_quarto.yml` file, which defines the structure of the website. +Generally, we prefer adding individual `index.qmd` files in new folders, as this leads to cleaner URLs. + +When you create a new page, you can test it locally by running `quarto render /path/to/mynewpage/index.qmd`, and then launching a HTTP server from the folder containing the rendered HTML file (for example, using `cd _site/path/to/mynewpage && python -m http.server`). + +Note that if you use `quarto preview`, this may take a very long time since Quarto will attempt to render the entire site! +You can see the [repository README](https://github.com/TuringLang/docs) for some information on how to get around this using the `_freeze` folder. + +## The docs environment + +The `docs` repository is built from a single Manifest file, which contains a pinned version of Turing.jl. +All notebooks are run with the same environment, which ensures consistency across the documentation site. + +In general, you should **not** add new packages to this environment which **depend** on Turing (i.e., reverse dependencies of Turing), or packages that have Turing extensions. +The reason for this is because such packages will have compatibility bounds on Turing. +Thus, we will be unable to update the docs to use the newest Turing version, until and unless those packages also update their compatibility bounds. + +Whenever a new version of Turing.jl is released, the Manifest file should ideally be updated (with a single `] up` in the Julia REPL), and the new docs published. +This process is not yet automated, though, so sometimes the version of Turing may fall behind the latest release. +Usually for minor versions we make sure to update the docs as soon as practicable, but less so for patch versions. + +## GitHub CI + +Each PR to the `docs` repository will trigger two GitHub Actions workflows: + +1. The workflow that builds the documentation. If this workflow fails, it's usually due to an error in the code, or some environment resolution issues. + + :::{.callout-tip} + If you specifically want to demonstrate the *presence* of an error, you can add `#| error: true` to the top of the code block in question. + ::: + +2. The workflow that checks that the version of Turing is the newest possible version. + If this workflow fails, it's because the Manifest file contains an older version of Turing. + +Note that the build-docs workflow utilises a lot of caching in order to speed up the build process (a full docs build can take 1.5 hours). +However, this caching is dependent on the Manifest file not changing. +Therefore, be aware that if you update the Manifest file, the next workflow run will require a full build! + +**If you are writing new docs that do not rely on a newer version of any dependency, it is often better to avoid updating the Manifest file, and instead just add the new docs.** +In this case, it's fine to let the check-version CI workflow fail. +You can add a Manifest update in a separate PR. diff --git a/contributing/pull-requests/index.qmd b/contributing/pull-requests/index.qmd new file mode 100644 index 000000000..136d3e478 --- /dev/null +++ b/contributing/pull-requests/index.qmd @@ -0,0 +1,80 @@ +--- +title: Pull Requests, Versions, and Releases +--- + +Don't worry about getting everything right on your first PR — we're happy to help you through the process. +Even an imperfect or half-finished PR is welcome; it's often easier to discuss changes with code in front of us. + +Once you open a PR, someone from the dev team will review your code (if they don't, ping `@TuringLang/maintainers` in a comment to get their attention). +If all looks good, we'll merge it. If not, we'll help you fix it and then merge it. + +# Which branch should I target? + +All TuringLang repositories follow [semantic versioning](https://semver.org/); however, the way we manage this differs between repositories. + +**Turing.jl and DynamicPPL.jl** retain two long-lived branches: `main` and `breaking`. + +When choosing a target branch for your PR, consider whether your change is breaking: + +- **`main`** is for non-breaking changes: bug fixes, new features that don't change existing behaviour, documentation, etc. +- **`breaking`** is for changes that lead to incompatibilities with previous versions' public API. + Because we don't like introducing breaking changes too frequently, we tend to aggregate multiple breaking changes into a single release. + This is why we have a separate `breaking` branch: it allows us to merge breaking changes as they come in without having to wait for a release. + +If you're unsure about whether your change is breaking, just let us know in the PR: we can help you figure it out. + +**Other repositories** don't have separate `main` and `breaking` branches. +In this case, if you have a breaking change, just target `main` and make sure to increment the appropriate version in the `Project.toml` file (see below). + +# Version numbers + +For packages which have a version number of `0.x.y`: + +- If the change you're making is non-breaking, you should increment the patch version (the last number) in the `Project.toml` file. + For example, 0.3.4 would go to 0.3.5. + +- If it's a breaking change, you should increment the minor version (the middle number) and reset the patch version to zero. + For example, 0.3.4 would go to 0.4.0. + +For packages which have a version number of `1.x.y` or higher: + +- If you are only providing a bug fix, and not introducing any new features, you can increment the patch version (the last number) in the `Project.toml` file. + For example, 1.2.3 would go to 1.2.4. + +- If you are introducing new features but not breaking any existing functionality, you should increment the minor version (the middle number) and reset the patch version to zero. + For example, 1.2.3 would go to 1.3.0. + +- If you are introducing breaking changes, you should increment the major version (the first number) and reset the minor and patch versions to zero. + For example, 1.2.3 would go to 2.0.0. + +# Changelogs + +When you make a PR, please add an entry to `HISTORY.md` describing the change. +You can see existing entries for examples of the style. + +If you are working on a repo that does not already have a `HISTORY.md` file, please consider creating one at the root of the repository! +A changelog that's started late is still better than no changelog at all. + +# What happens after I open a PR? + +## Code review + +A maintainer will review your code. +This is a collaborative process: don't worry if you get comments or change requests, that's normal and expected. + +## CI checks + +We run the test suite in GitHub Actions for several Julia versions. +Generally, all tests and code formatting checks should pass before merging. + +If the formatting check fails, please follow [the instructions on the Code Formatting page]({{< meta contributing-code-formatting >}}) to fix it. + +Some CI checks are allowed to fail: + +- **Julia prereleases:** These inform us of upcoming issues but don't block merging. + +- **Code coverage:** It's often helpful to inspect these, but we don't enforce specific coverage numbers. + +- **Upstream bugs:** Occasionally CI fails due to issues in dependencies or base Julia. + A good indicator is if the same test fails on the base branch too. + Do ping a maintainer if you're unsure about whether a CI failure is expected. diff --git a/contributing/start-contributing/index.qmd b/contributing/start-contributing/index.qmd new file mode 100644 index 000000000..d10bcc224 --- /dev/null +++ b/contributing/start-contributing/index.qmd @@ -0,0 +1,78 @@ +--- +title: Start Contributing +aliases: + - ../../developers/contributing/index.html + - ../../tutorials/docs-01-contributing-guide/index.html +--- + +Turing is an open-source project [hosted on GitHub](https://github.com/TuringLang), and we'd love your help! +Contributions of all kinds are welcome, whether that's fixing a bug, writing a tutorial, improving the docs, or just reporting an issue you've run into. + +If you're not sure where to begin, feel free to ask on any issue, or come say hello in the `#turing` channel on the [Julia Slack](https://julialang.org/slack/) or [Discourse](https://discourse.julialang.org/c/domain/probprog/48). + +# What kinds of contributions are we looking for? + +- **Bug reports and edge cases:** If you run into something that doesn't work, please [open an issue](https://github.com/TuringLang/Turing.jl/issues)! If you aren't sure which repository to post on, don't worry: just post it on the main Turing.jl repo and we can triage it. + + We're especially keen on finding cases where automatic differentiation fails. + If you find a model that doesn't work with AD, please report it, and we can either help to report it upstream, and/or add it to [the ADTests website](https://turinglang.org/ADTests/). + +- **Tutorials and example models:** If you have an interesting model that you think others could learn from, we'd love to hear about it! + You don't have to write a full docs page immediately; just open an issue and we'd be very happy to chat about it. + +- **Documentation improvements:** + Fixing typos, improving explanations, or even just suggestions for what new content to add are all very welcome. + +- **Code contributions:** + Check the issue trackers for open issues, especially on [Turing.jl](https://github.com/TuringLang/Turing.jl/issues) and [DynamicPPL.jl](https://github.com/TuringLang/DynamicPPL.jl/issues)! + +However, please don't let these categories restrict you: please do feel free to open pull requests or issues for anything you think would be a useful contribution! + +# Overview of the TuringLang ecosystem + +The Turing ecosystem really comprises [a number of Julia packages](https://turinglang.org/library). +The most important ones to know about are: + +- [**Turing.jl**](https://github.com/TuringLang/Turing.jl) is the top-level package that users interact with. + It uses the functionality from the other packages to provide a user-friendly interface for probabilistic programming. + Turing defines some of its own MCMC inference algorithms, but many of them are implemented by wrapping other packages (e.g. AdvancedHMC.jl). + +- [**DynamicPPL.jl**](https://github.com/TuringLang/DynamicPPL.jl) is the 'heart' of Turing: it defines the modelling language itself and core operations on models. + Currently, most active development work happens on DynamicPPL. + +- [**AbstractMCMC.jl**](https://github.com/TuringLang/AbstractMCMC.jl) is a lightweight package that defines an interface for samplers. + If you're implementing a new sampler, you should follow the API defined here. + +- [**Bijectors.jl**](https://github.com/TuringLang/Bijectors.jl), and specifically the `Bijectors.VectorBijectors` module, defines transformations between constrained and unconstrained parameter spaces. + +If you're looking to contribute documentation, do also check out our guide to [documentation contributions]({{< meta contributing-documentation >}}), as that describes how Turing's docs are structured. + +# New to Julia / open-source development? + +If you are new to open-source, GitHub has a [good introduction to the workflow](https://docs.github.com/en/get-started/using-github/github-flow), and Julia's own [contribution guide](https://github.com/JuliaLang/julia/blob/master/CONTRIBUTING.md) is also helpful. + +We won't cover all the details here as there are already a ton of good resources out there, but in short, you want to first [fork](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/fork-a-repo) the repository you want to contribute to. +This will create a new repository under your own GitHub account: for example `https://github.com//Turing.jl`. +You can then clone this repository to your local machine, make and commit your changes, and then push them back to your own fork on GitHub. + +When developing Julia code, it is often very useful to work in an environment where you can add "development" versions of packages, which point to a local copy of the source code. +A common workflow for Turing development is to clone all the requisite repositories (e.g. Turing.jl, DynamicPPL.jl, ...) into a single directory, and use that enclosing directory as the location for a shared environment where you can add development versions of all the packages at once. + +For example, let's say you have cloned the Turing.jl and DynamicPPL.jl repositories to `~/turing/Turing.jl` and `~/turing/DynamicPPL.jl` respectively. +Then, you can navigate to the `~/turing` directory, and run: + +```bash +julia --project=. +``` + +This will start Julia with the current directory as the active environment. +Then, you can run: + +```julia +] dev ./Turing.jl +] dev ./DynamicPPL.jl +``` + +That way, each time you restart your Julia session, you will pick up the latest changes from your local copy of the source code for both Turing.jl and DynamicPPL.jl. + +You probably want to also use [Revise.jl](https://timholy.github.io/Revise.jl/stable/) in conjunction with this, which allows you to skip the step of restarting Julia: simply edit code and the changes will be picked up automatically. diff --git a/contributing/tests/index.qmd b/contributing/tests/index.qmd new file mode 100644 index 000000000..b1a38374c --- /dev/null +++ b/contributing/tests/index.qmd @@ -0,0 +1,67 @@ +--- +title: Tests +--- + +# Running all tests + +For any Julia repository, you can run the whole suite by running `julia --project=.` from the root of the Turing repository, and then running + +```julia +]test +``` + +or equivalently + +```julia +import Pkg; Pkg.test() +``` + +# Running a subset of tests + +However, it is not always desirable to run the entire test suite: Turing.jl's test suite takes around an hour. +It would be far better to run only a subset of tests when working on a specific feature. + +The Julia community has come up with *many* different ways of running subsets of tests. +Perhaps unsurprisingly, the story of testing on TuringLang repositories is slightly complicated: different repositories have the test suites set up differently. + +**In general**, we would like to move towards a world where all repositories have test files that can be run individually using [TestPicker.jl](https://github.com/theogf/TestPicker.jl). +We have found that this is one of the most convenient ways to run a subset of tests. +In order for a test file to be compatible with TestPicker, it must be self-contained (and ideally, a module). +In particular, it should not depend on functions that were `include`d in a different file. +For example, if `test/runtests.jl` includes `test/utils.jl`, and `test/myfeature.jl` relies on something inside `test/utils.jl`, then `test/myfeature.jl` cannot be run on its own. + +Any help in refactoring test suites in this way is very welcome! + +## Turing.jl + +For the main Turing.jl repository, we can't use TestPicker.jl (yet). +You can, however, run specific test files using the `test_args` keyword argument of `Pkg.test()`. + +```julia +import Pkg; Pkg.test("Turing"; test_args=["optim", "hmc", "--skip", "ext"]) +``` + +The above command would run all files with "optim" or "hmc" in their path, such as `test/optimisation/Optimisation.jl`, but not files with "ext" in their path. +Alternatively, you can set these arguments as command line arguments when you run Julia: + +```julia +julia --project=. -e 'import Pkg; Pkg.test(; test_args=ARGS)' -- optim hmc --skip ext +``` + +(or equivalently, set the global `ARGS` variable, and call `include("test/runtests.jl")`.) + +## DynamicPPL.jl + +DynamicPPL has been completely set up to work with TestPicker. +Consequently, you can run any test file on its own by: + +1. Installing TestPicker in your global environment; +2. From the Julia REPL, pressing `!` to enter the selection mode, typing in a (partial) filename, and running it when prompted. + +If you are modifying another package to be compatible with TestPicker, you can follow the style of the test files in DynamicPPL as a guide. + +## Other repositories + +Other repositories in the Turing ecosystem are in various stages of being set up to work with TestPicker; you will have to check this by yourself. + +In a pinch, to run only a subset of files, you can comment out the `include` statements in `test/runtests.jl` that correspond to files you don't want to run, and then run the whole test suite as normal. diff --git a/developers/contributing/index.qmd b/developers/contributing/index.qmd deleted file mode 100755 index d71479821..000000000 --- a/developers/contributing/index.qmd +++ /dev/null @@ -1,216 +0,0 @@ ---- -title: Contributing -aliases: - - ../../tutorials/docs-01-contributing-guide/index.html ---- - -Turing is an open-source project and is [hosted on GitHub](https://github.com/TuringLang). -We welcome contributions from the community in all forms, large or small: bug reports, feature implementations, code contributions, or improvements to documentation or infrastructure are all extremely valuable. -We would also very much appreciate examples of models written using Turing. - -### How to get involved - -Our outstanding issues are tabulated on our [issue tracker](https://github.com/TuringLang/Turing.jl/issues). -Closing one of these may involve implementing new features, fixing bugs, or writing example models. - -You can also join the `#turing` channel on the [Julia Slack](https://julialang.org/slack/) and say hello! - -If you are new to open source software, please see [GitHub's introduction](https://guides.github.com/introduction/flow/) or [Julia's contribution guide](https://github.com/JuliaLang/julia/blob/master/CONTRIBUTING.md) on using version control for collaboration. - -### Documentation - -#### Where is Turing's documentation? - -Each of the packages in the Turing ecosystem (see [Libraries](/library)) has its own documentation, which is typically found in the `docs` folder of the corresponding package. -For example, the source code for DynamicPPL's documentation can be found in [its repository](https://github.com/TuringLang/DynamicPPL.jl). - -On top of the library-specific documentation, we also have a general documentation repository, which is what builds the website you are currently reading! -Anything that appears in `turinglang.org/docs` is built from the [`docs` repository](https://github.com/TuringLang/docs). - -Other sections of the website (anything that isn't a package, or a tutorial) – for example, the list of libraries – is built from the [`turinglang.github.io` repository](https://github.com/TuringLang/turinglang.github.io). - -In general, we prefer documentation to be written on the `TuringLang/docs` repository. -This is because it is more easily discoverable for users via the search bar and sidebar. -Documentation written on the individual package repositories can be found via the main site's search bar (due to a GitHub workflow that scrapes all the packages' contents and indexes them here), but once you navigate to a package's documentation, you cannot then use the sidebar to come back to the main documentation site. - -#### Documenting unreleased features - -There are sometimes cases where it is not possible to add docs to the `TuringLang/docs` repository. -In particular, because the `TuringLang/docs` repo builds from a released version of Turing and all its dependencies, new features in unreleased versions cannot be documented here. -However, it's always better to document things as you go along rather than to wait for a release and then play catch-up! -In such instances, we recommend first adding documentation to the relevant package's `docs` folder (using Documenter.jl as usual), and later copying it over to the main `TuringLang/docs` repository (adjusting for the Quarto format) once the new version is released. -Note that because the `TuringLang/docs` repository is tied to a specific version of Turing.jl, if you have updated the documentation for a new dependency of Turing (e.g. DynamicPPL or Bijectors), you also need to ensure that there is a version of Turing.jl that is compatible with that new version. - -#### Environments - -The `TuringLang/docs` repository is built from a single Manifest file, which contains a pinned version of Turing.jl. -All notebooks are run with the same environment, which ensures consistency across the documentation site. - -In general, you should **not** add new packages to this environment which **depend** on Turing (i.e., reverse dependencies of Turing), or packages that have Turing extensions. -The reason for this is because such packages will have compatibility bounds on Turing. -Thus, we will be unable to update the docs to use the newest Turing version, until and unless those packages also update their compatibility bounds. - -### Tests - -Turing, like most software libraries, has a test suite. You can run the whole suite by running `julia --project=.` from the root of the Turing repository, and then running - -```julia -import Pkg; Pkg.test("Turing") -``` - -The test suite subdivides into files in the `test` folder, and you can run only some of them using commands like - -```julia -import Pkg; Pkg.test("Turing"; test_args=["optim", "hmc", "--skip", "ext"]) -``` - -This one would run all files with "optim" or "hmc" in their path, such as `test/optimisation/Optimisation.jl`, but not files with "ext" in their path. Alternatively, you can set these arguments as command line arguments when you run Julia - -```julia -julia --project=. -e 'import Pkg; Pkg.test(; test_args=ARGS)' -- optim hmc --skip ext -``` - -Alternatively, set the global `ARGS` variable, and call `include("test/runtests.jl")`. - -### Pull requests, versions, and releases - -We merge all code changes through pull requests on GitHub. -To make a contribution to one of the Turing packages, fork it on GitHub, start a new branch on your fork, and add commits to it. -Once you're done, open a pull request to the main repository under [TuringLang](https://github.com/TuringLang). -Someone from the dev team will review your code (if they don't, ping `@TuringLang/maintainers` in a comment to get their attention) and check that the continuous integration tests pass (with some allowed exceptions, see below). -If all looks good, we'll merge your PR with gratitude. -If not, we'll help you fix it and then merge it with gratitude. - -Everything in this section about pull requests and branches applies to the Turing.jl and DynamicPPL.jl repositories. -Most of it also applies to other repositories under the TuringLang ecosystem, though some do not bother with the `main`/`breaking` distinction or with a `HISTORY.md`. -As at August 2025 we are slowly moving towards having all repos do the full process, so a new `HISTORY.md` in a repo that doesn't yet have one is always welcome. - -#### Branches - -Like Julia packages generally, Turing.jl follows [semantic versioning](https://semver.org/). -Because of this, we have two persistently alive branches in our repository: `main` and `breaking`. -All code that gets released as a new version of Turing gets merged into `main`, and a release is made from there. -However, any breaking changes should first be merged into `breaking`. -`breaking` will then periodically be merged into `main`. - -The idea is that `breaking` always contains commits that build towards the next breaking release in the semantic versioning sense. -That is, if the changes you make might break or change the behaviour of correctly written code that uses Turing.jl, your PR should target the `breaking` branch, and your code should be merged into `breaking`. -If your changes cause no such breakage for users, your PR should target `main`. -Notably, any bug fixes should merge directly into `main`. - -This way we can frequently release new patch version from `main`, while developing breaking changes in parallel on `breaking`. -E.g. if the current version is 0.19.3, and someone fixes a bug, we can merge the fix into `main` and release it as 0.19.4. -Meanwhile, breaking changes can be developed and merged into `breaking`, which is building towards a release of 0.20.0. -Multiple breaking changes may be accumulated into `breaking`, before finally the `breaking`-to-`main` merge is done, and 0.20.0 is released. -On `breaking` the version number should then immediately be bumped to 0.21. - -We do not generally backport bug fixes, although we may consider doing so in special circumstances. - -#### Change history - -We keep a cumulative changelog in a file called `HISTORY.md` at the root of the repository. -It should have an entry for every new breaking release, explaining everything our users need to know about the changes, such as what may have broken and how to fix things to work with the new version. -Any major new features should also be described in `HISTORY.md`, as may any other changes that are useful for users to know about. -Bug fixes generally don't need an entry in `HISTORY.md`. -Any new breaking release must have an entry in `HISTORY.md`, entries for non-breaking releases are optional. - -#### Continuous integration (CI) tests - -We generally run the whole test suite of each repository in a GitHub action, typically for a few different versions of Julia, including the earliest supported version and the latest stable release. -On some repositories we also run a few other checks in CI, such as code formatting and simple benchmarks. -Generally all tests except those run on a prerelease version of Julia (e.g. a release candidate of an upcoming Julia release), and all code formatting checks, should pass before merging a PR. -Exceptions can be made if the cause of the failure is known and unrelated to the PR. -CI checks other than tests and formatting serve various purposes, and some of them can be allowed to fail. -Some examples are - - - Anything running on a prerelease of Julia. These inform us of trouble ahead when that prerelease becomes an actual release, but don't require fixing for a PR to be merged. - - Any code coverage checks. Code coverage numbers can be helpful in catching missing tests or cases where the tests don't test what they are intended to. However, we do not insist on any particular coverage figures, since they are not a very good metric of a test suite's extensiveness. - - The benchmarks on DynamicPPL repo. These should be investigated to understand why they fail. If the reason is a bug in the PR, an actual test should be added to the test suite to catch it. However, sometimes they fail for unrelated reasons. - - Occasionally CI failures are caused by bugs that require upstream fixes (such as for AD backends, or base Julia). Please ping a maintainer if you are unsure if this is the case. A good indicator for this is if the same test is failing on the base branch of your pull request. - - The CI check in the `docs` repo for whether the docs are built with the latest Turing.jl release. This test failing is a reminder that we should make a PR to update to the latest version, but does not need fixing when working on a PR that makes unrelated changes to the documentation. - -If you are ever unsure whether some CI check needs to pass, or if the reason why one is failing is mysterious or seems unrelated to the PR, ask a maintainer and they'll help you out. - -#### Please make mistakes - -Getting pull requests from outside the core developer team is one of the greatest joys of open source maintenance, and Turing's community of contributors is its greatest asset. -If you are thinking of contributing, please do open a pull request, even an imperfect or half-finished one, or an issue to discuss it first if you prefer. -You don't need to nail all of the above details on the first go, the dev team is very happy to help you figure out how to bump version numbers or whether you need to target `main` or `breaking`. - -#### For Turing.jl core developers - -If you are a core developer of TuringLang, two notes, in addition to the above, apply: - -1. You don't need to make your own fork of the package you are editing. -Just make a new branch on the main repository, usually named `your-username/change-you-are-making` (we don't strictly enforce this convention though). -You should definitely still make a branch and a PR, and never push directly to `main` or `breaking`. -2. You can make a release of the package after your work is merged into `main`. -This is done by leaving a comment on the latest commit on `main`, saying - -``` -@JuliaRegistrator register - -Release notes: -[YOUR RELEASE NOTES HERE] -``` - -If you are making a breaking release, your release notes must also contain the string `Breaking changes` somewhere in them (this is mandated by the `@JuliaRegistrator` bot, described below). - -The `@JuliaRegistrator` bot will handle creating a pull request into the Julia central package repository and tagging a new release in the repository. -The release notes should be a copy-paste of the notes written in `HISTORY.md` if such an entry exists, or otherwise (for a patch release) a short summary of changes. - -Even core devs should always merge all their code through pull requests into `main` or `breaking`. -All code should generally be reviewed by another core developer and pass continuous integration (CI) checks. -Exceptions can be made in some cases though, such as ignoring failing CI checks where the cause is known and not due to the current pull request, or skipping code review when the pull request author is an experienced developer of the package and the changes are trivial. - -### Code Formatting - -Turing uses [JuliaFormatter.jl](https://github.com/domluna/JuliaFormatter.jl) to ensure consistent code style across the codebase. -**All code must be formatted before submitting a pull request**, and ideally with every commit. - -#### Installing JuliaFormatter - -We use version 1 of JuliaFormatter. -Install it in your **global Julia environment** (not the project environment, as adding it to the `Project.toml` would make it an invalid dependency of the project): - -```julia -julia -e 'using Pkg; Pkg.add(name="JuliaFormatter", version="1"); Pkg.pin("JuliaFormatter")' -``` - -#### Formatting Code - -To format all Julia files in the current directory and subdirectories: - -```julia -julia -e 'using JuliaFormatter; format(".")' -``` - -Run this command from the root of the repository before committing your changes. -This ensures your code follows the project's formatting standards and maintains consistency across the codebase. - -### Style Guide - -Turing has a style guide, described below. -Reviewing it before making a pull request is not strictly necessary, but you may be asked to change portions of your code to conform with the style guide before it is merged. - -Most Turing code follows [Blue: a Style Guide for Julia](https://github.com/JuliaDiff/BlueStyle). -These conventions were created from a variety of sources including Python's [PEP8](http://legacy.python.org/dev/peps/pep-0008/), Julia's [Notes for Contributors](https://github.com/JuliaLang/julia/blob/master/CONTRIBUTING.md), and Julia's [Style Guide](https://docs.julialang.org/en/v1/manual/style-guide/). - -#### Synopsis - - - Use 4 spaces per indentation level, no tabs. - - Try to adhere to a 92 character line length limit. - - Use upper camel case convention for [modules](https://docs.julialang.org/en/v1/manual/modules/) and [types](https://docs.julialang.org/en/v1/manual/types/). - - Use lower case with underscores for method names (note: Julia code likes to use lower case without underscores). - - Comments are good, try to explain the intentions of the code. - - Use whitespace to make the code more readable. - - No whitespace at the end of a line (trailing whitespace). - - Avoid padding brackets with spaces. ex. `Int64(value)` preferred over `Int64( value )`. - -#### A Word on Consistency - -When adhering to the Blue style, it's important to realise that these are guidelines, not rules. This is [stated best in the PEP8](http://legacy.python.org/dev/peps/pep-0008/#a-foolish-consistency-is-the-hobgoblin-of-little-minds): - -> A style guide is about consistency. Consistency with this style guide is important. Consistency within a project is more important. Consistency within one module or function is most important. - -> But most importantly: know when to be inconsistent – sometimes the style guide just doesn't apply. When in doubt, use your best judgment. Look at other examples and decide what looks best. And don't hesitate to ask!