Suggestions for NAPI and utilities

Tanya Maria Riseman tmr at thsun7.ph.bham.ac.uk
Mon Mar 26 18:44:38 BST 2001


DKA300:[TANYA.TEX.DATAFORMATS]nexus2001_napi_suggest.txt

 Suggestions for the NAPI and Utilities, 
 from Tanya Riseman tmr at th.ph.bham.ac.uk.

	Sorry if my notation is a bit random. Please understand what I mean, 
 not what I say exactly. I apologize for not spell checking; I lost my spell
 checker in a disk crash.

========================================================================
NXget_slab() and NXput_slab()
 	I'm not sure of the current definition nor its flexibility.

	Say one has 3-D data NXdata mydata(1:K,1:N,1:M). Perhaps one would
	like to read/store parts of it in a different rank order than is
	natural from the construction of the data. Is this currently possible?

	For example, 
	NXget_slab( handle, pointer, start=1, size=N, K=3,1:N, M=102)
	i.e. sort of...  pointer :== &mydata(3,1:N,102).
	where the pointer is to an array of size (1:N).

========================================================================
	For HDF5 version with file "mounts" (links to groups in external files
 rather than for groups within the files):

NXUtar_ball
	Tar ball utility (maybe with optional compression with gnuzip).
	Which collects a series of NeXus files, plus (optionally) the files 
	referred to by the file "mounts" into a UNIX-style tar file. 
	The idea is that the "mounted" files don't get separated from
	the original NeXus file and get forgotten when FTPing.
	Should maintain the directory tree structure.
	(Otherwise, calibration runs will almost always be forgotten
	as they are now.)

NXU_CD_image
	Which collects a series of NeXus files, plus (optionally) the files 
	referred to by the file "mounts" into a cdimage, ready to burn onto 
	an ISO-standard CDrom. If it won't all fit onto one CD,
	then several CDimages would be made, each (optionally) self-contained
	i.e. containing all files referred to by "mounts". 
	Don't split any NeXus files between CDroms unless the files are larger
        than 1 CD. The idea is that the "mounted" files won't get separated from
	the original NeXus file and get forgotten when archiving onto CDrom.
	It would be nice if the CD label (NeXus), author, copywrite, etc.
	information for the CD was also automatically generated,
	containing local information like the facility, beamline, 
	run number range, the date that the data taken and the date CDrom 
	was burnt. (Many users like the idea of being handed their data on CD
	and being able to use it as a archive as well as an alternative
	to FTPing. Hopefully, this utility would automate the process
	for the instrument scientists and potentially make it easy enough
	for the users to do it themselves.)
 
NXU_DVD_image
	Same thing as NXU_CD_image but for DVD, assuming that there is a 
        standard. Otherwise call it something like NXU_DVD_Sony_image, 
        to reflect the manufacturer.

========================================================================

Issue: maintaining "mounted" file links when moving NeXus files about.
(My apologies if these issues have already been addressed.)

	Will mounted files be stored as relative (better) or absolute (horrible)
 directory paths as part of the name, if the mounted files are not in the
 same directory? I don't want "treated" data in the same directory
 as the raw data. I might even put them in different directories
 when I copy them to another computer. I might move them anyway,
 when I reorganize my computer account. I might want to keep my calibration
 run in one directory and then sort my data into several directories
 based on the sample.

	If NeXus with HDF 5 uses mounted files, are we going to require
 the SAME unchanging relative directory tree on the data aquisition computer
 and the users computer? If not, how are you going to update broken
 "mount" file links?

	Maybe need a utility 
 NXUmove(currentname, newpath) 	(like unix mv or VMS move)
 NXUcopy(currentname, newpath) 	(like unix cp or VMS copy)
 e.g. NXUmove(~/download/run444.nxl, /usr/local/PSI/PIM3) 
 
 Also need a rename utility (like unix mv or VMS move)
 NXUmove(currentname, newname) 	(like unix mv or VMS move)
 NXUcopy(currentname, newname) 	(like unix cp or VMS copy)
 e.g. NXUmove(~/download/run444.nxl, /usr/local/PSI/PIM3/444.nxl) 

	Question: What happens to files which have a mount link to the 
 file that was moved?

	Need 
 NXUshow_mounts_child(filename(s))
	Shows all mounted files within the NeXus file filename.

 NXUshow_mounts_parent(filename(s))
	Shows all names of the NeXus files which have mount links
 	to the file named filename. 

 Maybe need to do something like
 NXU_map_mounts(some files)
	 	(put into a file map_mounts.nxl and/or memory)
 NXUmove(a_few_files, newpath)  	
		(record movements in temporay map_mounts.nxl)
 NXUmove(some_more_files, newpath)  
		(record movements in temporary file map_mounts.nxl)
 NXU_repare_mounts()
		 (use the info in the file to fix the
		  mounts in the files that have been made).

	I guess NXU_map_mounts and NXU_repare_mounts should be folded
 into NXUmove. 

	Worry: Is there a backup version of the data file created automatically 
 before you edit or add information (like NXsample) or update "mount" 
 information, in case there is a problem writing the file out at the end?
 I would be particularly concerned with the very large files, especially
 given the reported problems with flushing data and closing files.

	
========================================================================

	Please provide double links and double "mounted" files so that you can
 see both ends of the link and easily go up to to the parent as well as 
 down to the child. Still maintain the idea of the direction of the link.
 (Sort of like the game chutes and ladders.)

	 On second thought, raw data should probably not have any "mount"
 information about analysis files (that encourages turf wars and increases the 
 chances that the original data might get corrupted). In that case, in a chain
 of data reduction analysis files, the files which are the least treated
 should only have a one-way "mount" link to the raw data. 

========================================================================

	Add NXspin_rotator (for muon spin rotators and separators) 
 under NXinstrument for muSR. Muons are 100% polarized and
 the spin rotator rotated the spin from antiparallel to the momentum
 towards perpendicular (anywhere from 15 degrees to 90 degrees.)
 This is similar to NXspin_flipper, as used in neutron scattering.

========================================================================

	Add group NXcomments (an array of strings)

========================================================================

	Add arrays of names for the dectors, which is useful for
 instruments with only a few detectors (like "up" "down", "left", "right"
 and "cup_veto") used in muSR. This is particularly useful for 
 beamlines where the detectors are frequently re-configured. 

========================================================================

	Add a new data type "3vector" which will be 
 		(value, value, value) 
 where value can be integer, real or double and there is 
 a units= attribute and a coord_system= attribute.
 The coordinate system attribute options would be 
	coord_system= "cartesian"				(x,y,z)
			"cylindrical",  "cylindrical_degrees"	(r, theta, z)
			"spherical", 	"spherical_degrees"	(theta, phi, r)
 The default for angle will be radians.
 One could also use a link origin_link which would link to another 3vector, 
 definining the origin for 3vectors used as orientation vectors.

 Example 
 Magnetic field at the sample

			x   y  z
	muon_position = (0, 0, 0) 
		units="cm"
		coord_system= "cartesian"
		origin_link=null 

			x   y  z
	muon_Bfield = (100, 0, 0) 
		units="Gauss"
		coord_system= "cartesian"
		origin_link=muon_position

				 r theta  z
	muon_polarization =      (1,  45, 0)
		units="Fraction"
		coord_system= "cylindrical"
		origin_link=muon_positon

		What would be the units=? "norm"? for 1? 
		Fraction if only 95% polarized (0.95, 45, 0, "cylindrical").
		"fraction" and "norm" does not exist in the udunits.dat file!


 Needed utilities: something like
 ================
 NXUget_3vector(handle, pointer, coord_system_string, name)
 	Pointer return with (value, value, value)

 NXUput_3vector(handle, pointer, coord_system_string, name)
 
 NXUchange_coord_style_3vector(handle, pointer, new_coord_system, name)
    example 
	Bfield = (70.7, 70.7, 0) 	coord_system="cartesian"
	NXUchange_coord_style_3vector(handle, pointer, "cylindrical",Bfield)
	will return a vector (100, 45, 0).

 NXUchange_origin(handle, pointer, new_coord_system, name, new_origin)
 NXUremove_origin(handle, pointer, new_coord_system, name, old_origin)

 NXU_dot_product(handle, pointer, new_coord_system, name1, name2) ?
 NXU_cross_product(handle, pointer, new_coord_system, name1, name2)? 

 NXU_3vector_operator(handle,pointer,new_coord_system,name1,"operation", name2)
	where name1 and name2 are scalars or 3vectors or one of each.
	(too much overloading of the utility?)
	 "add" 			or "+"
	 "vector_add" 		or "+"
	 "subtract"	 	or "-"
	 "vector_subtract" 	or "-."
	 "multiply"	 	or "*"
	 "vector_multiply" 	or "*."		Like octave?
	 "divide" 		or "/"
	 "vector_divide" 	or "/."
	 "exponentiation"	or "^"
	 "dot"			or "<>" or "." ??	
	 "cross"		or "><"	??
		I can't remember what Octave uses for dot or cross product.
	

 NXU_determinent(handle, scalar, name1, name2, name3)? 

========================================================================
	Some reasonable unit-less "units" doesn't exist in udunits.dat file.
 What would be the units="norm" for unit vectors (length 1)?
 How about units="fraction" for polarization, so that if
 the probe is only 95% polarized:
	 muon_polarization =(0.95, 45, 0) coord_system=, "cylindrical".

	"fraction" and "norm" does not exist in the udunits.dat file!
 I guess one needs extra units! The closest the table has is "bit"
 for "non-base units of fundamental quantities", whatever that means.


---
  Dr. Tanya Riseman
  School of Physics and Astronomy	phone 44-121-414-7322
  University of Birmingham		fax   44-121-414-4719
  Birmingham B15 2TT, United Kingdom	email: tmr at th.ph.bham.ac.uk





More information about the NeXus mailing list