Merge pull request #4 from SciML/interface

First pass of the interface code

Author: ChrisRackauckas

.github/workflows/CI.yml

@@ -20,7 +20,6 @@ jobs:
           - Core
         version:
           - '1'
-          - '1.6'
     steps:
       - uses: actions/checkout@v4
       - uses: julia-actions/setup-julia@v1

.github/workflows/Downstream.yml

@@ -13,7 +13,7 @@ jobs:
       GROUP: ${{ matrix.package.group }}
     strategy:
       matrix:
-        julia-version: [1,1.6]
+        julia-version: [1]
         os: [ubuntu-latest]
         package:
           - {user: SciML, repo: SciMLBase.jl, group: Core}

Project.toml

@@ -1,12 +1,12 @@
 name = "SciMLStructures"
 uuid = "53ae85a6-f571-4167-b2af-e1d143709226"
 authors = ["SciML"]
-version = "0.1.0"
+version = "1.0.0"
 
 [deps]
 
 [compat]
-julia = "1.6"
+julia = "1.10"
 
 [extras]
 SafeTestsets = "1bc83da4-3b8d-516f-aca4-4fe02f6d838f"

README.md

@@ -31,7 +31,7 @@ are required to opt-into the interface.
 canonicalize(::AbstractPortion, p::T1) -> values::T2, repack, aliases::Bool
 repack(new_values::T2) -> p::T1 # with values replaced with new_values
 replace(::AbstractPortion, p::T1, new_values) -> p::T1
-replace!(p::T1)::Nothing # Requires mutable
+replace!(::AbstractPortion, p::T1)::Nothing # Requires mutable
 ```
 
 ### Portion Defintions

docs/Project.toml

@@ -1,7 +1,6 @@
 [deps]
-MultiScaleArrays = "f9640e96-87f6-5992-9c3b-0743c6a49ffa"
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
+SciMLStructures = "53ae85a6-f571-4167-b2af-e1d143709226"
 
 [compat]
-Documenter = "0.27"        
-MultiScaleArrays = "1.10"
+Documenter = "1"

docs/make.jl

@@ -1,29 +1,24 @@
-using Documenter, MultiScaleArrays
+using Documenter, SciMLStructures
 
 cp("./docs/Manifest.toml", "./docs/src/assets/Manifest.toml", force = true)
 cp("./docs/Project.toml", "./docs/src/assets/Project.toml", force = true)
 
 pages = [
     "Home" => "index.md",
+    "interface.md",
     "api.md",
 ]
 
-makedocs(sitename = "FunctionProperties.jl",
-         authors = "Chris Rackauckas",
-         modules = [FunctionProperties],
-         clean = true, doctest = false, linkcheck = true,
-         strict = [
-             :doctest,
-             :linkcheck,
-             :parse_error,
-             :example_block,
-             # Other available options are
-             # :autodocs_block, :cross_references, :docs_block, :eval_block, :example_block, :footnote, :meta_block, :missing_docs, :setup_block
-         ],
-         format = Documenter.HTML(analytics = "UA-90474609-3",
-                                  assets = ["assets/favicon.ico"],
-                                  canonical = "https://docs.sciml.ai/FunctionProperties/stable/"),
-         pages = pages)
+ENV["GKSwstype"] = "100"
 
-deploydocs(repo = "github.com/SciML/MultiScaleArrays.jl.git";
-           push_preview = true)
+makedocs(modules = [SciMLStructures],
+    sitename = "SciMLStructures.jl",
+    clean = true,
+    doctest = false,
+    linkcheck = true,
+    warnonly = [:missing_docs, :cross_references, :linkcheck],
+    format = Documenter.HTML(assets = ["assets/favicon.ico"],
+        canonical = "https://docs.sciml.ai/SciMLStructures/stable/"),
+    pages = pages)
+
+deploydocs(repo = "github.com/SciML/SciMLStructures.jl"; push_preview = true)

docs/src/api.md

@@ -1,5 +1,5 @@
 # API
 
-```@docs
-hasbranching
-```
+```@autodocs
+Modules = [SciMLStructures]
+```

docs/src/index.md

@@ -1,39 +1,18 @@
-# FunctionProperties.jl: Compiler-Based Proofs of Function Properties
+# SciMLStructures.jl: Compiler-Based Proofs of Function Properties
 
-FunctionProperties.jl is a package which contains utilities for testing the
-properties of Julia functions. For example, do you need to know if `f` has
-internal branches (if statements) in order to know if a given AD optimization
-or symbolic pass is valid? This package's functions allows you to perform
-such analyses on functions from a user's code by doing a compiler-based
-code inspection.
+SciMLStructures.jl defines a generic interface for interacting with solvers, estimation tooling, and more within
+the SciML ecosystem and the greater Julia universe. SciMLStructures.jl defines a structured enforcable interface
+which allows for solvers to be able to handle custom user types in an efficient and generalized way.
 
 ## Installation
 
-To install FunctionProperties.jl, use the Julia package manager:
+To install SciMLStructures.jl, use the Julia package manager:
 
 ```julia
 using Pkg
-Pkg.add("FunctionProperties")
+Pkg.add("SciMLStructures")
 ```
 
-## Example
-
-```julia
-@test hasbranching(1, 2) do x, y
-    (x < 0 ? -x : x) + exp(y)
-end # true
-
-@test hasbranching(1, 2) do x, y
-    ifelse(x < 0, -x, x) + exp(y)
-end # false
-```
-
-## This package uses Cassette internally?
-
-Yes, because this is how it's currently known how to be done. If you have an alternative
-implementation which uses the undocumented compiler plugins interface, we would happily
-accept the PR!
-
 ## Contributing
 
   - Please refer to the
@@ -42,7 +21,7 @@ accept the PR!
 
   - See the [SciML Style Guide](https://github.com/SciML/SciMLStyle) for common coding practices and other style decisions.
   - There are a few community forums:
-    
+
       + The #diffeq-bridged and #sciml-bridged channels in the
         [Julia Slack](https://julialang.org/slack/)
       + The #diffeq-bridged and #sciml-bridged channels in the
@@ -91,32 +70,19 @@ Pkg.status(; mode = PKGMODE_MANIFEST) # hide
 </details>
 ```
 
-```@raw html
-You can also download the 
-<a href="
-```
-
 ```@eval
 using TOML
+using Markdown
 version = TOML.parse(read("../../Project.toml", String))["version"]
 name = TOML.parse(read("../../Project.toml", String))["name"]
-link = "https://github.com/SciML/" * name * ".jl/tree/gh-pages/v" * version *
-       "/assets/Manifest.toml"
-```
-
-```@raw html
-">manifest</a> file and the
-<a href="
-```
-
-```@eval
-using TOML
-version = TOML.parse(read("../../Project.toml", String))["version"]
-name = TOML.parse(read("../../Project.toml", String))["name"]
-link = "https://github.com/SciML/" * name * ".jl/tree/gh-pages/v" * version *
-       "/assets/Project.toml"
-```
-
-```@raw html
-">project</a> file.
+link_manifest = "https://github.com/SciML/" * name * ".jl/tree/gh-pages/v" * version *
+                "/assets/Manifest.toml"
+link_project = "https://github.com/SciML/" * name * ".jl/tree/gh-pages/v" * version *
+               "/assets/Project.toml"
+Markdown.parse("""You can also download the
+[manifest]($link_manifest)
+file and the
+[project]($link_project)
+file.
+""")
 ```

docs/src/interface.md

@@ -0,0 +1,47 @@
+# The SciMLStructure Interface
+
+## Core Interface Definitions
+
+### `isscimlstructure` Definition
+
+```julia
+isscimlstructure(p)::Bool
+ismutablescimlstructure(p)::Bool
+```
+
+Returns whether the object satisfies the SciMLStructure interface. Defaults to `false` and types
+are required to opt-into the interface.
+
+### `canonicalize` Definition
+
+```julia
+canonicalize(::AbstractPortion, p::T1) -> values::T2, repack, aliases::Bool
+repack(new_values::T2) -> p::T1 # with values replaced with new_values
+replace(::AbstractPortion, p::T1, new_values) -> p::T1
+replace!(::AbstractPortion, p::T1)::Nothing # Requires mutable
+```
+
+### Portion Defintions
+
+The core function of the interface is the `canonicalize` function. `canonicalize` allows the user to define
+to the solver how to represent the given "portion" in a standard `AbstractVector` type which allows for
+interfacing with standard tools like linear algebra in an efficient manner. The type of portions which
+are defined are:
+
+* Tunable: the tunable values/parameters, i.e. the values of the structure which are supposed to be considered
+  non-constant when used in the context of an inverse problem solve. For example, this is the set of
+  parameters to be optimized during a parameter estimation of an ODE.
+    * Tunable parameters are expected to return an `AbstractVector` of unitless values.
+* Constants: the values which are to be considered constant by the solver, i.e. values which are not estimated
+  in an inverse problem and which are unchanged in any operation by the user as part of the solver's usage.
+* Caches: the stored cache values of the struct, i.e. the values of the structure which are used as intermediates
+  within other computations in order to avoid extra allocations.
+* Discrete: the discrete portions of the state captured inside of the structure. For example, discrete values
+  stored outside of the `u` in the parameters to be modified in the callbacks of an ODE.
+
+## Definitions for Base Objects
+
+* `Vector`: returns an aliased version of itself as `Tunable`, and an empty vector matching type for `Constants`,
+  `Caches`, and `Discrete`.
+* `Array`: returns the `vec(p)` aliased version of itself as `Tunable`, and an empty vector matching type for `Constants`,
+  `Caches`, and `Discrete`.

src/SciMLStructures.jl

@@ -1,9 +1,9 @@
 module SciMLStructures
 
-function isscimlstructure end
+include("interface.jl")
+include("array.jl")
 
-function canonicalize end
+# public isscimlstructure, ismutablescimlstructure, hasportion, canonicalize,
+#        replace, replace!, Tunable, Constants, Caches, Discrete
 
-
-
-end
+end