{"action":"created","comment":{"url":"https://api.github.com/repos/gonum/matrix/pulls/comments/40516022","id":40516022,"diff_hunk":"@@ -2,38 +2,119 @@\n // Use of this source code is governed by a BSD-style\n // license that can be found in the LICENSE file.\n \n-// Package mat64 provides basic linear algebra operations for float64 matrices.\n-//\n-// mat64 provides a set of concrete types that implement different classes of\n-// matrices (Dense, Symmetric, etc.) and operations on them. In most cases,\n-// an operation which results in a matrix value is a method on the value being\n-// produced. As an example, the method *Dense.Add(a,b) performs element-wise\n-// addition of the matrices a and b and stores the result into the method receiver.\n-// In all operations that assign to the receiver, the receiver may either have\n-// the correct dimensions for the result of the method or may be a zero-sized matrix.\n-// In the latter case, the receiver will be modified to the correct size, allocating\n-// data if necessary. The T() method is used for transposition; c.Mul(a.T(), b) computes\n-// c = a^T * b. Again, if c is a zero-sized matrix it will be modified to be the\n-// correct size, otherwise c must be size ac×bc, that is the number of columns in\n-// a (the number of rows in a^T) by the number of columns in b.\n-//\n-// Many operations are performed by calling into the gonum/blas/blas64 and\n-// gonum/lapack/lapack64 packages which implement BLAS and LAPACK routines\n-// respectively. By default, blas64 and lapack64 use native Go implementations\n-// of the routines. Alternatively, it is possible to use c-based libraries for\n-// the BLAS routines and/or the LAPACK routines with the respective cgo packages\n-// and Use routines. The Go implementation of LAPACK itself makes calls to blas64,\n-// so if a cgo BLAS implementation is used, the lapack64 calls will be partially\n-// executed in Go and partially executed in c.\n-//\n-// Along with the concrete matrix types are corresponding interface types. The\n-// Matrix interface, for example, represents an arbitrary matrix of float64 values,\n-// and the Symmetricer interface represents an arbitrary symmetric matrix. This\n-// abstract representation enables efficiency. In c.Mul(a,b), for example, if\n-// a is a RawSymmetricer and b is a RawMatrixer the specialized function for\n-// symmetric-dense multiplication (blas64.Symm) will be called. No specific\n-// guarantees are made about the performance of any method, as many special cases\n-// are possible. In particular, note that an abstract matrix type may be copied\n-// into a concrete type of the corresponding value. If there are specific special\n-// cases that are needed, please submit a pull-request or file an issue.\n+// Package mat64 provides implementations of float64 matrix structures and\n+// linear algebra operations on them.\n+//\n+// Overiew\n+//\n+// This section provides a quick overview of the matrix package. The following\n+// sections provide more in depth commentary.\n+//\n+// mat64 provides:\n+//  - Interfaces for Matrix classes (Matrix, Symmetric, Triangular)\n+//  - Concrete implementations (Dense, SymDense, TriDense)\n+//  - Methods and functions for using matrix data (Add, Trace, SymRankOne)\n+//  - Types for constructing and using matrix factorizations (QR, LU)\n+//\n+// A matrix may be constructed through the corresponding New function. If no\n+// backing array is provided the matrix will be initialized to all zeros.\n+//  // Allocate a zeroed array of size 3×5\n+//  zero := mat64.NewDense(3, 5, nil)\n+// If a backing data slice is provided, the matrix will have those elements.\n+// Matrices are all stored in row-major format.\n+//  // Generate a 6×6 matrix of random values.\n+//  data := make([]float64, 36)\n+//  for i := range data {\n+//\t\tdata[i] = rand.NormFloat64()\n+//  }\n+//  a := mat64.NewDense(6,6, data)\n+//\n+// Operations involving matrix data are implemented as functions when the values\n+// of the matrix remain unchanged\n+//  tr := mat64.Trace(a)\n+// and are implemented as methods when the operation modifies the receiver.\n+//  zero.Copy(a)\n+//\n+// Receivers must be the correct size for the matrix operations, otherwise the\n+// operation will panic. As a special case for convenience, a zero-sized matrix\n+// will be modified to have the correct size, allocating data if necessary.\n+//  var c mat64.Dense // construct a new zero-sized matrix\n+//  c.Mul(a, a)       // c is automatically adjusted to be 6×6\n+//\n+// The Matrix Interface(s)\n+//\n+// The Matrix interface is the common link between the concrete types. The Matrix\n+// interface is defined by three functions: Dims, which returns the dimensions\n+// of the Matrix, At, which returns the element in the specified location, and\n+// T, which will be discussed later. All of the concrete types can perform these\n+// behaviors and so implement the interface. Methods and functions are designed\n+// to use this interface, so in particular the method\n+//  func (m *Dense) Mul(a, b Matrix)\n+// constructs a *Dense from the result of a muliplication with any Matrix types,\n+// not just *Dense. Where more restrictive requirements must be met, there are also the\n+// Symmetric and Triangular interfaces. For example, in\n+//  func (s *SymDense) AddSym(a, b Symmetric)\n+// the Symmetric interface guarantees a symmetric result.\n+//\n+// Transposes\n+//\n+// The T method is used for transpostion. For example, c.Mul(a.T(), b) computes\n+// c = a^T * b. The mat64 types implement this method using an implicit transpose.\n+// Note that some operations have a transpose as part of their definition, as in\n+// *SymDense.SymOuterK.\n+//\n+// Matrix Factorization\n+//\n+// Matrix factorizations, such as the LU decomposition, typically have their own\n+// specific data storage, and so are each implemented as a specific type. The\n+// factorization can be computed through a call to Factorize\n+//  var lu mat64.LU\n+//  lu.Factorize(a)\n+// The elements of the factorization can be extracted through methods on the\n+// appropriate type, i.e. *TriDense.LFromLU and *TriDense.UFromLU. Alternatively,\n+// they can be used directly, as in *Dense.SolveLU. Some factorizations can be\n+// updated directly, without needing to update the original matrix and refactorize,\n+// as in *LU.RankOne.\n+//\n+// BLAS and LAPACK\n+//\n+// BLAS and LAPACK are the standard APIs for linear algebra routines. Many\n+// operations in mat64 are implemented using calls to the wrapper functions\n+// in gonum/blas/blas64 and gonum/lapack/lapack64. By default, blas64 and\n+// lapack64 call the native Go implementations of the routines.  Alternatively,","path":"mat64/doc.go","position":117,"original_position":117,"commit_id":"de7f21feada5ee1c800e2949b7a2217d4e8970b2","original_commit_id":"de7f21feada5ee1c800e2949b7a2217d4e8970b2","user":{"login":"vladimir-ch","id":1837502,"avatar_url":"https://avatars.githubusercontent.com/u/1837502?v=3","gravatar_id":"","url":"https://api.github.com/users/vladimir-ch","html_url":"https://github.com/vladimir-ch","followers_url":"https://api.github.com/users/vladimir-ch/followers","following_url":"https://api.github.com/users/vladimir-ch/following{/other_user}","gists_url":"https://api.github.com/users/vladimir-ch/gists{/gist_id}","starred_url":"https://api.github.com/users/vladimir-ch/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/vladimir-ch/subscriptions","organizations_url":"https://api.github.com/users/vladimir-ch/orgs","repos_url":"https://api.github.com/users/vladimir-ch/repos","events_url":"https://api.github.com/users/vladimir-ch/events{/privacy}","received_events_url":"https://api.github.com/users/vladimir-ch/received_events","type":"User","site_admin":false},"body":"Nitpicking: delete one space before Alternatively","created_at":"2015-09-28T03:13:28Z","updated_at":"2015-09-28T03:13:28Z","html_url":"https://github.com/gonum/matrix/pull/245#discussion_r40516022","pull_request_url":"https://api.github.com/repos/gonum/matrix/pulls/245","_links":{"self":{"href":"https://api.github.com/repos/gonum/matrix/pulls/comments/40516022"},"html":{"href":"https://github.com/gonum/matrix/pull/245#discussion_r40516022"},"pull_request":{"href":"https://api.github.com/repos/gonum/matrix/pulls/245"}}},"pull_request":{"url":"https://api.github.com/repos/gonum/matrix/pulls/245","id":46114003,"html_url":"https://github.com/gonum/matrix/pull/245","diff_url":"https://github.com/gonum/matrix/pull/245.diff","patch_url":"https://github.com/gonum/matrix/pull/245.patch","issue_url":"https://api.github.com/repos/gonum/matrix/issues/245","number":245,"state":"open","locked":false,"title":"Improve doc comment","user":{"login":"btracey","id":3680859,"avatar_url":"https://avatars.githubusercontent.com/u/3680859?v=3","gravatar_id":"","url":"https://api.github.com/users/btracey","html_url":"https://github.com/btracey","followers_url":"https://api.github.com/users/btracey/followers","following_url":"https://api.github.com/users/btracey/following{/other_user}","gists_url":"https://api.github.com/users/btracey/gists{/gist_id}","starred_url":"https://api.github.com/users/btracey/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/btracey/subscriptions","organizations_url":"https://api.github.com/users/btracey/orgs","repos_url":"https://api.github.com/users/btracey/repos","events_url":"https://api.github.com/users/btracey/events{/privacy}","received_events_url":"https://api.github.com/users/btracey/received_events","type":"User","site_admin":false},"body":"","created_at":"2015-09-28T01:26:24Z","updated_at":"2015-09-28T03:13:28Z","closed_at":null,"merged_at":null,"merge_commit_sha":"8cc5ed5330a5e0403b2096d754b29035fe40d9db","assignee":null,"milestone":null,"commits_url":"https://api.github.com/repos/gonum/matrix/pulls/245/commits","review_comments_url":"https://api.github.com/repos/gonum/matrix/pulls/245/comments","review_comment_url":"https://api.github.com/repos/gonum/matrix/pulls/comments{/number}","comments_url":"https://api.github.com/repos/gonum/matrix/issues/245/comments","statuses_url":"https://api.github.com/repos/gonum/matrix/statuses/de7f21feada5ee1c800e2949b7a2217d4e8970b2","head":{"label":"gonum:updatedoc","ref":"updatedoc","sha":"de7f21feada5ee1c800e2949b7a2217d4e8970b2","user":{"login":"gonum","id":3771091,"avatar_url":"https://avatars.githubusercontent.com/u/3771091?v=3","gravatar_id":"","url":"https://api.github.com/users/gonum","html_url":"https://github.com/gonum","followers_url":"https://api.github.com/users/gonum/followers","following_url":"https://api.github.com/users/gonum/following{/other_user}","gists_url":"https://api.github.com/users/gonum/gists{/gist_id}","starred_url":"https://api.github.com/users/gonum/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/gonum/subscriptions","organizations_url":"https://api.github.com/users/gonum/orgs","repos_url":"https://api.github.com/users/gonum/repos","events_url":"https://api.github.com/users/gonum/events{/privacy}","received_events_url":"https://api.github.com/users/gonum/received_events","type":"Organization","site_admin":false},"repo":{"id":8569918,"name":"matrix","full_name":"gonum/matrix","owner":{"login":"gonum","id":3771091,"avatar_url":"https://avatars.githubusercontent.com/u/3771091?v=3","gravatar_id":"","url":"https://api.github.com/users/gonum","html_url":"https://github.com/gonum","followers_url":"https://api.github.com/users/gonum/followers","following_url":"https://api.github.com/users/gonum/following{/other_user}","gists_url":"https://api.github.com/users/gonum/gists{/gist_id}","starred_url":"https://api.github.com/users/gonum/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/gonum/subscriptions","organizations_url":"https://api.github.com/users/gonum/orgs","repos_url":"https://api.github.com/users/gonum/repos","events_url":"https://api.github.com/users/gonum/events{/privacy}","received_events_url":"https://api.github.com/users/gonum/received_events","type":"Organization","site_admin":false},"private":false,"html_url":"https://github.com/gonum/matrix","description":"Matrix packages for the Go language.","fork":false,"url":"https://api.github.com/repos/gonum/matrix","forks_url":"https://api.github.com/repos/gonum/matrix/forks","keys_url":"https://api.github.com/repos/gonum/matrix/keys{/key_id}","collaborators_url":"https://api.github.com/repos/gonum/matrix/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/gonum/matrix/teams","hooks_url":"https://api.github.com/repos/gonum/matrix/hooks","issue_events_url":"https://api.github.com/repos/gonum/matrix/issues/events{/number}","events_url":"https://api.github.com/repos/gonum/matrix/events","assignees_url":"https://api.github.com/repos/gonum/matrix/assignees{/user}","branches_url":"https://api.github.com/repos/gonum/matrix/branches{/branch}","tags_url":"https://api.github.com/repos/gonum/matrix/tags","blobs_url":"https://api.github.com/repos/gonum/matrix/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/gonum/matrix/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/gonum/matrix/git/refs{/sha}","trees_url":"https://api.github.com/repos/gonum/matrix/git/trees{/sha}","statuses_url":"https://api.github.com/repos/gonum/matrix/statuses/{sha}","languages_url":"https://api.github.com/repos/gonum/matrix/languages","stargazers_url":"https://api.github.com/repos/gonum/matrix/stargazers","contributors_url":"https://api.github.com/repos/gonum/matrix/contributors","subscribers_url":"https://api.github.com/repos/gonum/matrix/subscribers","subscription_url":"https://api.github.com/repos/gonum/matrix/subscription","commits_url":"https://api.github.com/repos/gonum/matrix/commits{/sha}","git_commits_url":"https://api.github.com/repos/gonum/matrix/git/commits{/sha}","comments_url":"https://api.github.com/repos/gonum/matrix/comments{/number}","issue_comment_url":"https://api.github.com/repos/gonum/matrix/issues/comments{/number}","contents_url":"https://api.github.com/repos/gonum/matrix/contents/{+path}","compare_url":"https://api.github.com/repos/gonum/matrix/compare/{base}...{head}","merges_url":"https://api.github.com/repos/gonum/matrix/merges","archive_url":"https://api.github.com/repos/gonum/matrix/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/gonum/matrix/downloads","issues_url":"https://api.github.com/repos/gonum/matrix/issues{/number}","pulls_url":"https://api.github.com/repos/gonum/matrix/pulls{/number}","milestones_url":"https://api.github.com/repos/gonum/matrix/milestones{/number}","notifications_url":"https://api.github.com/repos/gonum/matrix/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/gonum/matrix/labels{/name}","releases_url":"https://api.github.com/repos/gonum/matrix/releases{/id}","created_at":"2013-03-05T01:59:12Z","updated_at":"2015-09-24T23:37:00Z","pushed_at":"2015-09-28T02:30:33Z","git_url":"git://github.com/gonum/matrix.git","ssh_url":"git@github.com:gonum/matrix.git","clone_url":"https://github.com/gonum/matrix.git","svn_url":"https://github.com/gonum/matrix","homepage":"","size":2988,"stargazers_count":147,"watchers_count":147,"language":"Go","has_issues":true,"has_downloads":true,"has_wiki":true,"has_pages":false,"forks_count":25,"mirror_url":null,"open_issues_count":15,"forks":25,"open_issues":15,"watchers":147,"default_branch":"master"}},"base":{"label":"gonum:master","ref":"master","sha":"4c84fc6d4435cd5d24ac0fb79103a83160e1559b","user":{"login":"gonum","id":3771091,"avatar_url":"https://avatars.githubusercontent.com/u/3771091?v=3","gravatar_id":"","url":"https://api.github.com/users/gonum","html_url":"https://github.com/gonum","followers_url":"https://api.github.com/users/gonum/followers","following_url":"https://api.github.com/users/gonum/following{/other_user}","gists_url":"https://api.github.com/users/gonum/gists{/gist_id}","starred_url":"https://api.github.com/users/gonum/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/gonum/subscriptions","organizations_url":"https://api.github.com/users/gonum/orgs","repos_url":"https://api.github.com/users/gonum/repos","events_url":"https://api.github.com/users/gonum/events{/privacy}","received_events_url":"https://api.github.com/users/gonum/received_events","type":"Organization","site_admin":false},"repo":{"id":8569918,"name":"matrix","full_name":"gonum/matrix","owner":{"login":"gonum","id":3771091,"avatar_url":"https://avatars.githubusercontent.com/u/3771091?v=3","gravatar_id":"","url":"https://api.github.com/users/gonum","html_url":"https://github.com/gonum","followers_url":"https://api.github.com/users/gonum/followers","following_url":"https://api.github.com/users/gonum/following{/other_user}","gists_url":"https://api.github.com/users/gonum/gists{/gist_id}","starred_url":"https://api.github.com/users/gonum/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/gonum/subscriptions","organizations_url":"https://api.github.com/users/gonum/orgs","repos_url":"https://api.github.com/users/gonum/repos","events_url":"https://api.github.com/users/gonum/events{/privacy}","received_events_url":"https://api.github.com/users/gonum/received_events","type":"Organization","site_admin":false},"private":false,"html_url":"https://github.com/gonum/matrix","description":"Matrix packages for the Go language.","fork":false,"url":"https://api.github.com/repos/gonum/matrix","forks_url":"https://api.github.com/repos/gonum/matrix/forks","keys_url":"https://api.github.com/repos/gonum/matrix/keys{/key_id}","collaborators_url":"https://api.github.com/repos/gonum/matrix/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/gonum/matrix/teams","hooks_url":"https://api.github.com/repos/gonum/matrix/hooks","issue_events_url":"https://api.github.com/repos/gonum/matrix/issues/events{/number}","events_url":"https://api.github.com/repos/gonum/matrix/events","assignees_url":"https://api.github.com/repos/gonum/matrix/assignees{/user}","branches_url":"https://api.github.com/repos/gonum/matrix/branches{/branch}","tags_url":"https://api.github.com/repos/gonum/matrix/tags","blobs_url":"https://api.github.com/repos/gonum/matrix/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/gonum/matrix/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/gonum/matrix/git/refs{/sha}","trees_url":"https://api.github.com/repos/gonum/matrix/git/trees{/sha}","statuses_url":"https://api.github.com/repos/gonum/matrix/statuses/{sha}","languages_url":"https://api.github.com/repos/gonum/matrix/languages","stargazers_url":"https://api.github.com/repos/gonum/matrix/stargazers","contributors_url":"https://api.github.com/repos/gonum/matrix/contributors","subscribers_url":"https://api.github.com/repos/gonum/matrix/subscribers","subscription_url":"https://api.github.com/repos/gonum/matrix/subscription","commits_url":"https://api.github.com/repos/gonum/matrix/commits{/sha}","git_commits_url":"https://api.github.com/repos/gonum/matrix/git/commits{/sha}","comments_url":"https://api.github.com/repos/gonum/matrix/comments{/number}","issue_comment_url":"https://api.github.com/repos/gonum/matrix/issues/comments{/number}","contents_url":"https://api.github.com/repos/gonum/matrix/contents/{+path}","compare_url":"https://api.github.com/repos/gonum/matrix/compare/{base}...{head}","merges_url":"https://api.github.com/repos/gonum/matrix/merges","archive_url":"https://api.github.com/repos/gonum/matrix/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/gonum/matrix/downloads","issues_url":"https://api.github.com/repos/gonum/matrix/issues{/number}","pulls_url":"https://api.github.com/repos/gonum/matrix/pulls{/number}","milestones_url":"https://api.github.com/repos/gonum/matrix/milestones{/number}","notifications_url":"https://api.github.com/repos/gonum/matrix/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/gonum/matrix/labels{/name}","releases_url":"https://api.github.com/repos/gonum/matrix/releases{/id}","created_at":"2013-03-05T01:59:12Z","updated_at":"2015-09-24T23:37:00Z","pushed_at":"2015-09-28T02:30:33Z","git_url":"git://github.com/gonum/matrix.git","ssh_url":"git@github.com:gonum/matrix.git","clone_url":"https://github.com/gonum/matrix.git","svn_url":"https://github.com/gonum/matrix","homepage":"","size":2988,"stargazers_count":147,"watchers_count":147,"language":"Go","has_issues":true,"has_downloads":true,"has_wiki":true,"has_pages":false,"forks_count":25,"mirror_url":null,"open_issues_count":15,"forks":25,"open_issues":15,"watchers":147,"default_branch":"master"}},"_links":{"self":{"href":"https://api.github.com/repos/gonum/matrix/pulls/245"},"html":{"href":"https://github.com/gonum/matrix/pull/245"},"issue":{"href":"https://api.github.com/repos/gonum/matrix/issues/245"},"comments":{"href":"https://api.github.com/repos/gonum/matrix/issues/245/comments"},"review_comments":{"href":"https://api.github.com/repos/gonum/matrix/pulls/245/comments"},"review_comment":{"href":"https://api.github.com/repos/gonum/matrix/pulls/comments{/number}"},"commits":{"href":"https://api.github.com/repos/gonum/matrix/pulls/245/commits"},"statuses":{"href":"https://api.github.com/repos/gonum/matrix/statuses/de7f21feada5ee1c800e2949b7a2217d4e8970b2"}}}}