installer finishing touches

core/examples/pgc/mori-beatwave-pgc.tw

@@ -51,7 +51,7 @@ new hermite gauss for 'pgc'
 }
 
 // ...or we can add extra words in between as desired.
-generate hermite gauss pulse, and a nice one indeed, for 'pgc'
+new hermite gauss pulse, and a nice one indeed, for 'pgc'
 {
 	a = ( 0.56 , 0 , 0 )
 	direction = ( 0 , 0 , 1 )

core/source/definitions.h

@@ -1,5 +1,5 @@
 #ifndef _did_definitions
-#define TW_VERSION_STRING "4.3.0rc"
+#define TW_VERSION_STRING "4.3.0"
 
 /////////////////////////////////////////////////////////////////////
 //                                                                 //

docs/conf.py

@@ -57,7 +57,7 @@
 # The short X.Y version.
 version = '4.3'
 # The full version, including alpha/beta/rc tags.
-release = '4.3.0rc'
+release = '4.3.0'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.

docs/install-easy.rst

@@ -16,7 +16,11 @@ The following should work in any operating system, assuming compilers are instal
 #. Run the installer
 
 	* Type ``twinstall`` for installations on a local machine.
-	* Type ``twinstall --terminal`` for installation on a remote terminal.
+	* Type ``twinstall --terminal`` for installation on a remote machine.
+
+	.. note::
+
+		As of this writing, the installer's ``--terminal`` option is not compatible with Windows PowerShell.  As a result, if you want to install on a remote non-Windows server from a Windows terminal, use the old-style command prompt, or a third party terminal emulator.
 
 #. Use the installer to complete the sequence of steps in the ``Tasks`` area.
 

docs/ref-tools.rst

@@ -639,11 +639,7 @@ Diagnostics
 Diagnostic Formats
 ,,,,,,,,,,,,,,,,,,
 
-TurboWAVE binaries are in numerical Python (numpy) format (extension ``.npy``).  They can be easily read into a Python program using ``numpy.load``.
-
-All metadata is in the file ``tw_metadata.json``, which can easily be read into a Python dictionary.  One then looks up the file of interest to expose further dictionaries pertaining to the file.
-
-Text files are generally tab delimited tables of ASCII data, with a one-line header containing column labels.
+TurboWAVE binaries are in numerical Python (numpy) format (extension ``.npy``). All metadata is in the file ``tw_metadata.json``. Text files are generally tab delimited tables of ASCII data, with a one-line header containing column labels.
 
 .. highlight:: none
 
@@ -676,6 +672,60 @@ Particles must be identified by unique values of aux1 and aux2.
 The time level separator is a record with all zeros.
 Valid particles can never have aux1 = aux2 = 0.
 
+Example Post-processing Script
+,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,
+
+.. highlight:: python
+
+Typical Python post-processing scripts begin like this::
+
+	import numpy as np
+	import json
+	import pathlib
+
+	my_path = pathlib.Path.home() / 'Run'
+	# Get a field component into a 4D numpy array with shape (t,x,y,z)
+	Ex = np.load(my_path / 'Ex.npy')
+	# Load the metadata into a dictionary (all metadata)
+	with open(my_path / 'tw_metadata.json','r') as f:
+		meta = json.load(f)
+	# As an example of metadata, get the conversion factor to mks units.
+	# Note axis mapping, 0=t, 1=x, 2=y, 3=z, 4=data
+	mks_factor = meta['Ex.npy']['axes']['4']['mks multiplier']
+	# Get the name of the grid file
+	grid_file_name = meta['Ex.npy']['grid']
+
+The grid data is a text file.  One way to read it is with the following function::
+
+	def get_mesh_pts(grid_file_path,dims):
+	    """Try to find a grid warp file matching the npy file.
+	    If the file is found return [tmesh,xmesh,ymesh,zmesh].
+	    Each element is a list of the mesh points along the given axis.
+	    If the file is not found return unit length uniform mesh.
+	    Arguments: grid_file_path = pathlike, name of grid file.
+	               dims = expected shape of the data"""
+	    try:
+	        ans = [[],[],[],[]]
+	        with open(grid_file_path) as f:
+	            for line in f:
+	                l = line.split(' ')
+	                if l[0]=='t':
+	                    ans[0] += [np.float(l[-1])]
+	                if l[0]=='axis1' and len(ans[1])==0:
+	                    ans[1] = [np.float(x) for x in l[2:]]
+	                if l[0]=='axis2' and len(ans[2])==0:
+	                    ans[2] = [np.float(x) for x in l[2:]]
+	                if l[0]=='axis3' and len(ans[3])==0:
+	                    ans[3] = [np.float(x) for x in l[2:]]
+	        if len(ans[0])==dims[0] and len(ans[1])==dims[1] and len(ans[2])==dims[2] and len(ans[3])==dims[3]:
+	            return [np.array(ans[0]),np.array(ans[1]),np.array(ans[2]),np.array(ans[3])]
+	        else:
+	            warnings.warn('Grid file found but wrong dimensions ('+grid_file_path+').')
+	            return [np.linspace(0.0,1.0,dims[i]) for i in range(4)]
+	    except:
+	        warnings.warn('No grid file found ('+grid_file_path+').')
+	        return [np.linspace(0.0,1.0,dims[i]) for i in range(4)]
+
 .. _diagnostics-shared:
 
 Diagnostics Shared Directives

tools/twutils/setup.py

@@ -6,7 +6,7 @@ def readme():
 		return f.read()
 
 setup(name='twutils',
-	version='4.3.0rc',
+	version='4.3.0',
 	description='TurboWAVE utilities',
 	long_description=readme(),
 	classifiers=[

tools/twutils/twutils/command_line/os2tw.py

@@ -3,12 +3,14 @@
 import glob
 import json
 import warnings
+import pkg_resources
 import numpy as np
 import h5py
 from scipy import constants as C
 
 def print_usage():
-    print('Usage: os2tw <cmd> <component>[,<modifier>] [n1=<density>] [dt=<frame_time>] [frame=<::>] [nfac=<factor>] [root=<MS>]')
+    print('Usage: os2tw [--help,-h] [--version,-v] <cmd> <component>[,<modifier>]')
+    print('             [n1=<density>] [dt=<frame_time>] [frame=<::>] [nfac=<factor>] [root=<MS>]')
     print('Extracts data from OSIRIS directory tree, consolidates into npy file, and creates metadata file.')
     print('1D coordinate label mapping: 1->z')
     print('2D coordinate label mapping: 1->z, 2->x')
@@ -27,6 +29,9 @@ def print_usage():
     print('nfac = OSIRIS frame skipping multiplication factor')
     print('root = OSIRIS root data directory relative to working directory')
 
+def print_version():
+    print('os2tw is provided by twutils, version '+pkg_resources.get_distribution('twutils').version)
+
 def str_to_range(rng_str,num):
     '''Convert a numpy-style slice string to a range'''
     rng = rng_str.split(':')
@@ -146,9 +151,12 @@ def grid_string(frame,dt,bounds,shp):
 def main():
     # Process command line
     # Required arguments
-    if len(sys.argv)<2:
+    if len(sys.argv)<2 or '--help' in sys.argv or '-h' in sys.argv:
         print_usage()
         exit(0)
+    if '--version' in sys.argv or '-v' in sys.argv:
+        print_version()
+        exit(0)
     cmd = sys.argv[1]
     if cmd not in ['init','append']:
         raise ValueError('First argument <'+cmd+'> not recognized.')

tools/twutils/twutils/command_line/twinstall.py

@@ -301,6 +301,9 @@ def GetComponents(self):
                     os.chdir(verified_path[0])
                     self.cmd.display('Pulling from repository...')
                     compl = subprocess.run(["git","pull","origin","master"],stdout=subprocess.PIPE,stderr=subprocess.STDOUT,universal_newlines=True)
+                    if git_err_handler(compl,self.cmd):
+                        verified_path = []
+                    compl = subprocess.run(["git","pull","origin","--tag"],stdout=subprocess.PIPE,stderr=subprocess.STDOUT,universal_newlines=True)
                     if git_err_handler(compl,self.cmd):
                         verified_path = []
                     self.cmd.display('')
@@ -967,12 +970,18 @@ def main():
         print('TurboWAVE Interactive Core Installer.')
         print('Usage: twinstall [--help] [--terminal]')
         print('Arguments: --help,-h :  displays this message')
+        print('           --version,-v : display version number')
         print('           --terminal,-t : use textual interface')
         exit(0)
 
+    if '--version' in sys.argv or '-v' in sys.argv:
+        print('twinstall is provided by twutils, version '+pkg_resources.get_distribution('twutils').version)
+        exit(0)
+
     if '--terminal' in sys.argv or '-t' in sys.argv:
         os.environ.setdefault('ESCDELAY','25')
         curses.wrapper(terminal)
+
     else:
         root = tk.Tk()
         ttk.Style().theme_use('default')

tools/twutils/twutils/command_line/twplot.py

@@ -1,6 +1,7 @@
 import sys
 import glob
 import os
+import pkg_resources
 import PIL.Image
 import numpy as np
 import matplotlib as mpl
@@ -46,6 +47,9 @@ def print_usage():
 	print('Put a python range as one of the slices to generate animated GIF.')
 	print('For example, zxyt=0,0,2:5 would animate time slices 2,3,4.')
 
+def print_version():
+    print('twplot is provided by twutils, version '+pkg_resources.get_distribution('twutils').version)
+
 # Label scheme
 
 def format_label(l):
@@ -102,10 +106,14 @@ def ParseSlices(dims,ax_list,slice_str_list):
 
 def main():
 
-	if len(sys.argv)<3:
+	if len(sys.argv)<2 or '--help' in sys.argv or '-h' in sys.argv:
 		print_usage()
 		exit(0)
 
+	if '--version' in sys.argv or '-v' in sys.argv:
+		print_version()
+		exit(0)
+
 	# Matplotlib setup
 
 	mpl.rcParams.update({'text.usetex' : False , 'font.size' : 10})

tools/twutils/twutils/command_line/twtest.py

@@ -2,6 +2,7 @@
 import glob
 import ntpath
 import sys
+import pkg_resources
 import traceback
 import subprocess
 import datetime
@@ -21,6 +22,9 @@ def print_usage():
 	print('cluster example: python twtest.py ~/turboWAVE mpirun -np 4 tw3d')
 	print('N.b. as a corollary no double colons may appear in tw_root.')
 
+def print_version():
+    print('twtest is provided by twutils, version '+pkg_resources.get_distribution('twutils').version)
+
 def cleanup(wildcarded_path):
 	cleanstr = glob.glob(wildcarded_path)
 	for f in cleanstr:
@@ -200,9 +204,13 @@ def optimize_parallel(num_procs,num_threads,dims):
 
 def main():
 
-	if len(sys.argv)<2:
+	if len(sys.argv)<2 or '--help' in sys.argv or '-h' in sys.argv:
 		print_usage()
-		exit()
+		exit(0)
+
+	if '--version' in sys.argv or '-v' in sys.argv:
+		print_version()
+		exit(0)
 
 	subargs = sys.argv[1].split('::')
 	tw_root = subargs[0]