Merge pull request #785 from SciML/myb/docs

Document getters

Author: ChrisRackauckas

docs/src/systems/AbstractSystem.md

@@ -17,10 +17,33 @@ total set, which includes that of all systems held inside.
 
 The values which are common to all `AbstractSystem`s are:
 
-- `sys.eqs` or `equations(sys)`: The equations that define the system.
-- `sys.states` or `states(sys)`: The set of states in the system.
-- `sys.parameters` or `parameters(sys)`: The parameters of the system.
-- `sys.systems`: The subsystems of the system.
+- `equations(sys)`: All equations that define the system and its subsystems.
+- `states(sys)`: All the states in the system and its subsystems.
+- `parameters(sys)`: All parameters of the system and its subsystems.
+- `nameof(sys)`: The name of the current-level system.
+- `get_equations(sys)`: Equations that define the current-level system.
+- `get_states(sys)`: States that are in the current-level system.
+- `get_ps(sys)`: Parameters that are in the current-level system.
+- `get_systems(sys)`: Subsystems of the current-level system.
+
+Optionally, a system could have:
+
+- `observed(sys)`: All observed equations of the system and its subsystems.
+- `get_observed(sys)`: Observed equations of the current-level system.
+- `get_default_u0(sys)`: A `Dict` that maps states into their default initial
+  condition.
+- `get_default_p(sys)`: A `Dict` that maps parameters into their default value.
+- `independent_variable(sys)`: The independent variable of a system.
+- `get_noiseeqs(sys)`: Noise equations of the current-level system.
+
+Note that there's `get_iv(sys)`, but it is not advised to use, since it errors
+when the system has no field `iv`. `independent_variable(sys)` returns `nothing`
+for `NonlinearSystem`s.
+
+A system could also have caches:
+
+- `get_jac(sys)`: The Jacobian of a system.
+- `get_tgrad(sys)`: The gradient with respect to time of a system.
 
 ## Transformations
 

src/systems/abstractsystem.jl

@@ -127,14 +127,29 @@ function getname(t)
     end
 end
 
-independent_variable(sys::AbstractSystem) = getfield(sys, :iv)
+independent_variable(sys::AbstractSystem) = isdefined(sys, :iv) ? getfield(sys, :iv) : nothing
 
 function structure(sys::AbstractSystem)
     s = get_structure(sys)
     s isa SystemStructure || throw(ArgumentError("SystemStructure is not yet initialized, please run `sys = initialize_system_structure(sys)` or `sys = alias_elimination(sys)`."))
     return s
 end
-for prop in [:eqs, :iv, :states, :ps, :default_p, :default_u0, :observed, :tgrad, :jac, :Wfact, :Wfact_t, :systems, :structure]
+for prop in [
+             :eqs
+             :noiseeqs
+             :iv
+             :states
+             :ps
+             :default_p
+             :default_u0
+             :observed
+             :tgrad
+             :jac
+             :Wfact
+             :Wfact_t
+             :systems
+             :structure
+            ]
     fname1 = Symbol(:get_, prop)
     fname2 = Symbol(:has_, prop)
     @eval begin

src/systems/nonlinear/nonlinearsystem.jl

@@ -63,8 +63,6 @@ function NonlinearSystem(eqs, states, ps;
     NonlinearSystem(eqs, value.(states), value.(ps), observed, name, systems, default_u0, default_p, nothing)
 end
 
-independent_variable(::NonlinearSystem) = nothing
-
 function calculate_jacobian(sys::NonlinearSystem;sparse=false,simplify=false)
     rhs = [eq.rhs for eq ∈ equations(sys)]
     vals = [dv for dv in states(sys)]