update docs

Author: imreddyTeja

docs/src/matrix_fields.md

@@ -153,28 +153,45 @@ and
 nt_fieldmatrix[(@name(a.bar), @name(b))]
 ```
 
-If the key `(@name(name1), @name(name2))` corresponds to an entry, then
-`(@name(foo.bar.buz), @name(biz.bop.fud))` would be the internal key for the key
-`(@name(name1.foo.bar.buz), @name(name2.biz.bop.fud))`.
+### Further Indexing Details
 
-Currently, internal values cannot be extracted in all situations. Extracting interal values
-works when indexing an object of type `eltype(entry)` with the
-second key of the internal key pair appended to the first results in a scalar.
-If the internal keys index to a non-scalar `Field`, a broadcasted object is returned.
+Let key `(@name(name1), @name(name2))` correspond to entry `sample_entry` in `FieldMatrix` `A`.
+An example of this is:
 
-When the entry is a `Field` of `Axis2Tensor`s, and both internal names are numbers that would index
-an `Axis2Tensor` with the same axis.
-
-This does not work when the internal keys index to a `Field` of sliced tensors.
-
-Extracting internal values from a `DiagonalMatrixRow` works in all cases, except when
-
-If the `FieldMatrix` represents a Jacobian, then extracting internal values works when an entry represents:
-
-- The partial derrivative of an `AxisVector`, `Tuple`, or `NamedTuple` with respect to a scalar.
-
-- The partial derrivative of a scalar with respect to an `AxisVector`.
-
-- The partial derrivative of a `Tuple`, or `NamedTuple` with respect to an `AxisVector`. In this case, the first name of the internal key must index into the tuple and result in a scalar.
+```julia
+ A = MatrixFields.FieldMatrix((@name(name1), @name(name2)) => sample_entry)
+```
 
-- The partial derrivative of an `AxisVector` with respect to an `AxisVector`. In this case, the partial derrivative of a component of the first `AxisVector` with respect to a component of the second `AxisVector` can be extracted, but not an entire `AxisVector` with respect to a component, or a component with respect to an entire `AxisVector`
+Now consider what happens indexing `A` with the key `(@name(name1.foo.bar.buz), @name(name2.biz.bop.fud))`.
+
+First, a function searches the keys of `A` for a key that `(@name(foo.bar.buz), @name(biz.bop.fud))`
+is a child of. In this example, `(@name(foo.bar.buz), @name(biz.bop.fud))` is a child of
+the key `(@name(name1), @name(name2))`, and
+`(@name(foo.bar.buz), @name(biz.bop.fud))` is referred to as the internal key.
+
+Next, the entry that `(@name(name1), @name(name2))` is paired with is recursively indexed
+by the internal key.
+
+The recursive indexing of an internal entry given some entry `entry` and internal_key `internal_name_pair`
+works as follows:
+
+1. If the  `internal_name_pair` is blank, return `entry`
+2. If each row of `entry` contains an `Axis2Tensor`, and `internal_name_pair` is of the form
+`(@name(components.data.1...), @name(components.data.2...))` (potentially with different numbers),
+then extract the specified component, and recurse on it with the remaining `internal_name_pair`. Note that if
+`entry` is not a `DiagonalMatrixRow`, then `internal_name_pair` cannot slice the tensor.
+3. If each row of `entry` is a `Geometry.AdjointAxisVector`, then recurse on the parent of the adjoint.
+4. If `internal_name_pair[1]` is not empty, and the first name in it is a field of the element type of each row of `entry`,
+extract that field from `entry`, and recurse on the it with the remaining names of `internal_name_pair[1]` and all of `internal_name_pair[2]`
+5. If `internal_name_pair[2]` is not empty, and the first name in it is a field of the element type of each row of `entry`,
+extract that field from `entry`, and recurse on the it with all of `internal_name_pair[1]` and the remaining names of `internal_name_pair[2]`
+6. At this point, if none of the previous cases are true, both `internal_name_pair[1]` and `internal_name_pair[2]` should be
+non-empty, and it is assumed that `entry` is being used to implicitally represent some tensor structure. If the first name in
+`internal_name_pair[1]` is equivalent to ``internal_name_pair[2]`, then both the first names are dropped, and entry is recursed onto.
+If the first names are different, both the first names are dropped, and the zero of entry is recursed onto.
+
+When the entry is a `ColumnWiseBandMatrixField`, indexing it will return a broadcasted object in
+the following situations:
+
+1. The internal key indexes to a type different than the basetype of the entry
+2. The internal key indexes to a zero-ed value

src/MatrixFields/field_name_dict.jl

@@ -183,7 +183,7 @@ function get_internal_entry(
             entry[row_index, col_index],
             (drop_first(internal_row_name), drop_first(internal_col_name)),
             key_error,
-        )
+        ) #TODO: should further indexing be allowed here
     elseif T <: Geometry.AdjointAxisVector # bypass parent for adjoint vectors
         return get_internal_entry(
             getfield(entry, :parent),
@@ -427,7 +427,7 @@ end
     get_scalar_keys(dict::FieldMatrix)
 
 Returns a `FieldMatrixKeys` object that contains the keys that result in
-a `ScalingFieldMatrixEntry{<:Number}` or a `ColumnwiseBandMatrixField` with bands of eltype `< :Number`
+a `ScalingFieldMatrixEntry{<:Number}` or a `ColumnwiseBandMatrixField` with bands of eltype `<: Number`
 when indexing `dict`.
 """
 function get_scalar_keys(dict::FieldMatrix)
@@ -446,7 +446,7 @@ end
     get_scalar_keys(T::Type)
 
 Returns a tuple of `FieldNamePair` objects that correspond to any children
-of `T` that are of type `FT`.
+of `T` that are of type `<: Number`.
 """
 function get_scalar_keys(::Type{T}) where {T}
     if T <: Number # TODO: is this tight enough of a Type? what about complex and duals and plushalfs