The acol Command Line Utility ============================= :ref:`O2scl ` acol contents ------------- - :ref:`acol introduction` - :ref:`acol types` - :ref:`Value specifications` - :ref:`Function specifications` - :ref:`Vector specifications` - :ref:`String list specifications` - :ref:`Multiple vector specifications` - :ref:`acol example` acol introduction ----------------- O₂scl contains a command line utility, acol, designed to facilitate the manipulation of various objects stored in HDF5 files. It can handle integers, characters, double-precision floating point numbers, size_t objects, arrays of any of these types, or O₂scl objects of selected types. ``acol`` can only operate with one object at a time. The basic workflow is: - create an object or read it from an HDF5 file - perform operations on that object - output the object to the screen or write it to an HDF5 file - create or read a new object - ... The available command list can be obtained using ``help`` or ``commands`` and changes depending on what type of object is currently in memory. In order to list the commands which would be available given a particular type, give ``commands`` the type as an argument, i.e. ``acol -commands table`` . In order to get detailed help on how a command operates on a particular type, give the type and the command as arguments to help, e.g. ``acol -help table interp``. There are some commands which are available for all types, and obtaining the help information for these commands does not require a type argument, i.e. ``acol -commands`` or ``acol -help read``. ``acol`` can sometimes, but not always read and write HDF5 files generated outside of O₂scl. ``acol`` has a command, ``run``, which allows you to run a set of commands which are given in a separate file. An example script in the ``extras`` directory of the documentation is named ``acol.scr``. The associated output is a useful demonstration of the capabilities of ``acol``. acol types ---------- The types which can be handled by ``acol`` are either C++ standard types or O₂scl types. The standard types which acol can manipulate are ``char, double, double[], int, int[], size_t, size_t[], std::string``, ``string[]``, ``vector>`` (shortened to ``vec_vec_double``), and ``vector>`` (shortened to ``vec_vec_string``). The relevant O₂scl types are :ref:`hist `, :ref:`hist_2d `, :ref:`prob_dens_mdim_amr `, :ref:`prob_dens_mdim_gaussian `, :ref:`table `, :ref:`table3d `, :ref:`tensor ` (including ``double``, ``int``, and ``size_t`` versions), :ref:`tensor_grid ` :ref:`uniform_grid `, and vector<:ref:`contour_line `>. Value specifications -------------------- Some acol commands take "value specifications" as arguments, which are string expressions which represent a fixed numerical value. These specifications are handled by :cpp:func:`o2scl_hdf::value_spec()`. The first part of the specification is a "type of specification" followed by a colon, followed by arguments which depend on the type. If no colon is present, then a "func:" prefix is assumed. The different types for a value specification are: 1. ```` - Value equal to the result of , e.g. "7.6" or "sin(0.5)". See :ref:`Function specifications` for a list of functions that can be used. 2. ``hdf5:

Selected row and columns uniform_grid (none) ==================== ======================== ======================= For table , the first additional specification is a row number, which can be negative to refer to counting from the end of the table. The second additional specification is a pattern of column names using either '*' or '?'. Index specifications -------------------- The tensor rearrange commands use index specifications to specify how the tensor should be rearranged. Index specifications may be specified as separate arguments e.g. "index(1)" "fixed(2,10)" or multiple index specifications may be given in a single argument separated by spaces or commas, e.g. "index(1) fixed(2,10)" or "index(1),fixed(2,10)". The indices begin with 0, the first index so that index 1 is the second index. The list of index specification is: - index(ix): Retain index ix in the new tensor. - fixed(ix): Fix the value of index ix. - sum(ix): Sum over the value of index ix - trace(ix1,ix2): Trace (sum) over indices ix and ix2. If the number of entries in either index is smaller than the other, then the remaining entries are ignored in the sum. - reverse(ix): Retain index ix but reverse the order. - range(ix,start,end): Retain index ix but modify range. Ranges include both of their endpoints. - interp(ix,value) (for tensor_grid): fix index ix by interpolating 'value' into the grid for index ix. - grid(ix,begin,end,n_bins,log) (for tensor_grid): interpolate the specified index on a grid to create a new index. If the value of log is 1, then the grid is logarithmic. - gridw(ix,begin,end,bin_width,log) (for tensor_grid): interpolate the specified index on a grid with a fixed bin width to create a new index. If the value of log is 1, then the grid is logarithmic and the bin_width is the multiplicative factor between bin edges. Note that the index specifications which result in a tensor index (all except 'fixed', 'sum', 'trace' and 'interp') must be given in the order they should appear in the tensor which results. Also, the 'rearrange' commands require that the result of the rearrangement must have at least one index left. Examples: index(1),index(0) - take the transpose of a rank 2 tensor (i.e. a matrix) index(1),fixed(2,0),index(0) - fix the value of index 2 (i.e. the third index) to zero and transpose the other two indices\n\n fixed(2,0),index(1),index(0) - same as above\n\n"; String list specifications -------------------------- Some acol commands take "string list specifications" as arguments, which are string expressions which represent a list of strings. These specifications are handled by :cpp:func:`o2scl_hdf::strings_spec()`. The different parts of the string are separated by a colon, and the first part specifes the type of vector specification. The different types are: 1. ``list:`` - A list of strings 2. ``shell:`` - The lines obtained from the result of a shell command, with a maximum of 256 characters per line. 3. ``pattern:N:x[0][a][A]`` - The N strings obtained from a pattern. Occurrences of [0] are replaced with the integer 'i' where i runs from 0 to N-1. Occurrences of [a] are replaced with 'a' through 'z' from 0 through 25, and 'aa' through 'zz' for i from 26 to 701. Occurrences of [A] are replaced with 'A' through 'Z' from 0 through 25, and 'AA' through 'ZZ' for i from 26 to 701. 4. hdf5: - Unfinished. Multiple vector specifications ------------------------------ Some acol commands take "multiple vector specifications" as arguments, which are string expressions which represent a list of vectors (which need not have the same length). These specifications are handled by :cpp:func:`o2scl_hdf::mult_vector_spec()`. The different parts of the string are separated by a colon, and the first part specifes the type of multiple vector specification. The different types are: 1. ``func:::`` - Specify the number of vectors, a function of "i" which determines the length of the ith vector, and a function of "i" and "j" which specifies the jth element of the ith vector. 2. ``text::`` - Read one or more text files and extract vectors of numbers from columns of the text file, ignoring any header rows which contain non-numeric values. For example 'text:~/temp.dat:2-4' will construct vectors from the third, fourth, and fifth columns of the file 'temp.dat' in the user's home directory. 3. ``hdf5::