First PR with some utils and docs

README.md

@@ -1,2 +1,19 @@
 # utils
-ARFC repository for storing miscellaneous tools and utility scripts
+ARFC repository for storing miscellaneous tools, scripts, and resources.
+Before creating a new directory, make sure your contribution doesn't fit in
+an existing directory.  If you add a new directory, add a description to 
+the list below.
+
+## Directories
+- `hpc/`: tools and scripts for working with hpc systems, such as useful batch
+    scripts.
+- `misc/`: miscellaneous tools and resources that are the only item of their category.  If it would be part of an often used larger category, do not put it
+in `misc/`.  `misc/` has its own README that is used to direct others to 
+resources that are in-browser.
+- `serpent/`: tools and scripts for working with Serpent.
+    > [!IMPORTANT]
+    > Serpent is an export controlled software.  ARFC has a group license
+    > for Serpent.  However, this is a public repository.  Never upload
+    > nuclear data library files or Serpent source code.  This directory
+    > should only contain resources without sensitive information.  When in
+    > doubt, do not commit to GitHub without asking @katyhuff.

hpc/README.md

@@ -0,0 +1,10 @@
+# HPC
+
+Directory for scripts or other utils for running on HPC systems.  These
+should be agnostic to the specific simulation tool being used - such utils
+should be in a directory dedicated to that particular simulation software.
+
+Items:
+- loop_job.sh: Sisyphean job script meant for automating submitting jobs for a
+long, continuous simulation.  Perpetually re-submits itself until it completes 
+the simulation or fails due to an error.  Written for HPC systems using SLURM.

hpc/loop_job.sh

@@ -0,0 +1,42 @@
+#!/bin/bash
+
+#SBATCH --time=04:00:00			### The limit on wall time for a single instance of the job
+#SBATCH --nodes=2-4 			### Total number of nodes to use
+#SBATCH --ntasks=384  			### Total number of tasks
+#SBATCH --cpus-per-task=1  		### Number of threads per task (OMP threads)
+##SBATCH --exclude=BAD_NODES		### Optional, exclude nodes if needed
+#SBATCH --job-name=JOB_NAME
+#SBATCH --account=ACCOUNT_ID
+#SBATCH --partition=PARTITION
+#SBATCH --mail-user=USERNAME@EMAIL.COM
+#SBATCH --mail-type=FAIL
+#
+
+### Script for creating a job script that automatically resubmits itself.
+### This is intended for use with very long simulations that exceed the
+### wall-time limits on your system and are designed to continue running
+### from some sort of arbitrary checkpoint.
+### This is made with slurm in mind, but might be able to be converted to work
+### on systems using other management tools.
+
+### the following lines are only for activating a conda environment, replace
+### these with whatever your job needs for its environment
+source /user/home/path/.bashrc
+conda activate /user/home/path/.conda/envs/your_env
+
+### If the file 'finished' exists, do nothing instead of resubmitting the job.
+if [ ! -f "finished" ] ; then
+	sbatch --dependency=afterany:$SLURM_JOBID loop_job.sh
+else
+	exit 0
+fi
+
+### Start job commands ###
+echo "Hello, World!" > output.txt
+### End job commands ###
+
+### If the job hit the wall time while still running, the job will abort before
+### it can create finished.  If the job completes, or an error causes the job
+### to fail, finished will be created, which will stop the job from endlessly
+### submitting itself.
+touch finished

misc/README.md

@@ -0,0 +1,9 @@
+# Miscellaneous
+
+Directory for miscellaneous tools, scripts, and utilities.  If the resource
+is a link to something in browser, list in this README with a brief description.
+
+Items:
+- [Viridis Color Palatte Generator](https://waldyrious.net/viridis-palette-generator/):
+tool for generating N evenly spaced colors in the viridis, inferno, magma, or
+plasma color maps.

serpent/README.md

@@ -0,0 +1,9 @@
+# Serpent:
+
+The Serpent docs are [here](https://serpent.vtt.fi/docs/index.html).  
+
+- `xsdata-tutorial.pdf` gives a tutorial on how to convert MCNP xsdir library
+files into the xsdata format used by Serpent.
+- `append_data.py` has one function, which is for aggregating decay, spontaneous
+fission yield, and neutron-induced fission yield data into `.dec`, `.sfy`, and
+`.nfy` libraries.  ENDF publishes this data publically.  For example, ENDFVIII.0 can be found [here](https://www.nndc.bnl.gov/endf-b8.0/download.html)

serpent/append_data.py

@@ -0,0 +1,41 @@
+import glob
+import shutil
+from os import path
+
+
+def write_serpent_misc_data(datapath, serpent_file):
+    '''
+    Given a path to a directory containing ENDF format data files (*.endf) for
+    decay, spontaneous fission yields, and neutron-induced fission yields, this
+    will append the data into a single file that can be used as the respective
+    library file in Serpent.
+
+    Parameters
+    ----------
+    datapath : str
+        Path to the directory containing the .endf files to be aggregated.
+        Note that this function uses the os package to expand the `~`
+        shorthand, so paths should be given as `~/path/to/data`, not 
+        `/home/user/path/to/data`
+    serpent_file : str
+        Name of the file this function generates.  File extensions commonly
+        match the library being generated, e.g.: `sss_endfX.dec`, 
+        `sss_endfX.nfy`, or `sss_endfX.sfy`.
+
+    Returns
+    ----------
+    This function has no returns, but does generate a file named serpent_file
+    '''
+    dpath = path.expanduser(datapath)
+    data_files = glob.glob(path.join(dpath, "*.endf"))
+
+    with open(serpent_file, mode='wb') as sssf:
+        for data_file in data_files:
+            with open(data_file, mode = 'rb') as dataf:
+                shutil.copyfileobj(dataf, sssf)
+
+
+
+
+
+

serpent/tutorial-tex/xsdata-tutorial.tex

@@ -0,0 +1,82 @@
+\documentclass[12pt, letterpaper]{article}
+\title{Serpent Cross-section Library Tutorial}
+\author{Zo\"e Richter}
+\date{March 2026}
+
+\usepackage{hyperref}
+
+\begin{document}
+\maketitle
+
+\section{Setup}
+Before you get started, you will need to do the following:
+\begin{itemize}
+\item Install perl
+\item Download the xsdirconvert.pl script from the \href{https://serpent.vtt.fi/docs/data/interaction_data.html#repository-interaction-data}{Serpent Data Repository}.
+\item ACE format data libraries for the nuclear data library you want to use:
+	\begin{itemize}
+	\item You will need the continuous energy cross section data (for example, \href{https://nucleardata.lanl.gov/ace/lib80x}{Lib80x}, which is based on ENDF/B-VIII.0).
+	\item You will need the thermal scattering data (for example, \href{https://nucleardata.lanl.gov/ace/endf80sab2}{ENDF80SaB2}, which is also based on ENDF/B-VIII.0)
+	\end{itemize}
+\item Set the \verb|SERPENT_DATA| environment variable in your .bashrc - this tutorial assumes you're setting it to \verb|/home/USER/PATH/TO/SERPENT/xsdata|.
+\end{itemize}
+
+Unpack the library data before moving on.  I would recommend creating a temp/ or scratch/ directory inside your Serpent xsdata directory to hold the compressed files and extract them into.  The tutorial will use \verb|scratch/|
+
+
+\section{Creating an xsdata file for Serpent}
+See the \href{https://serpent.vtt.fi/docs/installation/data_libraries.html#install-libraries}{Serpent docs on setting up data libraries} as well.
+
+In theory, the process for creating an xsdata file for Serpent is as simple as running \verb|perl xsdirconvert.pl input.xsdir > output.xsdata| on the xsdir file LANL provides with its ACE format libraries.  In practice, the provided file may not be exactly what you need out of the box, and you will need to add or remove some information.
+
+The xsdir file needs to take the general form of
+\begin{verbatim}
+datapath=
+atomic weight ratios
+ZAIDe1i1 [wt] ... ZAIDe1iI [wt] 
+.
+.
+.
+ZAIDeNi1 [wt] ... ZAIDeNiI [wt] 
+
+directory
+ZAIDi1 [wt] relative/path/to/isotope/acedata [parameters]
+.
+.
+.
+ZAIDiN [wt] relative/path/to/isotope/acedata [parameters]
+[therm mat]1 [wt] rel/path/to/therm/data [parameters]
+.
+.
+.
+[therm mat]N [wt] rel/path/to/therm/data [parameters]
+\end{verbatim}
+
+LANL may provide a more complex xsdir file for use, however, it will likely be much easier to create a xsdir by doing the following:
+
+\begin{itemize}
+\item Move into your \verb|xsdata/| directory, and make a new directory for holding the xsdata for the library you're making, e.g., \verb|endfX/| (which will be used as a placeholder name for this tutorial.  Inside \verb|endfX/|, create a directory called \verb|acedata/|
+\item Move \verb|xsdirconvert.pl| to \verb|xsdata/|
+\item Inside the uncompressed directories containing your ACE cross section data inside \verb|scratch/|, you should see a folder with the same name as the parent folder (such as \verb|Lib80x/| inside \verb|scratch/Lib80x/|), a file called \verb|xsdir|, and some miscellaneous files or directories for docs.  
+	\begin{itemize}
+	\item Move the sub-directory with the identical name into \verb|acedata/| for both the cross section library and the thermal scattering library.
+	\item Copy the \verb|xsdir| file from the cross section library into \verb|xsdata/| under a new name, such as \verb|endfX_combined.xsdir|.
+	\item On the last line of \verb|endfX_combined.xsdir|, add a new line, then add a line with 'directory', then move to a new line.  Copy the text in the thermal scattering \verb|xsdir| to the new line so you match the format laid out above.
+	\item Double check the relative paths to your data are correct (make sure you have \verb|path/to/acedata.file|, not \verb|/path/to/acedata.file|
+	\end{itemize}
+\item Move back to the top of \verb|endfX_combined.xsdir|.  Now you are adding the preamble:
+\begin{verbatim}
+datapath=PATH
+atomic weight ratios
+[rest of xsdir here]
+\end{verbatim}
+\item Now you need to set the data path.  It is the relative path to the directories containing the cross section and thermal scattering files.  So in the setup the tutorial uses, you would use \verb|datapath=endfX/acedata/|.
+\item Run \verb|perl xsdirconvert endfX_combined.xsdir > endfX_combined.xsdata|.  The result should be a new xsdata file with cross section entries first, then thermal scattering library entries.
+\end{itemize}
+
+And now you should be ready to go.  With your \verb|SERPENT_DATA| environment variable set to \verb|xsdata/|, you would set your acelib inside a Serpent2 input file with \verb|set acelib "endfX_combined.xsdata"|
+
+
+
+
+\end{document}