Add new capabilities

- Amendments to simulation output: changed definition and calculation of
  equivalent variables (e.g., equivalent deformation rate). Refer to
  documentation for full descriptions of output.
- Additions to simulation output: total strain tensor, plastic strain tensor,
  equivalent elastic strain, and nodal displacements.
- Updates to optional inputs: added option for saturation strength evolution.
- Simulation restart updates: New default naming convention for restart files.
- Mesh parsing update
- Updated and improved examples
- Bug fixes and code improvements
- Documentation improvements
* Incompatible changes: some changes require Neper v4.2.0 or greater.

.gitignore

@@ -4,36 +4,58 @@
 *.x
 *~
 *.x.dSYM
-*.cp* 
-*.fn* 
-*.ky* 
-*.pg* 
-*.tp* 
-*.vr* 
+*.cp*
+*.fn*
+*.ky*
+*.pg*
+*.tp*
+*.vr*
 *.mv*
 *.dvi
 *.info
 *.swp
 
+# Ignore FEPX build files
 /lib/libf95/modules
 /lib/libparallel/modules_serial
 /lib/libparallel/modules_parallel
 /src/build/
+/build/
 
 # Ignore AppleDouble files and Mac .DS_Store files
 ._*
 .DS_Store
 
-# Ignore LaTeX auxilliary files
+# Ignore LaTeX auxilliary files and made PDFs
 *.aux
 *.log
 *.out
 *.synctex.gz
 *.toc
-
 fepx.pdf
 
 # Ignore sed -e files
 VERSIONS-e
 *.f90-e
 *.texi-e
+
+# Ignore meld backups
+*_BACKUP_*
+*_BASE_*
+*_LOCAL_*
+*_REMOTE_*
+*.orig
+
+# Ignore simulation post files
+/examples/1_uniaxial/post.*
+/examples/1_uniaxial.sim/
+/examples/2_triaxCSR/post.*
+/examples/2_triaxCSR.sim/
+/examples/3_triaxCLR/post.*
+/examples/3_triaxCLR.sim/
+/examples/4_restart/cycle1/
+/examples/4_restart/cycle1.sim/
+/examples/4_restart/cycle2/
+/examples/4_restart/cycle2.sim/
+/examples/5_external/post.*
+/examples/5_external.sim/

VERSIONS

@@ -1,7 +1,18 @@
-New in 1.1.2-1 (02 Apr 2021):
-- Updated mesh parsing.
+New in 1.2.0 (11 Jun 2021):
+- Amendments to simulation output: changed definition and calculation of
+  equivalent variables (e.g., equivalent deformation rate). Refer to
+  documentation for full descriptions of output.
+- Additions to simulation output: total strain tensor, plastic strain tensor,
+  equivalent elastic strain, and nodal displacements.
+- Updates to optional inputs: added option for saturation strength evolution.
+- Simulation restart updates: New default naming convention for restart files.
+- Mesh parsing update
+- Updated and improved examples
+- Bug fixes and code improvements
+- Documentation improvements
+* Incompatible changes: some changes require Neper v4.2.0 or greater.
 
-New in 1.1.1 (23 Nov 2021):
+New in 1.1.1 (23 Nov 2020):
 - Major code formatting changes
 - Minor bug fixes
 

doc/texinfo/Makefile

@@ -1,5 +1,5 @@
 # This file is part of the FEPX software package.
-# Copyright (C) 1996-2020 ACME Lab
+# Copyright (C) 1996-2021 ACME Lab
 # See the COPYING file in the top-level directory.
 
 pdf:

doc/texinfo/copying.texi

@@ -1,5 +1,5 @@
 @c This file is part of the FEPX software package.
-@c Copyright (C) 1996-2020, DPLab, ACME Lab.
+@c Copyright (C) 1996-2021, DPLab, ACME Lab.
 @c See the COPYING file in the top-level directory.
 
 @node Conditions of Use

doc/texinfo/develhistory.texi

@@ -1,5 +1,5 @@
 @c This file is part of the FEPX software package.
-@c Copyright (C) 1996-2020 ACME Lab
+@c Copyright (C) 1996-2021 ACME Lab
 @c See the COPYING file in the top-level directory.
 
 @node Development History

doc/texinfo/fepx.texi

@@ -1,6 +1,6 @@
 \input texinfo.tex
 @c This file is part of the FEPX software package.
-@c Copyright (C) 1996-2020, DPLab, ACME Lab.
+@c Copyright (C) 1996-2021, DPLab, ACME Lab.
 @c See the COPYING file in the top-level directory.
 
 @afourpaper

doc/texinfo/introduction.texi

@@ -1,5 +1,5 @@
 @c This file is part of the FEPX software package.
-@c Copyright (C) 1996-2020, DPLab, ACME Lab.
+@c Copyright (C) 1996-2021, DPLab, ACME Lab.
 @c See the COPYING file in the top-level directory.
 
 @node Introduction
@@ -22,7 +22,7 @@ FEPX is a finite element software package for polycrystal plasticity. It is well
 
 @end itemize
 
-FEPX strives to be a user-friendly, efficient, and robust tool. All of the input data are prescribed non-interactively, using ASCII files. FEPX works hand in hand with Neper (@url{http://neper.info}), which can be used for both generating the input polycrystal mesh and post-processing the simulation results. Currently, FEPX is designed to provide solutions on rectangular prismatic domains (or right cuboids).
+FEPX strives to be a user-friendly, efficient, and robust tool. All of the input data are prescribed non-interactively, using ASCII files. FEPX works hand in hand with Neper (@url{https://neper.info}), which can be used for both generating the input polycrystal mesh and post-processing the simulation results. Currently, FEPX is designed to provide solutions on rectangular prismatic domains (or right cuboids).
 
 @node Resources and Support
 @section Resources and Support
@@ -37,15 +37,24 @@ Several complementary resources describing FEPX are available:
 
 @item The FEPX website, @url{https://fepx.info}, gives a general introduction to FEPX with illustrative examples.
 
-@end itemize
+@item The FEPX GitHub repository, @url{https://github.com/acmelab-ua/FEPX}, is where the latest version is available and where user interactions take place:
 
-The latest development version of FEPX is available from the development repository, @url{https://github.com/acmelab-ua/FEPX}. The best way to get and keep up-to-date with development versions is to clone the repository, using
+@itemize
+@item To get and keep up-to-date with the latest version, clone the repository using
 
 @com{git clone https://github.com/acmelab-ua/FEPX.git}
 
-which gives access to the latest stable development release on the default, @code{main}, branch. To update your local repository, run @command{git pull} from within the repository. The best way to report bugs within FEPX is directly through the GitHub issue tracker, @url{http://github.com/acmelab-ua/FEPX/issues}. When reporting bugs, please provide a minimal working example and any relevant FEPX terminal output. Any feature requests to the program should also be made within the issue tracker and marked with the appropriate labeling. 
+which gives access to the latest stable development release on the default, @code{main} branch. To update your local repository, run @command{git pull} from within the repository.
+
+@item To report bugs, use the issue tracker, @url{https://github.com/acmelab-ua/FEPX/issues}. When reporting bugs, please provide a minimal working example and the FEPX terminal output.
+
+@item To ask questions, share comments or request new features, use discussions, @url{https://github.com/acmelab-ua/FEPX/discussions}.
+
+@end itemize
+
+@end itemize
 
-Resources for Neper can be accessed from @url{http://neper.info}.
+Resources for Neper can be accessed from @url{https://neper.info}.
 
 @node Installing FEPX
 @section Installing FEPX
@@ -71,7 +80,7 @@ FEPX is written in Fortran, and it can run on any Unix-like system (including Ma
 
 @end itemize
 
-This procedure uses the default configuration options and should work out-of-the-box if you have a Fortran compiler, OpenMPI, and CMake installed. Testing is performed on GFortran @w{version 6} and greater, and OpenMPI @w{version 2} and greater (other Fortran compilers and MPI distributions may also work, though they are not explicitly supported or tested by ACME Lab). A minimum version of CMake @w{version 2.8} is required to utilize the build system.
+This procedure uses the default configuration options and should work out-of-the-box if you have a Fortran compiler, OpenMPI, and CMake installed. Testing is performed on GFortran @w{version 6} and greater, and OpenMPI @w{version 2} and greater (other Fortran compilers and MPI distributions may also work, though they are not explicitly supported or tested by ACME Lab). A minimum version of CMake @w{version 3.0} is required to utilize the build system.
 
 @node Getting Started
 @section Getting Started

doc/texinfo/job.texi

@@ -1,5 +1,5 @@
 @c This file is part of the FEPX software package.
-@c Copyright (C) 1996-2020 ACME Lab
+@c Copyright (C) 1996-2021 ACME Lab
 @c See the COPYING file in the top-level directory.
 
 @node Running a Simulation
@@ -21,7 +21,7 @@ A simulation may be run in parallel utilizing MPI,
 @com{mpirun -np @var{N} fepx}
 @inputfilefoot
 
-where @var{N} refers to the number of MPI processes desired. Note that your local installation of MPI may not utilize @samp{mpirun} and instead an alternative MPI command may be required. 
+where @var{N} refers to the number of MPI processes desired. Note that your local installation of MPI may not utilize @samp{mpirun} and instead an alternative MPI command may be required.
 
 @node Submitting FEPX to a Job Scheduling Program
 @section Submitting FEPX to a Job Scheduling Program
@@ -72,47 +72,42 @@ would be run by entering @command{qsub runtorque.sh} into the terminal from with
 @node Restarting a Simulation
 @section Restarting a Simulation
 
-A simulation may be restarted only if the restart files are written as simulation output (@pxref{Restart Output}). Printing restart files will output, by default, a single @samp{post.restart.control} file and a @samp{post.restart.field.core*} file for each individual core where @samp{*} denotes the ID of the core on which the data is being printed. These restart files must be included in the simulation directory along with the configuration file, the mesh file, and any external files included with the simulation. 
+A simulation may be restarted only if the restart files were printed as
+simulation output on the previous run (@pxref{Restart Output}). Printing restart files outputs
+a single @samp{rst@var{N}.control} file and a
+@samp{rst@var{N}.field.core@var{#}} file for each individual core, where
+@samp{@var{N}} refers to the restart ID (0 indexing), and @samp{@var{#}} denotes the
+ID of the core on which the data is being printed. These restart files must be
+included in the simulation directory along with the configuration file, the
+mesh file, and any external files included with the simulation.
 
-A simulation may be restarted by adding the following lines to the @file{simulation.config} file:
+A simulation may be restarted by adding the following line to the
+@file{simulation.config} file:
 
 @inputfilehead
 @example
-restart @var{file_handling_option}
+restart on
 @end example
 @inputfilefoot
 
-where @code{@var{file_handling_option}} is the style of file handling desired for a restarted simulation with respect to requested output variable printing. Options for @code{@var{file_handling_option}} are: @samp{append} and @samp{new_file}. When @samp{append} is selected, the restarted simulation will attempt to append output variable data to the existing files in the local directory. If @samp{append} is selected and output variable files are not present in the local directory, the restarted simulation will write new files as needed. When @samp{new_file} is selected, the restarted simulation will write output variable data to a new set of files, by default, as @samp{post.var.rst1.core*} where @code{@var{var}} is the requested output variable name and @code{@var{rst1}} is the restart label applied to all new output variable files.
-
-To modify the default restart file label, @code{@var{rst1}}, for the @samp{restart new_file} option:
-
-@inputfilehead
-@example
-rsvar_base_out @var{restart_label}
-@end example
-@inputfilefoot
-
-where @code{@var{restart_label}} is the desired restart file label of the new restart output variable files. Automatic options for @code{@var{restart_label}} are: @samp{@{date@}} and @samp{@{date_time@}}. The option @samp{@{date@}} will use the current calendar date in the @code{YYYYMMDD} format and @samp{@{date_time@}} will use the current calendar date and time in the @code{YYYYMMDD-HHMM} format. Note that, although @samp{rst1} is the default @code{@var{restart_label}}, if @samp{restart new_file} is enabled while  @samp{post.var.rst1.core*} files are present in the local directory, the restarted simulation will automatically increment the integer value in the label to avoid potentially overwriting data files. For example, if the files @samp{post.var.rst1.core*} and @samp{post.var.rst2.core*} are present in the local directory, the restarted simulation will write to new files labeled @samp{post.var.rst3.core*}. Likewise, if a user-defined @code{@var{restart_label}} is utilized while files with the same label exist in the local directory, the restarted simulation will abort to avoid potentially overwriting local data files.
-
-Additionally, the names of these restart files may be adjusted upon writing or before reading by adding optional commands to the @file{simulation.config} file.
-
-To modify the file names of the input restart (control/field) files:
-@inputfilehead
-@example
-rsctrl_in @var{control_file_name}
-rsfield_base_in @var{field_file_name}
-@end example
-@inputfilefoot
-
-To modify the file names of the output restart (control/field) files:
-@inputfilehead
-@example
-rsctrl_out @var{control_file_name}
-rsfield_base_out @var{field_file_name}
-@end example
-@inputfilefoot
-
-where @code{@var{control_file_name}} is the desired file name of the restart control file and @code{@var{field_file_name}} is the desired @dfn{base} string for the file name(s) of the restart field data files (@code{@var{field_file_name}} will always have the @samp{.core*} string appended on the defined string). @c For example, if the @code{@var{field_file_name}} is set to @samp{rsfield_example} the output restart field data file(s) will be named @samp{rsfield_example.core*}.
-
-Any restarted simulation must be rerun with the same number of cores that were used to run the original simulation. FEPX will automatically begin the simulation at the beginning of the step after the restart files were written. Restart files are always written at the end of a successful step and not at individual increments. Note that when a simulation is restarted, the new output files will overwrite any present output data in the local directory as defined in the @file{simulation.config} file. If this behavior is undesirable, it is recommended that the restart files, configuration file, mesh file, and any external files be copied to a new directory before restarting the simulation proper.
-
+When a simulation restarts, it will attempt to find the simulation restart
+files with the highest index, @code{@var{N}}. It will write output variable data to
+a new set of files, @samp{post.@var{var}.rst@var{N}+1.core*}, where @samp{@var{var}}
+is the requested output variable name and @samp{rst@var{N}+1} is the restart
+label applied to all new output variable files. Likewise, if restart files are
+again printed, their index will increase to @code{@var{N}+2} (the previous
+restart's files will not be overwritten).
+
+A simulation restart must be performed with the same number of cores that were
+used to run the original simulation. Restart files are always written at the
+end of a successful step and not at individual increments.
+
+Each restarted simulation is considered a new simulation, albeit with
+initialized field variables as written in the restart files. Step and increment
+indices, as well as the simulation time, are all reset to 0.
+
+When restarting a simulation, the prescribed deformation history
+(@pxref{Deformation History}) should include only additional steps. The
+restarted simulation will attempt to follow the entire deformation history as
+prescribed in the @file{simulation.config} file, and will not consider steps
+that were completed in the initial simulation.