Export policy

[acroy]

As briefly discussed in #5 we should decide on a policy for exports. Since exports in some sense also define the package API, this might be tricky to decide now. AFAICT there are several options:

1. Don't export anything.
2. Only export QuArray and FiniteBasis and the related functions.
3. In addition to 2, also export abstract types.
4. In addition to 3, also export "helper functions/types". For example, functions creating special matrices (like raisematrix etc).

[jrevels]

I think the main motivation behind the decision to export something in Julia is two-fold:

• Will this actually be useful to others?
• Will allowing others to use this encourage them to write bad/confusing code?

I haven't found that traditional OO concerns (e.g. safety via a mutation permissions scheme built on top of message passing) are as relevant in Julia, since a type holding "private" state is fairly rare. Even when a type DOES use private state, it's generally handled at the constructor level, as well as by a refusal to provide accessor functions to the private information.

In general, the deciding factor for exporting abstract types should be "Do we want the user to be able to dispatch on this type without importing it?". I can understand not exporting most abstract types, since I assume that most of them will rarely be used outside of somebody actually writing packages on top of QuBase. The exceptions here are subtypes of AbstractStructure.

I'm of the opinion that it's okay for raisematrix and similar functions to be exported. There are many calculations that are relevant to doing quantum mechanics that don't require the basis information that QuArrays store, so offering that code up will do much more good than harm. The only real issue I can think of is that this might accidentally prompt users to "go off the reservation", as it were, and do something like write duplicate code for making a QuArray creation operator because they know about raisematrix but not about raiseop. I think this problem can fairly easily be solved by the proper documentation - QuArray operations are treated as primary (heavy tutorial use/shown as part of the "main" docs) while helper functions are treated as secondary (listed in their own section/not used in "main" doc examples).

[acroy]

How about putting the abstract types and the interface functions into a submodule (Interface or whatever)? This would also make it easier to separate documentation of the interface from the concrete QuArray stuff. If someone wants to extend functionality or types, he/she could just do using QuBase.Interface to get the necessary types.

Regarding raisematrix et al I think there is per se no problem with exporting them, but if we do this we should try to be consistent and always provide both versions (if possible). We could tag the respective functions in the documentation to indicate that both versions exist. (Of course, in the end users will always ask for the matrix version of functions for which we don't support this :-) So I am not entirely against this, but I think it means more maintenance for us.

[jrevels]

the interface functions

Which functions are you referring to?

As for abstract types, I'd rather just not export them then move them into a submodule. But I still don't see the downside of exporting types, other than having to document the type tree (which should probably be done as a matter of dev documentation anyway).

Regarding raisematrix et al I think there is per se no problem with exporting them, but if we do this we should try to be consistent and always provide both versions (if possible). We could tag the respective functions in the documentation to indicate that both versions exist. (Of course, in the end users will always ask for the matrix version of functions for which we don't support this :-) So I am not entirely against this, but I think it means more maintenance for us.

I think it's reasonable to not to export functionality until somebody is ready to write documentation for it. Until we start documenting things, I suppose what we export will serve as a guide for the technical debt we'll have to pay off with the first wave of documentation.

[acroy]

Which functions are you referring to?

Uh, nothing in particular. See below for a maybe clearer definition.

As for abstract types, I'd rather just not export them then move them into a submodule. But I still don't see the downside of exporting types, other than having to document the type tree (which should probably be done as a matter of dev documentation anyway).

Maybe I am just stuck in old habits, but I would prefer to somehow separate "user interface" and "developer interface". Of course it doesn't harm if you export the (abstract) types, but OTOH as as "normal user" you are probably not using them anyways. Maybe I am making this too complicated.

I think it's reasonable to not to export functionality until somebody is ready to write documentation for it. Until we start documenting things, I suppose what we export will serve as a guide for the technical debt we'll have to pay off with the first wave of documentation.

Yes, that is one aspect. But if you think ahead, we will likely have a wild mix of functions which have a matrix counterpart and functions without one. You can document this, but if there is no guiding principle behind this it will not be intuitive. So either we say that we always want to have a matrix function (if it makes sense) - or in other words always provide the QuArray function in terms of a matrix function, like with the ladder ops - or we don't officially support the matrix variants.

[jrevels]

But if you think ahead, we will likely have a wild mix of functions which have a matrix counterpart and functions without one. You can document this, but if there is no guiding principle behind this it will not be intuitive.

This makes sense. After thinking on it some more, I don't think it would be productive to put effort into supporting/documenting the Array counterparts to QuArray functions, at least until we have a more solid feature set. I'll remove those exports for now and close up this issue.