Just a couple of comments:
As I was typing, Mars0i's message came in, with much of much what I wanted to say about documentation, but I'll reiterate a couple of key points: You can have an intuitive API that's poorly documented, just as it's possible to have a terrible API with great documentation (though certainly it's _easier_ to document a nice, clean API...). Those two things are relatively orthogonal. Your comments about documentation came in response to a line of thought about shortcomings of the core.matrix API, but bad documentation is not actually a shortcoming of the API proper. And not building around core.matrix because the API is bad is different than not building around it because the API is poorly documented (though both understandable), particularly when the latter is relatively easy to fix (even after the fact). However, I have to personally disagree about the state of the documentation. I think it's actually pretty decent. For example, on the GitHub page (README) there is a link to a wiki page for implementers that I think is fairly straight forward. If you go to the protocols namespace (as suggested in the implementers wiki page), the protocols which _must_ be implemented are well demarcated, and most of the protocols have pretty good documentation. There is certainly room for improvement though. The example of * vs mmul mentioned could have been avoided had https://github.com/mikera/core.matrix/blob/master/src/main/clojure/clojure/core/matrix/examples.clj (linked to from the README) more clearly denoted what * does, and added mmul as well (since I think that's what folks would use more frequently anyway...). There's probably also room for more thorough/robust high-level descriptions of key concepts. But I think overall the documentation is far from _bad_. That's just my opinion though; if other people are having trouble with the docs, there may be more room for improvement than I realize. Dragan, you point out that in the Clojure community "there are dozens of Clojure libraries for SQL, http, visualization, etc, and all have their place." That's certainly true, but you're comparing kittens to koalas here. Matrices/arrays are *data types*, while the things you mention are "libraries that do things with already standardized data types". Something common to every single Clojure SQL library out there is that it's likely going to return a seq of vectors or maps; in either case, these are the data types around which vast swaths of the Clojure code out there has already been built. So there's less need for standardization here. The situation around matrix/array programming is very different; here you have tightly coupled abstract data types and functionality/operations, and there is a lot that could be built up around them and which benefits from a standardization. I've talked with folks at some of the big(gish) Clojure companies doing ML, and they love core.matrix for this very reason. A perfect example of something similar is graphs; graphs are data types which are tightly coupled with a number of operations, and loom is a project which has been around for a while to try and unify an API around these data types and operations. When Mark Engelberg realized that loom didn't fit all his needs (which had to do with more robust/general graph types and operations; much more extensive than just beefing up performance on a subset of the functionality...), he didn't go and create his own thing. Well... he did... but he did it in such a way that his constructions also implemented the loom protocols, so what you wrote would still be relatively interoperable with loom code. This is a great example because even though his approach is much more general and I think should/could be *THE* graph api, he still was able to make things as compatible as he possibly could. This is the beauty of Clojure at it's greatest. As for complex matrices, there's already a project underway for this, with a rather elegant approach that would allow for any underlying implementation to be used: https://github.com/mikera/core.matrix.complex. Of course, a native implementation that supported complex types would be lovely, and could potentially be a lot faster than doing things this way, but it's not true that there's no complex story. As for performance benchmarks, I have to echo Mike that it seemed strange to me that you were claiming you were faster on ALL benchmarks when I'd only seen data on one. Would you mind sharing your full benchmarking analyses? With all that out of the way... I'm glad that you're willing to play ball here with the core.matrix community, and thank you for what I think has been a very productive discussion. I think we all went from talking _past_ each other, to understanding what the issues are and can now hopefully start moving forward and making things happen. While I think we'd all love to have you (Dragan) personally working on the core.matrix implementations, I agree with Mars0i that just having you agree to work-with/advise others who would do the actual work is great. I'd personally love to take that on myself, but I already have about a half dozen side projects I'm working on which I barely have time for. Oh, and a four month old baby :scream:! So if there's anyone else who's willing, I may leave it to them :-) Best Chris On Mon, Jun 22, 2015 at 7:28 AM, Mars0i <marsh...@logical.net> wrote: > It may be that there's agreement on everything that matters. Dragan, > you've said that you wouldn't mind others integrating Neanderthal into > core.matrix, but that you don't want to do that. That you are willing to > work with others on this is probably all that's needed. People may have > questions, want you to consider pull requests, etc. I think that > integrating Neanderthal into core. matrix will be an attractive project for > one someone. > > (For the record I don't think it's fair to criticize core.matrix as not > being an API because the documentation is limited. The API is in the > protocols, etc. It's all there in the source. Of course anyone using > core.matrix occasionally encounters frustration at the lack of > documentation, but core.matrix is a work in progress. That's the nature of > the situation. I have been able to figure out how to do everything I > needed to do using only the existing documentation, source code, > docstrings, asking occasional questions with helpful answers from others. > If I had more time, maybe I would work on the documentation more than the > tiny bit I've been able to do so. Similar remarks apply to what clatrix > doesn't do well yet. Being unfinished is not a design flaw.) > > -- > You received this message because you are subscribed to the Google > Groups "Clojure" group. > To post to this group, send email to clojure@googlegroups.com > Note that posts from new members are moderated - please be patient with > your first post. > To unsubscribe from this group, send email to > clojure+unsubscr...@googlegroups.com > For more options, visit this group at > http://groups.google.com/group/clojure?hl=en > --- > You received this message because you are subscribed to a topic in the > Google Groups "Clojure" group. > To unsubscribe from this topic, visit > https://groups.google.com/d/topic/clojure/dFPOOw8pSGI/unsubscribe. > To unsubscribe from this group and all its topics, send an email to > clojure+unsubscr...@googlegroups.com. > For more options, visit https://groups.google.com/d/optout. > -- You received this message because you are subscribed to the Google Groups "Clojure" group. To post to this group, send email to clojure@googlegroups.com Note that posts from new members are moderated - please be patient with your first post. To unsubscribe from this group, send email to clojure+unsubscr...@googlegroups.com For more options, visit this group at http://groups.google.com/group/clojure?hl=en --- You received this message because you are subscribed to the Google Groups "Clojure" group. To unsubscribe from this group and stop receiving emails from it, send an email to clojure+unsubscr...@googlegroups.com. For more options, visit https://groups.google.com/d/optout.
