63 lines
24 KiB
HTML
63 lines
24 KiB
HTML
<!DOCTYPE html>
|
||
<html lang="en"><head><meta charset="UTF-8"/><meta name="viewport" content="width=device-width, initial-scale=1.0"/><title>SubArrays · The Julia Language</title><script>(function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
|
||
(i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
|
||
m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
|
||
})(window,document,'script','https://www.google-analytics.com/analytics.js','ga');
|
||
|
||
ga('create', 'UA-28835595-6', 'auto');
|
||
ga('send', 'pageview');
|
||
</script><link href="https://cdnjs.cloudflare.com/ajax/libs/normalize/4.2.0/normalize.min.css" rel="stylesheet" type="text/css"/><link href="https://fonts.googleapis.com/css?family=Lato|Roboto+Mono" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/4.6.3/css/font-awesome.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/9.12.0/styles/default.min.css" rel="stylesheet" type="text/css"/><script>documenterBaseURL=".."</script><script src="https://cdnjs.cloudflare.com/ajax/libs/require.js/2.2.0/require.min.js" data-main="../assets/documenter.js"></script><script src="../siteinfo.js"></script><script src="../../versions.js"></script><link href="../assets/documenter.css" rel="stylesheet" type="text/css"/><link href="../assets/julia-manual.css" rel="stylesheet" type="text/css"/></head><body><nav class="toc"><a href="../index.html"><img class="logo" src="../assets/logo.png" alt="The Julia Language logo"/></a><h1>The Julia Language</h1><select id="version-selector" onChange="window.location.href=this.value" style="visibility: hidden"></select><form class="search" id="search-form" action="../search.html"><input id="search-query" name="q" type="text" placeholder="Search docs"/></form><ul><li><a class="toctext" href="../index.html">Home</a></li><li><span class="toctext">Manual</span><ul><li><a class="toctext" href="../manual/introduction.html">Introduction</a></li><li><a class="toctext" href="../manual/getting-started.html">Getting Started</a></li><li><a class="toctext" href="../manual/variables.html">Variables</a></li><li><a class="toctext" href="../manual/integers-and-floating-point-numbers.html">Integers and Floating-Point Numbers</a></li><li><a class="toctext" href="../manual/mathematical-operations.html">Mathematical Operations and Elementary Functions</a></li><li><a class="toctext" href="../manual/complex-and-rational-numbers.html">Complex and Rational Numbers</a></li><li><a class="toctext" href="../manual/strings.html">Strings</a></li><li><a class="toctext" href="../manual/functions.html">Functions</a></li><li><a class="toctext" href="../manual/control-flow.html">Control Flow</a></li><li><a class="toctext" href="../manual/variables-and-scoping.html">Scope of Variables</a></li><li><a class="toctext" href="../manual/types.html">Types</a></li><li><a class="toctext" href="../manual/methods.html">Methods</a></li><li><a class="toctext" href="../manual/constructors.html">Constructors</a></li><li><a class="toctext" href="../manual/conversion-and-promotion.html">Conversion and Promotion</a></li><li><a class="toctext" href="../manual/interfaces.html">Interfaces</a></li><li><a class="toctext" href="../manual/modules.html">Modules</a></li><li><a class="toctext" href="../manual/documentation.html">Documentation</a></li><li><a class="toctext" href="../manual/metaprogramming.html">Metaprogramming</a></li><li><a class="toctext" href="../manual/arrays.html">Multi-dimensional Arrays</a></li><li><a class="toctext" href="../manual/linear-algebra.html">Linear algebra</a></li><li><a class="toctext" href="../manual/networking-and-streams.html">Networking and Streams</a></li><li><a class="toctext" href="../manual/parallel-computing.html">Parallel Computing</a></li><li><a class="toctext" href="../manual/dates.html">Date and DateTime</a></li><li><a class="toctext" href="../manual/interacting-with-julia.html">Interacting With Julia</a></li><li><a class="toctext" href="../manual/running-external-programs.html">Running External Programs</a></li><li><a class="toctext" href="../manual/calling-c-and-fortran-code.html">Calling C and Fortran Code</a></li><li><a class="toctext" href="../manual/handling-operating-system-variation.html">Handling Operating System Variation</a></li><li><a class="toctext" href="../manual/environment-variables.html">Environment Variables</a></li><li><a class="toctext" href="../manual/embedding.html">Embedding Julia</a></li><li><a class="toctext" href="../manual/packages.html">Packages</a></li><li><a class="toctext" href="../manual/profile.html">Profiling</a></li><li><a class="toctext" href="../manual/stacktraces.html">Stack Traces</a></li><li><a class="toctext" href="../manual/performance-tips.html">Performance Tips</a></li><li><a class="toctext" href="../manual/workflow-tips.html">Workflow Tips</a></li><li><a class="toctext" href="../manual/style-guide.html">Style Guide</a></li><li><a class="toctext" href="../manual/faq.html">Frequently Asked Questions</a></li><li><a class="toctext" href="../manual/noteworthy-differences.html">Noteworthy Differences from other Languages</a></li><li><a class="toctext" href="../manual/unicode-input.html">Unicode Input</a></li></ul></li><li><span class="toctext">Standard Library</span><ul><li><a class="toctext" href="../stdlib/base.html">Essentials</a></li><li><a class="toctext" href="../stdlib/collections.html">Collections and Data Structures</a></li><li><a class="toctext" href="../stdlib/math.html">Mathematics</a></li><li><a class="toctext" href="../stdlib/numbers.html">Numbers</a></li><li><a class="toctext" href="../stdlib/strings.html">Strings</a></li><li><a class="toctext" href="../stdlib/arrays.html">Arrays</a></li><li><a class="toctext" href="../stdlib/parallel.html">Tasks and Parallel Computing</a></li><li><a class="toctext" href="../stdlib/linalg.html">Linear Algebra</a></li><li><a class="toctext" href="../stdlib/constants.html">Constants</a></li><li><a class="toctext" href="../stdlib/file.html">Filesystem</a></li><li><a class="toctext" href="../stdlib/io-network.html">I/O and Network</a></li><li><a class="toctext" href="../stdlib/punctuation.html">Punctuation</a></li><li><a class="toctext" href="../stdlib/sort.html">Sorting and Related Functions</a></li><li><a class="toctext" href="../stdlib/pkg.html">Package Manager Functions</a></li><li><a class="toctext" href="../stdlib/dates.html">Dates and Time</a></li><li><a class="toctext" href="../stdlib/iterators.html">Iteration utilities</a></li><li><a class="toctext" href="../stdlib/test.html">Unit Testing</a></li><li><a class="toctext" href="../stdlib/c.html">C Interface</a></li><li><a class="toctext" href="../stdlib/libc.html">C Standard Library</a></li><li><a class="toctext" href="../stdlib/libdl.html">Dynamic Linker</a></li><li><a class="toctext" href="../stdlib/profile.html">Profiling</a></li><li><a class="toctext" href="../stdlib/stacktraces.html">StackTraces</a></li><li><a class="toctext" href="../stdlib/simd-types.html">SIMD Support</a></li></ul></li><li><span class="toctext">Developer Documentation</span><ul><li><a class="toctext" href="reflection.html">Reflection and introspection</a></li><li><span class="toctext">Documentation of Julia's Internals</span><ul><li><a class="toctext" href="init.html">Initialization of the Julia runtime</a></li><li><a class="toctext" href="ast.html">Julia ASTs</a></li><li><a class="toctext" href="types.html">More about types</a></li><li><a class="toctext" href="object.html">Memory layout of Julia Objects</a></li><li><a class="toctext" href="eval.html">Eval of Julia code</a></li><li><a class="toctext" href="callconv.html">Calling Conventions</a></li><li><a class="toctext" href="compiler.html">High-level Overview of the Native-Code Generation Process</a></li><li><a class="toctext" href="functions.html">Julia Functions</a></li><li><a class="toctext" href="cartesian.html">Base.Cartesian</a></li><li><a class="toctext" href="meta.html">Talking to the compiler (the <code>:meta</code> mechanism)</a></li><li class="current"><a class="toctext" href="subarrays.html">SubArrays</a><ul class="internal"><li><a class="toctext" href="#Indexing:-cartesian-vs.-linear-indexing-1">Indexing: cartesian vs. linear indexing</a></li><li><a class="toctext" href="#Index-replacement-1">Index replacement</a></li><li><a class="toctext" href="#SubArray-design-1">SubArray design</a></li></ul></li><li><a class="toctext" href="sysimg.html">System Image Building</a></li><li><a class="toctext" href="llvm.html">Working with LLVM</a></li><li><a class="toctext" href="stdio.html">printf() and stdio in the Julia runtime</a></li><li><a class="toctext" href="boundscheck.html">Bounds checking</a></li><li><a class="toctext" href="locks.html">Proper maintenance and care of multi-threading locks</a></li><li><a class="toctext" href="offset-arrays.html">Arrays with custom indices</a></li><li><a class="toctext" href="libgit2.html">Base.LibGit2</a></li><li><a class="toctext" href="require.html">Module loading</a></li></ul></li><li><span class="toctext">Developing/debugging Julia's C code</span><ul><li><a class="toctext" href="backtraces.html">Reporting and analyzing crashes (segfaults)</a></li><li><a class="toctext" href="debuggingtips.html">gdb debugging tips</a></li><li><a class="toctext" href="valgrind.html">Using Valgrind with Julia</a></li><li><a class="toctext" href="sanitizers.html">Sanitizer support</a></li></ul></li></ul></li></ul></nav><article id="docs"><header><nav><ul><li>Developer Documentation</li><li>Documentation of Julia's Internals</li><li><a href="subarrays.html">SubArrays</a></li></ul><a class="edit-page" href="https://github.com/JuliaLang/julia/blob/master/doc/src/devdocs/subarrays.md"><span class="fa"></span> Edit on GitHub</a></nav><hr/><div id="topbar"><span>SubArrays</span><a class="fa fa-bars" href="#"></a></div></header><h1><a class="nav-anchor" id="SubArrays-1" href="#SubArrays-1">SubArrays</a></h1><p>Julia's <code>SubArray</code> type is a container encoding a "view" of a parent <a href="../stdlib/arrays.html#Core.AbstractArray"><code>AbstractArray</code></a>. This page documents some of the design principles and implementation of <code>SubArray</code>s.</p><h2><a class="nav-anchor" id="Indexing:-cartesian-vs.-linear-indexing-1" href="#Indexing:-cartesian-vs.-linear-indexing-1">Indexing: cartesian vs. linear indexing</a></h2><p>Broadly speaking, there are two main ways to access data in an array. The first, often called cartesian indexing, uses <code>N</code> indexes for an <code>N</code> -dimensional <code>AbstractArray</code>. For example, a matrix <code>A</code> (2-dimensional) can be indexed in cartesian style as <code>A[i,j]</code>. The second indexing method, referred to as linear indexing, uses a single index even for higher-dimensional objects. For example, if <code>A = reshape(1:12, 3, 4)</code>, then the expression <code>A[5]</code> returns the value 5. Julia allows you to combine these styles of indexing: for example, a 3d array <code>A3</code> can be indexed as <code>A3[i,j]</code>, in which case <code>i</code> is interpreted as a cartesian index for the first dimension, and <code>j</code> is a linear index over dimensions 2 and 3.</p><p>For <code>Array</code>s, linear indexing appeals to the underlying storage format: an array is laid out as a contiguous block of memory, and hence the linear index is just the offset (+1) of the corresponding entry relative to the beginning of the array. However, this is not true for many other <code>AbstractArray</code> types: examples include <a href="../stdlib/arrays.html#Base.SparseArrays.SparseMatrixCSC"><code>SparseMatrixCSC</code></a>, arrays that require some kind of computation (such as interpolation), and the type under discussion here, <code>SubArray</code>. For these types, the underlying information is more naturally described in terms of cartesian indexes.</p><p>You can manually convert from a cartesian index to a linear index with <code>sub2ind</code>, and vice versa using <code>ind2sub</code>. <code>getindex</code> and <code>setindex!</code> functions for <code>AbstractArray</code> types may include similar operations.</p><p>While converting from a cartesian index to a linear index is fast (it's just multiplication and addition), converting from a linear index to a cartesian index is very slow: it relies on the <code>div</code> operation, which is one of the slowest low-level operations you can perform with a CPU. For this reason, any code that deals with <code>AbstractArray</code> types is best designed in terms of cartesian, rather than linear, indexing.</p><h2><a class="nav-anchor" id="Index-replacement-1" href="#Index-replacement-1">Index replacement</a></h2><p>Consider making 2d slices of a 3d array:</p><pre><code class="language-julia">S1 = view(A, :, 5, 2:6)
|
||
S2 = view(A, 5, :, 2:6)</code></pre><p><code>view</code> drops "singleton" dimensions (ones that are specified by an <code>Int</code>), so both <code>S1</code> and <code>S2</code> are two-dimensional <code>SubArray</code>s. Consequently, the natural way to index these is with <code>S1[i,j]</code>. To extract the value from the parent array <code>A</code>, the natural approach is to replace <code>S1[i,j]</code> with <code>A[i,5,(2:6)[j]]</code> and <code>S2[i,j]</code> with <code>A[5,i,(2:6)[j]]</code>.</p><p>The key feature of the design of SubArrays is that this index replacement can be performed without any runtime overhead.</p><h2><a class="nav-anchor" id="SubArray-design-1" href="#SubArray-design-1">SubArray design</a></h2><h3><a class="nav-anchor" id="Type-parameters-and-fields-1" href="#Type-parameters-and-fields-1">Type parameters and fields</a></h3><p>The strategy adopted is first and foremost expressed in the definition of the type:</p><pre><code class="language-julia">struct SubArray{T,N,P,I,L} <: AbstractArray{T,N}
|
||
parent::P
|
||
indexes::I
|
||
offset1::Int # for linear indexing and pointer, only valid when L==true
|
||
stride1::Int # used only for linear indexing
|
||
...
|
||
end</code></pre><p><code>SubArray</code> has 5 type parameters. The first two are the standard element type and dimensionality. The next is the type of the parent <code>AbstractArray</code>. The most heavily-used is the fourth parameter, a <code>Tuple</code> of the types of the indices for each dimension. The final one, <code>L</code>, is only provided as a convenience for dispatch; it's a boolean that represents whether the index types support fast linear indexing. More on that later.</p><p>If in our example above <code>A</code> is a <code>Array{Float64, 3}</code>, our <code>S1</code> case above would be a <code>SubArray{Int64,2,Array{Int64,3},Tuple{Colon,Int64,UnitRange{Int64}},false}</code>. Note in particular the tuple parameter, which stores the types of the indices used to create <code>S1</code>. Likewise,</p><pre><code class="language-julia-repl">julia> S1.indexes
|
||
(Colon(),5,2:6)</code></pre><p>Storing these values allows index replacement, and having the types encoded as parameters allows one to dispatch to efficient algorithms.</p><h3><a class="nav-anchor" id="Index-translation-1" href="#Index-translation-1">Index translation</a></h3><p>Performing index translation requires that you do different things for different concrete <code>SubArray</code> types. For example, for <code>S1</code>, one needs to apply the <code>i,j</code> indices to the first and third dimensions of the parent array, whereas for <code>S2</code> one needs to apply them to the second and third. The simplest approach to indexing would be to do the type-analysis at runtime:</p><pre><code class="language-julia">parentindexes = Array{Any}(0)
|
||
for thisindex in S.indexes
|
||
...
|
||
if isa(thisindex, Int)
|
||
# Don't consume one of the input indexes
|
||
push!(parentindexes, thisindex)
|
||
elseif isa(thisindex, AbstractVector)
|
||
# Consume an input index
|
||
push!(parentindexes, thisindex[inputindex[j]])
|
||
j += 1
|
||
elseif isa(thisindex, AbstractMatrix)
|
||
# Consume two input indices
|
||
push!(parentindexes, thisindex[inputindex[j], inputindex[j+1]])
|
||
j += 2
|
||
elseif ...
|
||
end
|
||
S.parent[parentindexes...]</code></pre><p>Unfortunately, this would be disastrous in terms of performance: each element access would allocate memory, and involves the running of a lot of poorly-typed code.</p><p>The better approach is to dispatch to specific methods to handle each type of stored index. That's what <code>reindex</code> does: it dispatches on the type of the first stored index and consumes the appropriate number of input indices, and then it recurses on the remaining indices. In the case of <code>S1</code>, this expands to</p><pre><code class="language-julia">Base.reindex(S1, S1.indexes, (i, j)) == (i, S1.indexes[2], S1.indexes[3][j])</code></pre><p>for any pair of indices <code>(i,j)</code> (except <code>CartesianIndex</code>s and arrays thereof, see below).</p><p>This is the core of a <code>SubArray</code>; indexing methods depend upon <code>reindex</code> to do this index translation. Sometimes, though, we can avoid the indirection and make it even faster.</p><h3><a class="nav-anchor" id="Linear-indexing-1" href="#Linear-indexing-1">Linear indexing</a></h3><p>Linear indexing can be implemented efficiently when the entire array has a single stride that separates successive elements, starting from some offset. This means that we can pre-compute these values and represent linear indexing simply as an addition and multiplication, avoiding the indirection of <code>reindex</code> and (more importantly) the slow computation of the cartesian coordinates entirely.</p><p>For <code>SubArray</code> types, the availability of efficient linear indexing is based purely on the types of the indices, and does not depend on values like the size of the parent array. You can ask whether a given set of indices supports fast linear indexing with the internal <code>Base.viewindexing</code> function:</p><pre><code class="language-julia-repl">julia> Base.viewindexing(S1.indexes)
|
||
IndexCartesian()
|
||
|
||
julia> Base.viewindexing(S2.indexes)
|
||
IndexLinear()</code></pre><p>This is computed during construction of the <code>SubArray</code> and stored in the <code>L</code> type parameter as a boolean that encodes fast linear indexing support. While not strictly necessary, it means that we can define dispatch directly on <code>SubArray{T,N,A,I,true}</code> without any intermediaries.</p><p>Since this computation doesn't depend on runtime values, it can miss some cases in which the stride happens to be uniform:</p><pre><code class="language-julia-repl">julia> A = reshape(1:4*2, 4, 2)
|
||
4×2 Base.ReshapedArray{Int64,2,UnitRange{Int64},Tuple{}}:
|
||
1 5
|
||
2 6
|
||
3 7
|
||
4 8
|
||
|
||
julia> diff(A[2:2:4,:][:])
|
||
3-element Array{Int64,1}:
|
||
2
|
||
2
|
||
2</code></pre><p>A view constructed as <code>view(A, 2:2:4, :)</code> happens to have uniform stride, and therefore linear indexing indeed could be performed efficiently. However, success in this case depends on the size of the array: if the first dimension instead were odd,</p><pre><code class="language-julia-repl">julia> A = reshape(1:5*2, 5, 2)
|
||
5×2 Base.ReshapedArray{Int64,2,UnitRange{Int64},Tuple{}}:
|
||
1 6
|
||
2 7
|
||
3 8
|
||
4 9
|
||
5 10
|
||
|
||
julia> diff(A[2:2:4,:][:])
|
||
3-element Array{Int64,1}:
|
||
2
|
||
3
|
||
2</code></pre><p>then <code>A[2:2:4,:]</code> does not have uniform stride, so we cannot guarantee efficient linear indexing. Since we have to base this decision based purely on types encoded in the parameters of the <code>SubArray</code>, <code>S = view(A, 2:2:4, :)</code> cannot implement efficient linear indexing.</p><h3><a class="nav-anchor" id="A-few-details-1" href="#A-few-details-1">A few details</a></h3><ul><li><p>Note that the <code>Base.reindex</code> function is agnostic to the types of the input indices; it simply determines how and where the stored indices should be reindexed. It not only supports integer indices, but it supports non-scalar indexing, too. This means that views of views don't need two levels of indirection; they can simply re-compute the indices into the original parent array!</p></li><li><p>Hopefully by now it's fairly clear that supporting slices means that the dimensionality, given by the parameter <code>N</code>, is not necessarily equal to the dimensionality of the parent array or the length of the <code>indexes</code> tuple. Neither do user-supplied indices necessarily line up with entries in the <code>indexes</code> tuple (e.g., the second user-supplied index might correspond to the third dimension of the parent array, and the third element in the <code>indexes</code> tuple).</p><p>What might be less obvious is that the dimensionality of the stored parent array must be equal to the number of effective indices in the <code>indexes</code> tuple. Some examples:</p><pre><code class="language-julia">A = reshape(1:35, 5, 7) # A 2d parent Array
|
||
S = view(A, 2:7) # A 1d view created by linear indexing
|
||
S = view(A, :, :, 1:1) # Appending extra indices is supported</code></pre><p>Naively, you'd think you could just set <code>S.parent = A</code> and <code>S.indexes = (:,:,1:1)</code>, but supporting this dramatically complicates the reindexing process, especially for views of views. Not only do you need to dispatch on the types of the stored indices, but you need to examine whether a given index is the final one and "merge" any remaining stored indices together. This is not an easy task, and even worse: it's slow since it implicitly depends upon linear indexing.</p><p>Fortunately, this is precisely the computation that <code>ReshapedArray</code> performs, and it does so linearly if possible. Consequently, <code>view</code> ensures that the parent array is the appropriate dimensionality for the given indices by reshaping it if needed. The inner <code>SubArray</code> constructor ensures that this invariant is satisfied.</p></li><li><p><code>CartesianIndex</code> and arrays thereof throw a nasty wrench into the <code>reindex</code> scheme. Recall that <code>reindex</code> simply dispatches on the type of the stored indices in order to determine how many passed indices should be used and where they should go. But with <code>CartesianIndex</code>, there's no longer a one-to-one correspondence between the number of passed arguments and the number of dimensions that they index into. If we return to the above example of <code>Base.reindex(S1, S1.indexes, (i, j))</code>, you can see that the expansion is incorrect for <code>i, j = CartesianIndex(), CartesianIndex(2,1)</code>. It should <em>skip</em> the <code>CartesianIndex()</code> entirely and return:</p><pre><code class="language-julia">(CartesianIndex(2,1)[1], S1.indexes[2], S1.indexes[3][CartesianIndex(2,1)[2]])</code></pre><p>Instead, though, we get:</p><pre><code class="language-julia">(CartesianIndex(), S1.indexes[2], S1.indexes[3][CartesianIndex(2,1)])</code></pre><p>Doing this correctly would require <em>combined</em> dispatch on both the stored and passed indices across all combinations of dimensionalities in an intractable manner. As such, <code>reindex</code> must never be called with <code>CartesianIndex</code> indices. Fortunately, the scalar case is easily handled by first flattening the <code>CartesianIndex</code> arguments to plain integers. Arrays of <code>CartesianIndex</code>, however, cannot be split apart into orthogonal pieces so easily. Before attempting to use <code>reindex</code>, <code>view</code> must ensure that there are no arrays of <code>CartesianIndex</code> in the argument list. If there are, it can simply "punt" by avoiding the <code>reindex</code> calculation entirely, constructing a nested <code>SubArray</code> with two levels of indirection instead.</p></li></ul><footer><hr/><a class="previous" href="meta.html"><span class="direction">Previous</span><span class="title">Talking to the compiler (the <code>:meta</code> mechanism)</span></a><a class="next" href="sysimg.html"><span class="direction">Next</span><span class="title">System Image Building</span></a></footer></article></body></html>
|