Merge pull request #5994 from kayahans/qmca_image

Nexus: add qmca feature to save plots to image files (png, pdf, svg, eps)

Author: prckent

docs/analyzing.rst

@@ -53,8 +53,11 @@ typing ``qmca`` at the command line with no other inputs (also try
       -e EQUILIBRATION, --equilibration=EQUILIBRATION
                             Equilibration length in blocks (default=auto).
       -a, --average         Average over files in each series (default=False).
+      --save_average        Save averaged data into scalar.dat files.
+                            (default=False).
       -w WEIGHTS, --weights=WEIGHTS
                             List of weights for averaging (default=None).
+      -j JOIN, --join=JOIN  Join data for a range of series (default=None).
       -b, --reblock         (pending) Use reblocking to calculate statistics
                             (default=False).
       -p, --plot            Plot quantities vs. series (default=False).
@@ -69,7 +72,14 @@ typing ``qmca`` at the command line with no other inputs (also try
       --noac                Alias for --noautocorr (default=False).
       --sac                 Show autocorrelation of sample data (default=False).
       --sv                  Show variance of sample data (default=False).
-      -i, --image           (pending) Save image files (default=False).
+      --sort                Display output data sorted alphabetically by file name
+                            (default=False).
+      -i, --image           Save plot files (default prefix: qmca_plot).
+      --image-prefix=BASENAME
+                            Save plot files with basename prefix
+                            (default=None).
+      --image-format=FORMAT Output format for saved plots: png, pdf, svg, or eps
+                            (default=png).
       -r, --report          (pending) Write a report (default=False).
       -s, --show_options    Print user provided options (default=False).
       -x, --examples        Print examples and exit (default=False).
@@ -81,6 +91,17 @@ typing ``qmca`` at the command line with no other inputs (also try
                             Show number of samples needed to maintain error bar on
                             larger system: desired particle number first, current
                             particle number second (default=none)
+      --fp=PRECISION        Sets the floating point precision of displayed
+                            statistical results.  Must be a floating point format
+                            string such as 16.8f, 8.6e, or similar (default=none).
+      --nowarn              Suppress warning messages (default=False).
+      --average_all         Average over all files, ignoring differences in path
+                            (default=False).
+      --twist_info=TWIST_INFO
+                            Use twist weights in twist_info.dat files or not.
+                            Options: "use", "ignore", "require".  "use" means use
+                            when present, "ignore" means do not use, "require"
+                            means must be used (default=use).
 
 .. _qmca-mean-error:
 
@@ -566,29 +587,59 @@ command line with no other input. This following is a current list:
 ::
 
   Abbreviations and full names for quantities:
-      ar              = AcceptRatio
-      bc              = BlockCPU
-      bw              = BlockWeight
-      ce              = CorrectedEnergy
-      de              = DiffEff
-      e               = LocalEnergy
-      ee              = ElecElec
-      eff             = Efficiency
-      ii              = IonIon
-      k               = Kinetic
-      kc              = KEcorr
-      l               = LocalECP
-      le2             = LocalEnergy_sq
-      mpc             = MPC
-      n               = NonLocalECP
-      nw              = NumOfWalkers
-      p               = LocalPotential
-      sw              = AvgSentWalkers
-      te              = TrialEnergy
-      ts              = TotalSamples
-      tt              = TotalTime
-      v               = Variance
-      w               = Weight
+    ar              = AcceptRatio
+    bc              = BlockCPU
+    bw              = BlockWeight
+    ce              = CorrectedEnergy
+    de              = DiffEff
+    de_AB           = dLocEne_0_1
+    dee_AB          = dElecElec_0_1
+    dii_AB          = dIonIon_0_1
+    e               = LocalEnergy
+    e_A             = LocEne_0
+    e_B             = LocEne_1
+    ee              = ElecElec
+    ee_A            = ElecElec_0
+    ee_B            = ElecElec_1
+    ee_m            = ElecElec_m
+    ee_p            = ElecElec_p
+    eff             = Efficiency
+    ei_A            = ElecIon_0
+    ei_AB           = dElecIon_0_1
+    ei_B            = ElecIon_1
+    el              = EnergyEstim__nume_real
+    fl              = Flux
+    fl_A            = Flux_0
+    fl_AB           = dFlux_0_1
+    fl_B            = Flux_1
+    ii              = IonIon
+    ii_A            = IonIon_0
+    ii_B            = IonIon_1
+    k               = Kinetic
+    k_A             = Kinetic_0
+    k_AB            = dKinetic_0_1
+    k_B             = Kinetic_1
+    k_m             = Kinetic_m
+    k_p             = Kinetic_p
+    kc              = KEcorr
+    l               = LocalECP
+    le2             = LocalEnergy_sq
+    mpc             = MPC
+    n               = NonLocalECP
+    nw              = NumOfWalkers
+    p               = LocalPotential
+    p_A             = LocPot_0
+    p_AB            = dLocPot_0_1
+    p_B             = LocPot_1
+    p_p             = LocalPotential_pure
+    sw              = AvgSentWalkers
+    te              = TrialEnergy
+    ts              = TotalSamples
+    tt              = TotalTime
+    v               = Variance
+    w               = Weight
+    wp_A            = wpsi_0
+    wp_B            = wpsi_1
 
 See the output overview for ``scalar.dat``
 (:ref:`scalardat-file`) and ``dmc.dat``
@@ -877,6 +928,27 @@ Plotting a trace of the local energy:
 
   >qmca -t -q e *scalar*
 
+Saving a trace plot of the local energy to a PNG file (default prefix: qmca_plot):
+
+::
+
+  >qmca -t -q e --image *scalar*
+
+Saving a trace plot of the local energy to a PNG file with a custom prefix:
+
+::
+
+  >qmca -t -q e --image-prefix myrun *scalar*
+
+Saving a trace plot to a PDF file for publication (vector format):
+
+::
+
+  >qmca -t -q e --image-format pdf --image-prefix myrun *scalar*
+
+PDF, SVG, and EPS output are resolution-independent and better suited to journal
+submission than PNG.
+
 Applying an equilibration cutoff to VMC data (series 0):
 
 ::

nexus/nexus/bin/qmca

@@ -835,6 +835,12 @@ QMCA examples:
    qmca -pa -q e -e 10 qmc.g*.s*.scalar.dat
    qmca -ta -q e -e 10 qmc.g*.s*.scalar.dat
 
+ saving plots to files (-i/--image uses prefix qmca_plot; --image-prefix sets a custom prefix)
+   qmca -t -q e -i qmc.s*.scalar.dat
+   qmca -ta -q ev --image-prefix myrun qmc.g*.s*.scalar.dat
+ saving plots to PDF files (--image-format pdf for vector output suited to publication)
+   qmca -t -q e --image-format pdf --image-prefix myrun qmc.s*.scalar.dat
+
  multiple quantities and prefixes can be used for plots as well
 '''
         self.log(examples)
@@ -931,9 +937,17 @@ QMCA examples:
                           action='store_true',default=False,
                           help='Display output data sorted alphabetically by file name (default=%default).'
                           )
-        parser.add_option('-i','--image',dest='image',
+        parser.add_option('-i','--image', dest='save_image',
                           action='store_true',default=False,
-                          help='(pending) Save image files (default=%default).'
+                          help='Save plot files (default prefix: qmca_plot).'
+                          )
+        parser.add_option('--image-prefix',dest='image_prefix',
+                          default='None',metavar='BASENAME',
+                          help='Save plot files with basename prefix (default=%default).'
+                          )
+        parser.add_option('--image-format',dest='image_format',
+                          default='png',metavar='FORMAT',
+                          help='Output format for saved plots: png, pdf, svg, or eps (default=%default).'
                           )
         parser.add_option('-r','--report',dest='report',
                           action='store_true',default=False,
@@ -979,7 +993,7 @@ QMCA examples:
                           help='Use twist weights in twist_info.dat files or not.  Options: "use", "ignore", "require".  "use" means use when present, "ignore" means do not use, "require" means must be used (default=%default).'
                           )
 
-        unsupported = set('histogram image reblock report'.split())
+        unsupported = set('histogram reblock report'.split())
 
         units = obj(hartree='Ha',ha='Ha',ev='eV',rydberg='Ry',ry='Ry',kelvin='K',kj_mol='kJ_mol',joules='J')
 
@@ -1064,9 +1078,19 @@ QMCA examples:
             #end if
             opt.join = j
         #end if
-        if opt.image=='None':
-            opt.image=None
+        if opt.image_prefix!='None':
+            opt.image = opt.image_prefix
+        elif opt.save_image:
+            opt.image = 'qmca_plot'
+        else:
+            opt.image = None
+        #end if
+        image_formats = ('png','pdf','svg','eps')
+        fmt = opt.image_format.lower().lstrip('.')
+        if fmt not in image_formats:
+            self.error('image_format option is invalid\nimage_format must be one of: {}\nyou provided: {}'.format(image_formats,opt.image_format))
         #end if
+        opt.image_format = fmt
         twist_info_options = ('use','ignore','require')
         if opt.twist_info not in twist_info_options:
             self.error('twist_info option is invalid\ntwist_info must be one of: {}\nyou provided: {}'.format(twist_info_options,opt.twist_info))
@@ -1449,7 +1473,9 @@ QMCA examples:
             tracestyle  = color+line
             histstyle   = color+line
             iplot,itrace,ihist = list(range(3))
+            mode_names = ['series','trace','histogram']
             modes = [opt.plot,opt.trace,opt.histogram]
+            save_plots = opt.image is not None
             quantities = []
             for q in opt.quantities:
                 all_present = True
@@ -1562,12 +1588,28 @@ QMCA examples:
                                         ax.legend(loc=2,bbox_to_anchor=(1.0,1.0),borderaxespad=0.)
                                     #end if
                                 #end if
+                                if save_plots:
+                                    safe_prefix = prefix.replace('/','_').replace(os.sep,'_')
+                                    fmt = opt.image_format
+                                    fname = '{0}_{1}_{2}_{3}.{4}'.format(
+                                        opt.image,safe_prefix,quantity,mode_names[mode],fmt)
+                                    save_kwargs = dict(format=fmt,bbox_inches='tight')
+                                    if fmt=='png':
+                                        save_kwargs['dpi'] = 150
+                                    #end if
+                                    fig.savefig(fname,**save_kwargs)
+                                    if self.verbose:
+                                        self.log('saved plot to {0}'.format(fname),n=1)
+                                    #end if
+                                    plt.close(fig)
+                                #end if
                             #end if
                         #end for
                     #end if
                 #end for
             #end for
-            plt.show()
+            if not save_plots:
+                plt.show()
         #end if
     #end def analyze_data
 #end class QMCA

nexus/nexus/tests/test_qmca.py

@@ -266,3 +266,59 @@ def test_weighted_twist_average():
     os.chdir(cwd)
 #end def test_weighted_twist_average
 
+
+
+def test_save_plot_pdf():
+
+    os.environ['MPLBACKEND'] = 'Agg'
+    try:
+        import matplotlib.pyplot  # noqa: F401
+    except (ImportError, RuntimeError):
+        pytest.skip('matplotlib not available')
+
+    cwd = Path.cwd()
+    os.chdir(QA_PATHS["vmc"])
+
+    prefix = 'testplot_pdf'
+    plot_file = f'{prefix}_vmc_LocalEnergy_trace.pdf'
+    if os.path.exists(plot_file):
+        os.remove(plot_file)
+
+    command = (f'MPLBACKEND=Agg {sys.executable} {QMCA_EXE} -t -q e -e 5 '
+               f'--image-prefix {prefix} --image-format pdf --nowarn *scalar*')
+    out,err,rc = execute(command)
+    assert rc==0
+    assert os.path.exists(plot_file)
+
+    os.remove(plot_file)
+    os.chdir(cwd)
+#end def test_save_plot_pdf
+
+
+
+def test_save_plot_png_default():
+
+    os.environ['MPLBACKEND'] = 'Agg'
+    try:
+        import matplotlib.pyplot  # noqa: F401
+    except (ImportError, RuntimeError):
+        pytest.skip('matplotlib not available')
+
+    cwd = Path.cwd()
+    os.chdir(QA_PATHS["vmc"])
+
+    prefix = 'testplot_png'
+    plot_file = f'{prefix}_vmc_LocalEnergy_trace.png'
+    if os.path.exists(plot_file):
+        os.remove(plot_file)
+
+    command = (f'MPLBACKEND=Agg {sys.executable} {QMCA_EXE} -t -q e -e 5 '
+               f'--image-prefix {prefix} --image --nowarn *scalar*')
+    out,err,rc = execute(command)
+    assert rc==0
+    assert os.path.exists(plot_file)
+
+    os.remove(plot_file)
+    os.chdir(cwd)
+#end def test_save_plot_png_default
+