Extended IDL Help

  • Return to IDL Topics

    Last modified: Tue Aug 7 08:53:41 2007.


    List of Routines


    Routine Descriptions

    CLOSEEXO

    [Next Routine] [List of Routines]
       Close a Exodus file. If the current file is closed, the current file pointer
       will be set the last file in the showexo file listing.
       format:   CLOSEEXO [, fileid]
       where:
          fileid    - file id of the file to be closed
                      If it is omitted, the current file is closed.
                      If it is zero or 'all', then all files will be closed.
       Example:
          Close the current file.
             closeexo
    
          Close the file with a file id of 3
             closeexo, 3
    
          Close all files
             closeexo, 0
         closepff, 'all'
    
           Written by:     L. P. Mix, October 10, 2005
    

    (See ../pfidl/exodus/closeexo.pro)


    DIREXO

    [Previous Routine] [Next Routine] [List of Routines]
    
         This routine prints a directory of Exodus II files and optionally returns
           the values of the directory information in keyword arguements.
    
         DIREXO [, P1] [, Page = Page] [, NDSET = ndset]
             [, TRUNCATE = truncate] [, FILEID= fileid]
             [, Reset = reset]  [, Xsize = xsize] [, /print] [, /quiet]
             [, FILENAME = filename] [, COMMENT = comment] [, LINE = line] 
             [, LOC = loc]
         where:
               P1       - an optional search string.
                          For example: To get all datasets with 'TEMP' use:
                            direxo, 'temp' 
                          See GET_MATCH for allowed wild cards.
               PAGE     - the number of lines on the directory
                          default is 24
               RESET    - present and not zero, resets the directory
                          use this if the window has been closed
                      Note: If the window is still open and you wish to leave it
                            open, use /reset to put the current command in a second 
                            window.
                      NOTE: By using the reset qualifier, a window can be 
                            opened for each file with the filename at the top.
               NDSET    - the number of datasets returned 
                          For EXODUS II data NDSET has 3 elements for 
                            global, nodal and cell based data.
               XSIZE    - the width of the window in pixels (generally not set)
               TRUNCATE - if set, the dataset comments will be truncated at ' - '
                          This is a toggle; If not specified the last value will
                          be used.  Default value =0 -- no truncate
               PRINT    - If set, directory will be sent to terminal
               QUIET    - If set, no outputs unless an error. 
              FILENAME  - Name of the Exodus II file
              COMMENT   - Dataset comment for each of the datasets
              LOC       - Pointer into COMMENT for each of the dataset types.
                          For EXODUS II data.
                    Example:
                          If ndset(0) gt 0, then global data exists and the 
                          comments are given by 
                             global_comments= comment(loc(0):loc(1)-1)
                          If ndset(1) gt 0, then node data exists and the 
                          comments are given by 
                             Node_comments= comment(loc(1):loc(2)-1)
                          If ndset(2) gt 0, then cell or element data exists and the 
                          comments are given by 
                             Cell_comments= comment(loc(2):loc(3)-1)
                           
         Example:
             Get a directory of the current exodus file and the number of datasets.
               direxo, ndset = ndset
             Get a directory of the current file and the exo file with id = 3
               with an additional window for this widget 
               (to see two different files simultaneously)
               direxo & direxo, 3, /reset
             Print a directory of current file to the terminal
               direxo, /p
    
      Written by:     L. P. Mix, October 7, 2005
    

    (See ../pfidl/exodus/direxo.pro)


    GET_ELEM

    [Previous Routine] [Next Routine] [List of Routines]
     NAME:
           GET_ELEM
    
     PURPOSE:
           This function returns the element number(s) for elements closest to a point.
    
     CALLING SEQUENCE:
    
           ELEM = GET_ELEM(POSITION [, TIME])
    
     OUTPUT:
           ELEM:   Element or cell numbers from the file.
                   ELEM equal -1 if no element information is available.
                   Nodes are numbered from 1 to NUM_ELEM.
    
     INPUTS:
           POSITION: Spatial position where closest element is requested.
                     Element position is the average position of the nodes that
                     form the element.
           TIME:     Optional input to specify a time other than the first time.
                     The position at initial time is stored in a common block 
                     and is much faster to access.  If INDEX is set, TIME is the 
                     time step which must be in the range 1 to N_TIMES.
    
     KEYWORD PARAMETERS:
           INDEX:  If set, TIME is the time index from 1 to N_TIMES.
           VALUES: Actual spatial position of the element(s) returned.
                   Values = [Num_elements, ndim]
           NELEM:  Number of elements returned.
                   Default is 1 - Closest Node to Position.
           RADIUS:	If present and not zero, this specifies a radius for finding
                   elements.  All elements with a position less than RADIUS from 
                   POSITION are returned.
           TETS:   If present, tets associated with each element are returned.
                   Size is [4, num_elements]  If some elements are not tets, this
                   request will return -1.
           The following are ignored if RADIUS is set.
           XDelta: Range of X-values to use in returning elements.
                   Values returned have X such that:
                   POSITION[0]-0.5*Xdelta LE X LE POSITION[0]+0.5*Xdelta
           YDelta: Range of Y-values to use in returning elements.
                   Values returned have Y such that:
                   POSITION[0]-0.5*Ydelta LE Y LE POSITION[0]+0.5*Ydelta
           ZDelta: Range of Z-values to use in returning elements.
                   Values returned have Z such that:
                   POSITION[0]-0.5*Zdelta LE Z LE POSITION[0]+0.5*Zdelta
    
     RESTRICTIONS:
           Current Exodus II file is searched.  Use SETEXO to set desired file.
    
     EXAMPLE:
           Find the element number and true position (val) of the element closest to 
           the location: [.1, .2, .1].  Save the element in NN.
             nn = GET_ELEM( [.1, .2, .1], value = val )
    
           Find the element number and true position (val) of the element closest to 
           the location: [.1, .2, .1] at a time of 100e-9.  Save the element in N100.
             n100 = GET_ELEM( [.1, .2, .1], 100.0e-9, value = val )
           Note:  No interpolation is done.  Time closest to 100e-9 us used.
    
           Find the element numbers and true position (val) of the element within 5 cm of 
           the location: [.1, .2, .1] at a time of 100e-9.  Save the element in N05.
             n05 = GET_ELEM( [.1, .2, .1], 100.0e-9 , r= 0.05, val = val)
    
           Find the element numbers and true position (val) of the element within 5 cm of 
           the location: x = 0.1 at a the initial time.  Store the numbers in xp1
             xp1 = GET_ELEM( [.1, 0, 0], x= 0.05, val= val)
    
     MODIFICATION HISTORY:
     	Written by:	L. P. Mix, October 6, 2005
    
    

    (See ../pfidl/exodus/get_elem.pro)


    GET_EXOTIMES

    [Previous Routine] [Next Routine] [List of Routines]
     NAME:
           Get_ExoTimes
    
     PURPOSE:
    	Return the time values for the current ExodusII file
           File must be opened with OPENEXO.
    
     CATEGORY:
           Utility
    
     CALLING SEQUENCE:
           TIMES = GET_EXOTIMES([INDEX])
    
    
     INPUTS:
           INDEX:  Optional index array with values from 1 to the number of times.
                     Invalid values will be ignored
                   Default: INDEX = UNDEFINED ; All times are returnded
                   Index is an integer.
    
     OUTPUTS:
           Time values for the current ExodusII file
    
     COMMON BLOCKS:
           This routine accesses the common in the file: exoduscom.dat
    
     EXAMPLE:
           Get the times for the current ExodusII file.
             Times = get_exotimes()
    
           Get the first 100 odd times from a simulation and store in T_odd.
             T_odd = get_exotimes(indgen(100)*2+1)
    
     MODIFICATION HISTORY:
     	Written by:	L. P. Mix, October 4, 2005
    

    (See ../pfidl/exodus/get_exotimes.pro)


    GET_NODES

    [Previous Routine] [Next Routine] [List of Routines]
     NAME:
           GET_NODES
    
     PURPOSE:
           This function returns the node number(s) for nodes closest to a point.
    
     CALLING SEQUENCE:
    
           NODES = GET_NODES(POSITION [, TIME])
    
     OUTPUT:
           NODES:  Node numbers from the file.  NODES equal -1 if no nodes available.
                   Nodes are numbered from 1 to NUM_NODES.
    
     INPUTS:
           POSITION: Spatial position where closest node is requested.
           TIME:     Optional input to specify a time other than the first time.
                     The position at initial time is stored in a common block 
                     and is much faster to access.  If INDEX is set, TIME is the 
                     time step which must be in the range 1 to N_TIMES.
    
     KEYWORD PARAMETERS:
           INDEX:  If set, TIME is the time index from 1 to N_TIMES.
           VALUES: Actual spatial position of the node(s) returned.
                   Size is [Num_nodes, ndim]
           NNODES: Number of Nodes returned.
                   Default is 1 - Closest Node to Position.
           RADIUS:	If present and not zero, this specifies a radius for finding
                   nodes.  All nodes with a position less than RADIUS from 
                   POSITION are returned.
           The following are ignored if RADIUS is set.
           XDelta: Range of X-values to use in returning nodes.
                   Values returned have X such that:
                   POSITION[0]-0.5*Xdelta LE X LE POSITION[0]+0.5*Xdelta
           YDelta: Range of Y-values to use in returning nodes.
                   Values returned have Y such that:
                   POSITION[0]-0.5*Ydelta LE Y LE POSITION[0]+0.5*Ydelta
           ZDelta: Range of Z-values to use in returning nodes.
                   Values returned have Z such that:
                   POSITION[0]-0.5*Zdelta LE Z LE POSITION[0]+0.5*Zdelta
    
     RESTRICTIONS:
           Current Exodus II file is searched.  Use SETEXO to set desired file.
    
     EXAMPLE:
           Find the node number and true position (val) of the node closest to 
           the location: [.1, .2, .1].  Save the node in NN.
             nn = GET_NODES( [.1, .2, .1], value = val )
    
           Find the node number and true position (val) of the node closest to 
           the location: [.1, .2, .1] at a time of 100e-9.  Save the node in N100.
             n100 = GET_NODES( [.1, .2, .1], 100.0e-9, value = val )
           Note:  No interpolation is done.  Time closest to 100e-9 us used.
    
           Find the node numbers and true position (val) of the node within 5 cm of 
           the location: [.1, .2, .1] at a time of 100e-9.  Save the nodes in N05.
             n05 = GET_NODES( [.1, .2, .1], 100.0e-9 , r= 0.05, val = val)
    
           Find the node numbers and true position (val) of the nodes within 5 cm of 
           the location: x = 0.1 at a the initial time.  Store the numbers in xp1
             xp1 = GET_NODES( [.1, 0, 0], x= 0.05, val= val)
    
     MODIFICATION HISTORY:
     	Written by:	L. P. Mix, October 6, 2005
    
    

    (See ../pfidl/exodus/get_nodes.pro)


    OPENEXO

    [Previous Routine] [Next Routine] [List of Routines]
      Open a Exodus file.  The current file pointer is set to this file id.
      format: OPENEXO [, File] [, Fileid ] [, NDSET =ndset] [, WRITE = write]
                      [, PATH = path] [, FILTER = filter] [, HELP = help]
                      [, FILEID = fileid] [, QUIET = quiet] [, /VERBOSE]
      where:
        File   - Name of the Exodus file to be opened.  If file is zero, 
                   Dialog_Pickfile will be used to obtain the file.
                 The default file extension is ".exo". 
                 If file is omitted or undefined, PICKFILE will be used to select
                 a file. The initial path in PICKFILE is the current directory or
                 the PATH to the last file selected.
                 NOTE: PATH and FILTER may be used to set the initial path and
                       filter for PICKFILE.
                 NOTE: FULFNAM procedure is used to handle environment variables
                       See FULFNAM for details
        FileID - user specified file id 
                 If fileid is specified, it will be used as the file id.  If 
                 fileid is not provided or is zero, a value will be 
                 provided; default value is the first unused integer greater
                 than 0.  If fileid is provided but has been used for another 
                 file the program will inform the user and terminate.
        WRITE  - Set to open the file for both read and write
        HELP   - Print a help text
        PATH   - Path to the current file 
                 Default is the current directory in the first call to OPENEXO
                 but the default path is changed to the final path selected is 
                 retained as the default in the next call to OPENEXO.
        FILTER - File filter - The default may be set in USERQSINIT; if undefined
                 the default is '*'.  The default filter is set only with
                  USERQSINIT or SETDEFAULT.
                  USERQSINIT or SETDEFAULT.
        NDSET  - Number of datasets 
                 For Exodus II: Array of [# of global, # of node, # of cell]
                 For WDF array: Number of WDF arrays
        QUIET  - Only print error messages
        VERBOSE- Print file information
    
      Examples:
        Open a Exodus file with the default file id
          openexo
        Open a Exodus file, 'users/test', with the default file id
          openpff, '/users/test'
        Open a file to be selected from a menu with a file id of 14
          OPENEXO, '', 14
      or  OPENEXO, 0, 14
        Get help
          OPENEXO, /h
    

    (See ../pfidl/exodus/openexo.pro)


    READEXO

    [Previous Routine] [Next Routine] [List of Routines]
      Name: READEXO
    
      Purpose:
            Reads a Exodus dataset into a PFIDL structure or WDF array.
          Note: Cell or element data can be left as element or cell data.
                Default is it convert element data to node data.
    
      Format:
    
        READEXO, STRUCTURE, [ DATASET,] TVALUE [, /INDEX] [, IERROR = ierror]
                         [, TIME_INDEX = time_index] [, /GRID] [, CLABEL = clab]
                         [, ONEDIM = onedim] [, /CELL_VALUES] [, RZ_ONE = rz_one]
                         [, RECTILINEAR = rectilinear] [, /STRUCTURE_ONLY]
                         [, EPSILON = epsilon] [, VECTOR = vector]
    
      where:
        STRUCTURE - Structure array number for structure data.
                    WDF array number for pseudo-1D data if ONEDIM is set.
        NOTE: Dataset must be provided unless grid is set.
        DATASET   - indicates a Exodus dataset name or a search string for dataset
                    names or a Exodus dataset number.  Only node and cell data may be read.
                    DATASET numbers are number shown in DIREXO.
                    DATASET must be omitted if GRID is set.
                      Format: READEXO, TVALUE, /GRID, ....
                    Use REEXO to read data at one node for all times.
                    If GRID is set, must contain the TVALUE.
               See: GET_DSET (in PFIDL_1D) for more details of the search.
                    IF DATASET is an array or VECTOR is set, the square root of the sum
                    of the squares will be stored.
        TVALUE    - Time for the data.  If INDEX is set this is an index number.
                    Valid index numbers are 1 to number of time values.
                    The closest time is returned; no interpolation is performed.
                    If GRID is set and DISPLX, DISPLY, DISPLZ are missing, then
                    TVALUE is ignored.
              Note: To obtain the node/element value vs time at one node, use REEXO
        INDEX     - If INDEX is set then TVALUE goes from 1 to the maximum number of
                    times.
        IERROR    - Returned 0 if no error and valid data
        TIME_INDEX- This is returned with the time value index from 1 to the number
                    Times.  The actual time is given by TIME = (GET_TIME())[Time_index -1]
        GRID      - If set, a node array will be returned.  If DISPLX, DISPLY, DISPLZ
                    are missing, the coordinates are for the first time step.
        CLABEL    - Comment label for the data.  If missing the comment label from 
                    READ_EXO will be used.  The default includes the time and filename.
                    Format: "DATASET, t=time - Filename=filename"
        ONEDIM    - If set and the data is two-dimensional cell data, the data will be 
                    put into a wdf array and stored in wdfarray, structure.  
                    Node data is averaged over top and bottom values.
                    Element data is put at the cell center.
              Note: ONEDIM is ignored if number of dimensions is gt 2.
    
        CELL_VALUES - If set, element or cell data will be returned with the cell
                    centers.  Default - Move cell data to the nodes for finite
                    element data and leave at the cells for rectilinear data; ie 
                    Default value: Cell_Values = (RZ_One || Rectilinear)
        RZ_One    - If set, assume a one dimensional one cylindrical dataset.
                    If RZ_ONE = 1 store the data as R vs Z
                    The radius will be averaged between the top and bottom of each cell
                    Data is assumed to lie in planes in the R-Z dimension if the number of 
                      node values is equal to the number of Z values times the number of 
                      X values.  For NODE data, the top and bottom nodes are averaged.
                    If the number of node values is less than this product, then the data 
                      is stored as a finite element mesh.
                    No action is taken for grid data
        RECTILINEAR-  NOT CURRENTLY IMPLEMENTED
                    If set, attempt to put the data on a rectilinear grid.
                    Multiple block data will be read as multiple block data
                    If the number of dimensions is 3 then the user should 
                    specify RECTILINEAR =1
                    Default is RECTILINEAR = 0
                    If 3d data has only 1 cell then will be read as 2d degenerate.
        Note: Values are assumed equal if they differ by less than EPSILON
              Only the initial grid is checked.  A Lagrangian problem which starts
              with a rectilinear grid can be read as rectilinear data; the grid
              will be the initial grid for all times.
        Note: A less sensitive of delta_X /xrange < delta may be used if 
              RECTILINEAR = DELTA 
        DOUBLE_PREC - If set, save data as double precision
        EPSILON   - Default error parameter = 1./16384 * datarange
        STRUCTURE_ONLY- If set, a structure will be returned in STRUCTURE
        VECTOR    - If set, multiple dataset values will be expected.  The square 
                    root of the sum of the squares will be stored.
    
      Examples:
        Read dataset 34 into array 33, at time step 5.
          READEXO, 33, 34, 5, /ind
    
        Read dataset with 'KE' into structure array 4, at time = 1.36 ns.
          READEXO, 4, 'KE', 1.36e-9
    
        Read the magnitude of the magnetic field into structure 5 at time step 5.
          READEXO, 5, '^B_', 5, /index, /vector
    
      MODIFICATION HISTORY:
           Written by:     L. P. Mix, November 4, 2005
           March 14, 2006  Added keyword VECTOR (lpm)
    
    

    (See ../pfidl/exodus/readexo.pro)


    READ_EXO

    [Previous Routine] [Next Routine] [List of Routines]
      Name: READ_EXO
    
      Purpose:
            Reads a Exodus dataset into an IDL array.  
            This is a utility function.
          Note: Cell or element data will be left as element or cell data.
          Note: IDL arrays are returned with RE_EXO for a node or element history
    
      Format: 
    
        DATA = READ_EXO( [ DATASET,] TVALUE [, /INDEX] [, IERROR = ierror]
                         [, TIME_INDEX = time_index] [, /GRID] [, CLABEL = clab]
                         [, NODE = NODE] [, VECTOR = vector] )
    
      where:
        DATA      - IDL array with the requested data array.
        DATASET   - indicates a Exodus dataset name or a search string for dataset
                    names.  Only node and cell data may be read.
                    DATASET numbers are number shown in DIREXO.
                    If GRID is set, must contain the TVALUE.
            See: GET_DSET (PFIDL_1D) for more details of the search.
        TVALUE    - Time for the data.  If INDEX is set this is an index number.
                    Valid index numbers are 1 to number of time values.
                    The closest time is returned; no interpolation is performed.
                    If GRID is set and DISPLX, DISPLY, DISPLZ are missing, then
                    TVALUE is ignored.
        INDEX     - If INDEX is set then TVALUE goes from 1 to the maximum number of
                    times.
        IERROR    - Returned 0 if no error and valid data
        TIME_INDEX- This is returned with the time value index from 1 to the number
                    Times.  The actual time is given by TIME = (GET_TIME())[Time_index -1]
        GRID      - If set, a node array will be returned.  If DISPLX, DISPLY, DISPLZ
                    are missing, the coordinates are for the first time step.
        CLABEL    - Comment label for the data.  It includes the time and filename.
                    Format: "DATASET, t=time - Filename=filename"
        NODE      - Node number or Element number for dataset vs time.
                    If set, a one-dimensional vector is returned.
                    If NODE is a vector with NDIM elements, then the closest element
                    or node will be returned.
                    Actual values are returned in the keywords, NUMBER and POSITION.
    
      Examples:
        Read dataset 34 into array, data, at time step 5.
          data = read_exo( 34, 5, /ind)
    
        Read dataset with 'KE' into array, energy, at time = 1.36 ns.
          energy = read_exo('KE', 1.36e-9)
    
      MODIFICATION HISTORY:
           Written by:     L. P. Mix, October 4, 2005
    
    

    (See ../pfidl/exodus/read_exo.pro)


    REEXO

    [Previous Routine] [Next Routine] [List of Routines]
      Name: REEXO
    
      Purpose:
            Reads a Exodus dataset into a WDF array.  
            This reads global data vs time or the value at a node or cell vs time.
    
      Format: 
    
        REEXO, WDFARRAY, DATASET [, IERROR = ierror] [, NODE = node] [, /ALLDATA]
                  [, NUMBER = number] [, POSITION = position] [, NARRAY = narray]
    
      where:
        WDFARRAY  - WDFarray number for the data
        DATASET   - Dataset number or dataset name 
                    If NODE is not specified, this is a global dataset name or number
                    If NODE is specified, this is a node or element (cell) dataset 
                      name or number.
                    DATASET numbers are number shown in DIREXO
                    If DATASET is a search string equal to '' then all
                    datasets are read.
               See: GET_DSET (in PFIDL_1D) for more details of the search.
        IERROR    - Returned 0 if no error and valid data
        NODE      - This is the node or element (cell) number desired.  Values range
                    from 1 to the total number or may be the coordinates of the node 
                    or cell center.  When reading global variables this is omitted.
        ALLDATA   - If set, all specified data is read.
                    This is only checked with a finite length search string.
        NARRAY    - Number of datasets returned.
    
        NOTE:  The following apply only when NODE is specified.
        NUMBER    - Node number or Element number of the returned data.
        POSITION  - Actual Coordinates of the returned data.
    
      Examples:
        Read global dataset 34 into array 33
          REEXO, 33, 34
    
        Read all dataset with 'KE' into WDF array 4 and following.
          REEXO, 4, 'KE', /ALLDATA
    
        Read DISPLX data from node 967 into wdf array 7
          REEXO, 7, 'DISPLX', node = 967
    
        Read DISPLX data from node at [.1, 2] into wdf array 47
          REEXO, 47, 'DISPLX', node = [.1, 2]
    
      MODIFICATION HISTORY:
           Written by:     L. P. Mix, January 19,  2005
    
    

    (See ../pfidl/exodus/reexo.pro)


    SETEXO

    [Previous Routine] [Next Routine] [List of Routines]
       Set the current file pointer to indicated file.
       Format: SETEXO,  fileid [, /VERBOSE] [, IERROR = ierror]
       where:
          fileid - file id of desired file
          VERBOSE- Keyword, if set, information about data will be printed.
       Note:  If fileid is undefined or is zero, nothing is done.
    
        Example:
       Set the current file pointer to the file with a file id (fid) of 3
          SETEXO, 3
    
       Written by:     L. P. Mix, October 10, 2005
    
    

    (See ../pfidl/exodus/setexo.pro)


    SHOWEXO

    [Previous Routine] [List of Routines]
      Show all opened Exodus files and their file id.
      Indicate the location of the current file pointer.
      The current file id, and arrays of the user file ids and filesnames
        can be received as keywords.
      Format: SHOWCDF [, current = current] [, ufid = ufid]
                  [, filename = filename]  [, NUMBER= number]
      where
             current - user file id of the current file
             ufid    - array of user file id's
             filename- Array of file names corresponding to the ufid's
             number  - number of files open
             full    - Show all information about the file
                       This includes title, type, and the number of datasets
             ndset   - Number of datasets; ndset = ndset(number, 3)
                       where the second index is represents the number of 
                         global/wdf arrays, node arrays, and cell/element arrays
             quiet   - If present and not zero, send no output to terminal
      Example:
      Show the status, including file id, of all opened Exodus files
        SHOWEXO
      
      Get the filenames and user file id's for all open files
      Do not send any output to the terminal
        SHOWEXO, current = cur, ufid=ufid, num= n, filename= filename, /quiet
    
      Written by:     L. P. Mix, October 10, 2005
    

    (See ../pfidl/exodus/showexo.pro)