design of array constructors

[Sacha0]

Intro

This post is an attempt to consolidate/review/analyze the several ongoing, disjoint conversations on array construction. The common heart of these discussions is that the existing patchwork of array construction methods leaves something to be desired. A more coherent model that is pleasant to use, adequately general and flexible, largely consistent both within and across array types, and consists of orthogonal, composable parts would be fantastic.

Some particular design objectives / razors might include:

• Given an unfamiliar array type, you should have a reasonable sense of how to construct an instance with desired contents without manual/method/code sleuthing.

• Reading an incantation that constructs an array of unfamiliar type, you should be able to largely deduce the array's type and contents without manual/method/code sleuthing.

• The general tools for array construction should be discoverable, and writing *common operations via those general tools should be sufficiently pleasant and concise that: (1) pressure to write ad hoc convenience methods does not escalate to the point where such methods proliferate; and (2) antipatterns for array construction do not emerge to avoid (or in ignorance of) the general tools.

(*Common operations include constructing: (1) an array uniformly initialized from a value; (2) an array filled from an iterable, or from a similar object defining the array's contents such as I; (3) one array from another; and (4) an uninitialized array.)

Via a tour of the relevant issues and with the above in mind, let's explore the design space.

Tour of the issues

Let's start with...

• 16029, "Merge collect() into Vector()". The crux: Some array types have constructor methods that, given (solely) a tuple or series of integer arguments specifying shape, produce an uninitialized instance of the given shape. Due to method signature collisions, those constructor methods prevent such array types from supporting construction from certain iterables (particularly tuples and integers). Illustration with Vector: Vector(x) should be able to construct a Vector from an arbitrary HasLength iterable x (as with e.g. Vector(1:4), which intuitively yields [1, 2, 3, 4]). But this cannot work for tuples now, as e.g. Vector{Float64}((2,)) instead constructs an uninitialized Vector{Float64} of length two.

The prevailing idea for fixing the preceding issue is to: (1) deprecate uninitialized-array constructors that accept (solely) a tuple or series of integer arguments as shape, removing the method signature collision; and (2) replace those uninitialized-array constructors with something else. Two broad replacement proposals exist:

1. Introduce a new generic function, say (*modulo spelling) blah(T, shape...) for type T and tuple or series of integers shape, that returns an uninitialized Array with element type T and shape shape. This approach is an extension of the existing collection of Array convenience constructors inherited from other languages including ones, zeros, eye, rand, and randn.

(* Please note that blah is merely a short placeholder for whatever name comes out of the relevant ongoing bikeshed. The eventual name is not important here :).)

2. Introduce Array{T}(blah, shape...) constructors where blah signals that the caller does not care what the return's contents are. These constructors would be specific instances of a more general model that extends and unifies the existing constructor model. That more general model is discussed further below.

The first proposal

The first proposal leads us to...

• 11557, "Functions that return arrays with eltype as input should use container type instead?". The crux: ones, zeros, eye, rand, randn, and the proposed blah(T, shape...) all produce Arrays. How do we generalize these functions to array types broadly? Two approaches exist:

The de facto approach is introduction of ad hoc perturbations on these function names for each new array type: Devise an obscure prefix associated with your array type, and introduce *ones, *zeros, *eye, *rand, *randn, and hypothetically *blah functions with * your prefix. This approach fails all three razors above: Failing the first razor, to construct an instance of an array type that follows this approach, you have to discover that the array type takes this approach, figure out the associated prefix, and then hope the methods you find do what you expect. Failing the second razor, when you encounter the unfamiliar bones function in code, you might guess that function either carries out spooky divination rituals, or constructs a b full of ones (whatever b refers to). Along similar lines, does spones populate all entries in a sparse matrix with ones, or only some set of stored/nonzero entries (and if so which)? Failing the third razor, the very nature of this approach is proliferation of ad hoc convenience functions and is itself an antipattern. On the other hand, this approach's upside is that it sometimes involves a bit less typing (though often also not, see below). Nonetheless, this approach is fraught.

So what's the other approach? #11557 started off by discussing that other approach: ones, zeros, eye, rand, and randn typically accept a result element type as either first or second argument, for example ones(Int, (3, 3)) and rand(MersenneTwister(), Int, (3, 3)). That argument could instead be an array type, for example ones(MyArray{Int}, (3, 3)) and rand(MersenneTwister(), MyArray{Int}, (3, 3)). This approach is enormously better than the last: It could mostly pass the first and second razors above. But it nonetheless fails the third razor, and exhibits other shortcomings (mostly inherited from the existing convenience constructors). Let's look at some of those shortcomings:

• Default element type ambiguity: When element type isn't specified, for example as in eye(MyArray, (3, 3)) or ones(MyArray, (3, 3)), what should the returned array's element type be? Should that default element type be consistent across array types, or allowed to vary? At present these functions yield Float64 by default, which is a reasonable (useful) choice when running on modern CPUs. But other defaults may be more appropriate for array types associated with other hardware or applications, for example Float16 or Float32 for array types / contexts associated with GPUs. And one could also argue that Int is a more canonical type independent of context, or that Bool usually provides better promotion behavior, and so on. (This shortcoming to some degree violates the second razor.)

• ones (and, to lesser degree, eye) element type ambiguity: As #24444 highlights, whether ones(MyArray{T}, shape...) returns element type T's multiplicative identity (one(T)) or additive generator (oneunit(T)) is ambiguous. Of course one or the other can be chosen and documented. But choosing one, ones(MyArray{T}, shape...) can no longer consistently return a MyArray{T}, as for some types typeof(one(T)) does not coincide with T (e.g. one(1meter) == 1 != 1meter). And as demonstrated in #24444, with either choice some subset of users's expectations will be violated and use cases unsatisfied, creating pressure for ad hoc solutions or additional value-names. eye(MyArray{T}, shape...)'s element type should less ambiguously be one(T), which mitigates the latter issue but runs into the former. (This shortcoming to some degree violates both the first and second razors.)

• zeros element type ambiguity: Prior to #16116, whether one(T) returned a multiplicative identity or additive generator for T was ambiguous. #20268 resolved this ambiguity by introducing oneunit(T) as the additive generator for T and affirming one(T) as a multiplicative identity. zero suffers from a similar issue, though likely less important in practice: Is zero(T) the additive identity or a sort of multiplicative zero for T? To illustrate, is 3meters * zero(1meters) 0meters^2 or 0meters? Consequently, zeros suffers from an ambiguity analogous to that described above for ones.

• Handling values without an associated function: To construct a MyArray of 1s, you call ones(MyArray{Int}, (3, 3)). To construct a MyArray of 0s, you call zeros(MyArray{Int}, (3, 3)). To construct a MyArray containing the identity matrix, you call eye(MyArray{Int}, (3, 3)). Great so far. But how do you construct a MyArray of 2s, or -1s, or containing I/2? If you are used to these convenience constructors, perhaps you respectively call 2*ones(MyArray{Int}, (3, 3)), -ones(MyArray{Int}, (3, 3)), and eye(MyArray{Int}, (3, 3))/2. Or in the first two cases perhaps you call fill!(blah(MyArray{Int}, (3, 3)), [2|-1]) for mutable and fill!-supporting MyArray, limiting your code's scope. If you want to avoid generating a temporary, you probably use the fill! incantation. But these incantations are less pleasant than ones or zeros, so perhaps you give your common values names: twos(MyArray{Int}, (3, 3)). And to avoid the temporary in the eye call, perhaps you roll a halfeye(MyArray{Int}, (3, 3)) function to avoid allocating the temporary. Overall, antipatterns emerge and ad hoc functions proliferate. And as demonstrated in https://github.com/JuliaLang/julia/issues/24444#issuecomment-343261511 and discussed elsewhere, this issue bears out in practice and is widespread. (This shortcoming violates the third razor.)

• Two disjoint, incongruous, and overlapping models are necessary: To construct an array from another array, or from an iterable or similar content specifier, you have to switch from these functions to constructors. So users must be familiar with two disjoint, incongruous, and non-orthogonal models.

• Minor type argument position inconsistency: The position of these functions' type argument varies, requiring method sleuthing to figure out the correct signature. Examples: ones(MyArray{Int}, (3, 3)) versus rand(RNG, MyArray{Int}, (3, 3)).

Each of these shortcomings is perhaps acceptable considered in isolation. But considering these shortcomings simultaneously, this approach becomes a shaky foundation on which to build a significant component of the language.

In part motivated by these and other considerations, #11557 and concurrent discussion turned to...

The second proposal

... which is to introduce (modulo spelling of blah, please see above) Array{T}(blah, shape...) constructors, where blah indicates the caller does not care what the return's contents are. These constructors immediately generalize to arbitrary array types as in MyArray{T}(blah, shape_etc...), and would be a specific instance of a more general model that extends the existing constructor model:

The existing constructor model allows you to write, for example, Vector(x) for x any of 1:4, Base.OneTo(4), or [1, 2, 3, 4] (to construct the Vector{Int} [1, 2, 3, 4]), or similarly SparseVector(x) (to build the equivalent SparseVector). To the limited degree this presently works broadly, the model is MyArray[{...}](contentspec) where contentspec, for example some other array, iterable, or similar object, defines the resulting array's contents.

The more general extension of this model is MyArray[{...}](contentspec[, modifierspec...]). Roughly, contentspec defines the result's contents, while modifierspec... (if given) provides qualifications, e.g. shape.

What does this look like in practice?

For the most part you would use constructors as you do now, with few exceptions. Let's go through the common construction operations mentioned above:

1. (Constructing uninitialized arrays.) To build an uninitialized MyArray{T}, where now you write e.g. MyArray{T}(shape...), instead you would write MyArray{T}(blah, shape...). (#24400 explored this possibity for Arrays, and inevitably became a bikeshed of the spelling of blah :).)

2. (Constructing one array from another.) Constructing one array from another, as in e.g. Vector(x) or SparseVector(x) for x being [1, 2, 3, 4], would work just as before.

3. (Constructing an array filled from an iterable, or from a similar object defining the array's contents such as I.) What is possible now, for example Vector(x) for x either 1:4 or Base.One(4), would work as before. But where e.g. Array[{T,N}](tuple) now fails or produces an uninitialized array depending on T, N, and tuple, such signatures could work as for any other iterable. And additional possibilities become natural: Constructing Arrays from HasShape generators is one nice example. Another, already on master (#24372), is Matrix[{T}](I, m, n) (alternatively Matrix[{T}](I, (m, n))), which constructs a Matrix[{T}] of shape (m, n) containing the identity, and is equivalent to eye([T, ]m[, n]) with fewer ambiguities.

Great so far. Now what about perhaps the most common operation, i.e. constructing an array uniformly initialized from a value? Under the general model above, this operation should of course roughly be MyArray[{T}](it, shape...) where it is an iterable repeating the desired value. But this incantation should: (a) be fairly short and pleasant to type, lest ad hoc constructors for particular array types and values proliferate to avoid using the general model; and ideally (b) mesh naturally with convenience constructors for Arrays.

Triage came up with two broad spelling possibilities. The first spelling possibility led to...

• 24389, "constructors for Array from zeros/ones". The crux: Make ones and zeros iterable, allowing e.g. MyArray([ones|zeros], shape...). At first blush this spelling seems reasonable: It's fairly short/pleasant, satisfying (a). And it ties to the ones/zeros convenience constructors, somewhat satisfying (b) (caveat being the slightly unnatural reversed identifier ordering as in e.g. ones(T, shape...) vs MyArr{T}(ones, shape...)). But further consideration reveals that this spelling foists most shortcomings of the first design proposal (that is, the e.g. ones(Int, ...) -> ones(MyArray{Int}, ...) proposal described above) onto this second design proposal. Specifically, the "Default element type ambiguity", "ones/eye/zeros element type ambiguity", and "handling values without an associated function" shortcomings described above all apply here as well. Sad razors.

The second spelling possibility is MyArray(Rep(v), shape...) modulo spelling of Rep(v), where Rep(v) is some convenient alias for Iterators.Repeated(v) with v any desired value. (Another possible spelling of Rep(v) discussed in triage is Fill(v), which dovetails beautifully with the fill convenience constructor for the same purpose specific to Arrays. Independent of the iterator's name, this spelling is a clean generalization of fill from Arrays to arrays generally.) In practice this would look like MyArray(Rep(1), shape...) (instead of MyArray{Int}(ones, shape...)). This spelling possesses some distinct advantages:

• By nature of requiring a value, this spelling suffers from neither the "default element type ambiguity" nor the "ones/eye/zeros elementy type ambiguity" described above.

• By nature of accommodating any value, this spelling avoids the "handling values without an associated function" issue and the consequent antipatterns and ad hoc method proliferation.

• By nature of requiring and accepting a value, this spelling is frequently more compact and efficient than equivalents with the other spelling: Consider MyArray(Rep(1.0im), shape...) versus im*MyArray{Complex{Float64}}(ones, shape...), or MyArray(Rep(1f0/ℯ), shape...) versus MyArray{Float32}(ones, shape...)/ℯ.

• This spelling is a composition of well-defined, fundamental tools that, once learned, can be deployed to good effect elsewhere. In contrast, the other spelling is ad hoc and a bit of a pun.

Great. With this latter spelling, overall this second proposal appears to satisfy both the broad design objectives and three razors at the top, and avoids the shortcomings of the first proposal.

What else? Convenience constructors

Convenience constructor are an important part of this discussion and about which there is much to consider. But that topic I will leave for another post. Thanks for reading! :)

[JeffBezanson]

I would also accept renaming it to uninit. That is one long word.

[andyferris]

c.f. #undef - if we're looking for a new name for these things, it could be nice to normalize terminology.

[carstenbauer]

But uninit and #undef mean different things, right? AFAIU uninit means I don't care about the initialization whereas #undef represents not filled at all (truly empty array).

[andyferris]

#undefs can only occur as uninitialized values of Arrays (or fields of structs), which AFAICT are set to zero pointers by the compiler (zero pointers could also come from structs and arrays returned by foreign calls, I suppose). The main difference is for isbits types whose uninitialised value is whatever RAM happens to be there, since no pointer is involved. It may well be that a large enough difference exists such that two terminologies is better than one, but maybe it’s worth thinking about.

I was just thinking it might be nice to be able to use something like uninitialized in struct inner constructors (i.e. Expr(:new, ...) expressions where I can indicate exactly which fields to leave uninitialized - but then maybe that would need to be a language keyword or something since if it is an object I should be able to throw it inside a struct?).

[ChrisRackauckas]

Bringing up https://github.com/JuliaLang/julia/issues/25107 since it seems a lot of this proposal mentions shape, when shape isn't enough information to fully characterize the structure of many abstract arrays.

[AzamatB]

I often find myself wanting to generate random Symmetric PSD Matrix, so end up writing something like

julia> S = rand(4,4); S = S'S + I

It would be nice to abstract this away by adding constructors for generating random structured matrix types (like Symmetric, Diagonal, Orthogonal, Orthonormal, etc.) maybe after #8240 is settled.