14 Browse
This chapter discusses the Browse Browse@Browse component of HyperDoc. HyperDoc@{HyperDoc} We suggest you invoke Axiom and work through this chapter, section by section, following our examples to gain some familiarity with Browse.
14.1 The Front Page: Searching the Library
To enter Browse, click on Browse on the top level page of HyperDoc to get the front page of Browse.
To use this page, you first enter a search string into the input area at the top, then click on one of the buttons below. We show the use of each of the buttons by example.
Constructors
First enter the search string Matrix into the input area and click on Constructors. What you get is the constructor page for Matrix. We show and describe this page in detail in ugBrowseDomain . By convention, Axiom does a case-insensitive search for a match. Thus matrix is just as good as Matrix, has the same effect as MaTrix, and so on. We recommend that you generally use small letters for names however. A search string with only capital letters has a special meaning (see ugBrowseCapitalizationConvention ).
Click on 
to return to the Browse front page.
Use the symbol ``*'' in search strings as a wild card. A wild card matches any substring, including the empty string. For example, enter the search string *matrix* into the input area and click on Constructors.To get only categories, domains, or packages, rather than all constructors, you can click on the corresponding button to the right of Constructors. What you get is a table of all constructors whose names contain the string ``matrix.''
All constructors containing the string are listed, whether exposed or unexposed. You can hide the names of the unexposed constructors by clicking on the *= unexposed button in the Views panel at the bottom of the window. (The button will change to exposed only.)
One of the names in this table is Matrix. Click on Matrix. What you get is again the constructor page for Matrix. As you see, Browse gives you a large network of information in which there are many ways to reach the same pages. Matrix
Again click on the to return to the table of constructors
whose names contain matrix.
Below the table is a Views panel. This panel contains buttons that let you view constructors in different ways. To learn about views of constructors, skip to ugBrowseViewsOfConstructors .
Click on to return to the Browse front page.
Operations
Enter *matrix into the input area and click on Operations. This time you get a table of operations whose names end with matrix or Matrix.
If you select an operation name, you go to a page describing all the operations in Axiom of that name. At the bottom of an operation page is another kind of Views panel, one for operation pages. To learn more about these views, skip to ugBrowseViewsOfOperations .
Click on to return to the Browse front page.
Attributes
This button gives you a table of attribute names that match the search string. Enter the search string * and click on Attributes to get a list of all system attributes.
Click on to return to the Browse front page.
Again there is a Views panel at the bottom with buttons that let you view the attributes in different ways.
General
This button does a general search for all constructor, operation, and attribute names matching the search string. Enter the search string *matrix* into the input area. Click on General to find all constructs that have matrix as a part of their name.
The summary gives you all the names under a heading when the number of entries is less than 10.
Click on to return to the Browse front page.
Documentation
Again enter the search key *matrix* and this time click on Documentation. This search matches any constructor, operation, or attribute name whose documentation contains a substring matching matrix.
Click on to return to the Browse front page.
Complete
This search combines both General and Documentation.
14.2 The Constructor Page
In this section we look in detail at a constructor page for domain Matrix. Enter matrix into the input area on the main Browse page and click on Constructors.
The header part tells you that Matrix has abbreviation MATRIX and one argument called R that must be a domain of category Ring. Just what domains can be arguments of Matrix? To find this out, click on the R on the second line of the heading. What you get is a table of all acceptable domain parameter values of R, or a table of rings in Axiom.
Click on to return to the constructor page for
Matrix.
If you have access to the source code of Axiom, the third source code line of the heading gives you the name of the source file containing the definition of Matrix. Click on it to pop up an editor window containing the source code of Matrix.
We recommend that you leave the editor window up while working through this chapter as you occasionally may want to refer to it.
14.2.1.1 Description
Click here to bring up a page with a brief description of constructor Matrix. If you have access to system source code, note that these comments can be found directly over the constructor definition.
14.2.1.2 Operations
Click here to get a table of operations exported by Matrix. You may wish to widen the window to have multiple columns as below.
If you click on an operation name, you bring up a description page for the operations. For a detailed description of these pages, skip to ugBrowseViewsOfOperations .
14.2.1.3 Attributes
Click here to get a table of the two attributes exported by Matrix: attribute finiteAggregate and shallowlyMutable. These are two computational properties that result from Matrix being regarded as a data structure.
14.2.1.4 Examples
Click here to get an examples page with examples of operations to create and manipulate matrices.
Read through this section. Try selecting the various buttons. Notice that if you click on an operation name, such as newnewMatrix, you bring up a description page for that operation from Matrix.
Example pages have several examples of Axiom commands. Each example has an active button to its left. Click on it! A pre-computed answer is pasted into the page immediately following the command. If you click on the button a second time, the answer disappears. This button thus acts as a toggle: ``now you see it; now you don't.''
Note also that the Axiom commands themselves are active. If you want to see Axiom execute the command, then click on it! A new Axiom window appears on your screen and the command is executed.
At the end of the page is generally a menu of buttons that lead you to further sections. Select one of these topics to explore its contents.
14.2.1.5 Exports
Click here to see a page describing the exports of Matrix exactly as described by the source code.
As you see, Matrix declares that it exports all the operations and attributes exported by category MatrixCategory(R, Row, Col). In addition, two operations, diagonalMatrix and inverse, are explicitly exported.
To learn a little about the structure of Axiom, we suggest you do the following exercise.
Otherwise, go on to the next section.
Matrix explicitly exports only two operations. The other operations are thus exports of MatrixCategory. In general, operations are usually not explicitly exported by a domain. Typically they are inherited from several different categories. Let's find out from where the operations of Matrix come.
- Click on MatrixCategory, then on Exports. Here you see that MatrixCategory explicitly exports many matrix operations. Also, it inherits its operations from TwoDimensionalArrayCategory.
- Click on TwoDimensionalArrayCategory, then on Exports. Here you see explicit operations dealing with rows and columns. In addition, it inherits operations from HomogeneousAggregate.
- Click on and then
click on Object, then on Exports, where you see
there are no exports.
- Click on repeatedly to return to the constructor page
for Matrix.
14.2.1.6 Related Operations
Click here bringing up a table of operations that are exported by packages but not by Matrix itself.
To see a table of such packages, use the Relatives button on the Cross Reference page described next.
14.2.2 Cross Reference
Click on the Cross Reference button on the main constructor page for Matrix. This gives you a page having various cross reference information stored under the respective buttons.
14.2.2.1 Parents
The parents of a domain are the same as the categories mentioned under the Exports button on the first page. Domain Matrix has only one parent but in general a domain can have any number.
14.2.2.2 Ancestors
The ancestors of a constructor consist of its parents, the parents of its parents, and so on. Did you perform the exercise in the last section under Exports? If so, you see here all the categories you found while ascending the Exports chain for Matrix.
14.2.2.3 Relatives
The relatives of a domain constructor are package constructors that provide operations in addition to those exported by the domain.
Try this exercise.
- Click on Relatives, bringing up a list of packages.
- Click on LinearSystemMatrixPackage bringing up its constructor page.You may want to widen your HyperDoc window to make what follows more legible.
- Click on Operations. Here you see rank, an operation also exported by Matrix itself.
- Click on rank. This rankrankLinearSystemMatrixPackage has two arguments and thus is different from the rankrankMatrix from Matrix.
- Click on to return to the list of operations for the
package LinearSystemMatrixPackage.
- Click on solve to bring up a solvesolveLinearSystemMatrixPackage for linear systems of equations.
- Click on several times to return to the cross
reference page for Matrix.
14.2.2.4 Dependents
The dependents of a constructor are those domains or packages that mention that constructor either as an argument or in its exports.
If you click on Dependents two entries may surprise you: RectangularMatrix and SquareMatrix. This happens because Matrix, as it turns out, appears in signatures of operations exported by these domains.
14.2.2.5 Lineage
The term lineage refers to the search order for functions. If you are an expert user or curious about how the Axiom system works, try the following exercise. Otherwise, you best skip this button and go on to Clients.
Clicking on Lineage gives you a list of domain constructors: InnerIndexedTwoDimensionalArray, MatrixCategory&, TwoDimensionalArrayCategory&, HomogeneousAggregate&, Aggregate&. What are these constructors and how are they used?
We explain by an example. Suppose you create a matrix using the interpreter, then ask for its rank. Axiom must then find a function implementing the rank operation for matrices. The first place Axiom looks for rank is in the Matrix domain.
If not there, the lineage of Matrix tells Axiom where else to look. Associated with the matrix domain are five other lineage domains. Their order is important. Axiom first searches the first one, InnerIndexedTwoDimensionalArray. If not there, it searches the second MatrixCategory&. And so on.
Where do these lineage constructors come from? The source code for Matrix contains this syntax for the function body of Matrix:InnerIndexedTwoDimensionalArray is a special domain implemented for matrix-like domains to provide efficient implementations of two-dimensional arrays. For example, domains of category TwoDimensionalArrayCategory can have any integer as their . Matrices and other members of this special ``inner'' array have their defined as .
InnerIndexedTwoDimensionalArray(R,mnRow,mnCol,Row,Col)
add ...
where the ``...'' denotes all the code that follows. In English, this means: ``The functions for matrices are defined as those from InnerIndexedTwoDimensionalArray domain augmented by those defined in `...','' where the latter take precedence.
This explains InnerIndexedTwoDimensionalArray. The other names, those with names ending with an ampersand & are default packages for categories to which Matrix belongs. Default packages are ordered by the notion of ``closest ancestor.''
14.2.2.6 Clients
A client of Matrix is any constructor that uses Matrix in its implementation. For example, Complex is a client of Matrix; it exports several operations that take matrices as arguments or return matrices as values.A constructor is a client of Matrix if it handles any matrix. For example, a constructor having internal (unexported) operations dealing with matrices is also a client.
14.2.2.7 Benefactors
A benefactor of Matrix is any constructor that Matrix uses in its implementation. This information, like that for clients, is gathered from run-time structures.The benefactors exclude constructors such as PrimitiveArray whose operations macro-expand and so vanish from sight!
Cross reference pages for categories have some different buttons on them. Starting with the constructor page of Matrix, click on Ring producing its constructor page. Click on Cross Reference, producing the cross-reference page for Ring. Here are buttons Parents and Ancestors similar to the notion for domains, except for categories the relationship between parent and child is defined through category extension.
14.2.2.8 Children
Category hierarchies go both ways. There are children as well as parents. A child can have any number of parents, but always at least one. Every category is therefore a descendant of exactly one category: Object.
14.2.2.9 Descendants
These are children, children of children, and so on.
Category hierarchies are complicated by the fact that categories take parameters. Where a parameterized category fits into a hierarchy may depend on values of its parameters. In general, the set of categories in Axiom forms a directed acyclic graph, that is, a graph with directed arcs and no cycles.
14.2.2.10 Domains
This produces a table of all domain constructors that can possibly be rings (members of category Ring). Some domains are unconditional rings. Others are rings for some parameters and not for others. To find out which, select the conditions button in the views panel. For example, DirectProduct(n, R) is a ring if R is a ring.
14.2.3 Views Of Constructors
Below every constructor table page is a Views panel. As an example, click on Cross Reference from the constructor page of Matrix, then on Benefactors to produce a short table of constructor names.
The Views panel is at the bottom of the page. Two items, names and conditions, are in italics. Others are active buttons. The active buttons are those that give you useful alternative views on this table of constructors. Once you select a view, you notice that the button turns off (becomes italicized) so that you cannot reselect it.
14.2.3.1 names
This view gives you a table of names. Selecting any of these names brings up the constructor page for that constructor.
14.2.3.2 abbrs
This view gives you a table of abbreviations, in the same order as the original constructor names. Abbreviations are in capitals and are limited to 7 characters. They can be used interchangeably with constructor names in input areas.
14.2.3.3 kinds
This view organizes constructor names into the three kinds: categories, domains and packages.
14.2.3.4 files
This view gives a table of file names for the source code of the constructors in alphabetic order after removing duplicates.
14.2.3.5 parameters
This view presents constructors with the arguments. This view of the benefactors of Matrix shows that Matrix uses as many as five different List domains in its implementation.
14.2.3.6 filter
This button is used to refine the list of names or abbreviations. Starting with the names view, enter m* into the input area and click on filter. You then get a shorter table with only the names beginning with m.
14.2.3.7 documentation
This gives you documentation for each of the constructors.
14.2.3.8 conditions
This page organizes the constructors according to predicates. The view is not available for your example page since all constructors are unconditional. For a table with conditions, return to the Cross Reference page for Matrix, click on Ancestors, then on conditions in the view panel. This page shows you that CoercibleTo(OutputForm) and SetCategory are ancestors of Matrix(R) only if R belongs to category SetCategory.
14.2.4 Giving Parameters to Constructors
Notice the input area at the bottom of the constructor page. If you leave this blank, then the information you get is for the domain constructor Matrix(R), that is, Matrix for an arbitrary underlying domain R.
In general, however, the exports and other information do usually depend on the actual value of R. For example, Matrix exports the inverse operation only if the domain R is a Field. To see this, try this from the main constructor page:
- Enter Integer into the input area at the bottom of the page.
- Click on Operations, producing a table of operations. Note the number of operation names that appear at the top of the page.
- Click on to return to the constructor page.
- Use the Delete or Backspace keys to erase Integer from the input area.
- Click on Operations to produce a new table of operations. Look at the number of operations you get. This number is greater than what you had before. Find, for example, the operation inverse.
- Click on inverse to produce a page describing the operation inverse. At the bottom of the description, you notice that the Conditions line says ``R has Field.'' This operation is not exported by Matrix(Integer) since Integer is not a field. Try putting the name of a domain such as Fraction Integer (which is a field) into the input area, then clicking on Operations. As you see, the operation inverse is exported.
14.3 Miscellaneous Features of Browse
14.3.1 The Description Page for Operations
From the constructor page of Matrix, click on Operations to bring up the table of operations for Matrix.
Find the operation inverse in the table and click on it. This takes you to a page showing the documentation for this operation.
Here is the significance of the headings you see.
14.3.1.1 Arguments
This lists each of the arguments of the operation in turn, paraphrasing the signature of the operation. As for signatures, a $ is used to designate this domain, that is, Matrix(R).
14.3.1.2 Returns
This describes the return value for the operation, analogous to the Arguments part.
14.3.1.3 Origin
This tells you which domain or category explicitly exports the operation. In this example, the domain itself is the Origin.
14.3.1.4 Conditions
This tells you that the operation is exported by Matrix(R) only if ``R has Field,'' that is, ``R is a member of category Field.'' When no Conditions part is given, the operation is exported for all values of R.
14.3.1.5 Description
Here are the ++ comments that appear in the source code of its Origin, here Matrix. You find these comments in the source code for Matrix.
Click on to return to the table of operations.
Click on map.
Here you find three different operations named map.
This should not surprise you.
Operations are identified by name and signature.
There are three operations named map, each with
different signatures.
What you see is the descriptions view of the operations.
If you like, select the button in the heading of one of these
descriptions to get only that operation.
14.3.1.6 Where
This part qualifies domain parameters mentioned in the arguments to the operation.
14.3.2 Views of Operations
We suggest that you go to the constructor page for Matrix and click on Operations to bring up a table of operations with a Views panel at the bottom.
14.3.2.1 names
This view lists the names of the operations. Unlike constructors, however, there may be several operations with the same name. The heading for the page tells you the number of unique names and the number of distinct operations when these numbers are different.
14.3.2.2 filter
As for constructors, you can use this button to cut down the list of operations you are looking at. Enter, for example, m* into the input area to the right of filter then click on filter. As usual, any logical expression is permitted. For example, use
*! or *?
to get a list of destructive operations and predicates.
14.3.2.3 documentation
This gives you the most information: a detailed description of all the operations in the form you have seen before. Every other button summarizes these operations in some form.
14.3.2.4 signatures
This views the operations by showing their signatures.
14.3.2.5 parameters
This views the operations by their distinct syntactic forms with parameters.
14.3.2.6 origins
This organizes the operations according to the constructor that explicitly exports them.
14.3.2.7 conditions
This view organizes the operations into conditional and unconditional operations.
14.3.2.8 usage
This button is only available if your user-level is set to user-level development. The usage button produces a table of constructors that reference this operation.Axiom requires an especially long time to produce this table, so anticipate this when requesting this information.
14.3.2.9 implementation
This button is only available if your user-level is set to development. user-level If you enter values for all domain parameters on the constructor page, then the implementation button appears in place of the conditions button. This button tells you what domains or packages actually implement the various operations.This button often takes a long time; expect a delay while you wait for an answer.
With your user-level set to development, we suggest you try this exercise. Return to the main constructor page for Matrix, then enter Integer into the input area at the bottom as the value of R. Then click on Operations to produce a table of operations. Note that the conditions part of the Views table is replaced by implementation. Click on implementation. After some delay, you get a page describing what implements each of the matrix operations, organized by the various domains and packages.
14.3.2.10 generalize
This button only appears for an operation page of a constructor involving a unique operation name.
From an operations page for Matrix, select any operation name, say rank. In the views panel, the filter button is replaced by generalize. Click on it! What you get is a description of all Axiom operations named rank.If there were more than 10 operations of the name, you get instead a page with a Views panel at the bottom and the message to Select a view below. To get the descriptions of all these operations as mentioned above, select the description button.
14.3.2.11 all domains
This button only appears on an operation page resulting from a search from the front page of Browse or from selecting generalize from an operation page for a constructor.
Note that the filter button in the Views panel is replaced by all domains. Click on it to produce a table of all domains or packages that export a rank operation.
We note that this table specifically refers to all the rank operations shown in the preceding page. Return to the descriptions of all the rank operations and select one of them by clicking on the button in its heading. Select all domains. As you see, you have a smaller table of constructors. When there is only one constructor, you get the constructor page for that constructor.
14.3.3 Capitalization Convention
When entering search keys for constructors, you can use capital letters to search for abbreviations. For example, enter UTS into the input area and click on Constructors. Up comes a page describing UnivariateTaylorSeries whose abbreviation is UTS.
Constructor abbreviations always have three or more capital letters. For short constructor names (six letters or less), abbreviations are not generally helpful as their abbreviation is typically the constructor name in capitals. For example, the abbreviation for Matrix is MATRIX.
Abbreviations can also contain numbers. For example, POLY2 is the abbreviation for constructor PolynomialFunctions2. For default packages, the abbreviation is the same as the abbreviation for the corresponding category with the ``&'' replaced by ``-''. For example, for the category default package MatrixCategory& the abbreviation is MATCAT- since the corresponding category MatrixCategory has abbreviation MATCAT.