% Options for packages loaded elsewhere
\PassOptionsToPackage{unicode}{hyperref}
\PassOptionsToPackage{hyphens}{url}
%
\documentclass[
]{article}
\usepackage{amsmath,amssymb}
\usepackage{iftex}
\ifPDFTeX
  \usepackage[T1]{fontenc}
  \usepackage[utf8]{inputenc}
  \usepackage{textcomp} % provide euro and other symbols
\else % if luatex or xetex
  \usepackage{unicode-math} % this also loads fontspec
  \defaultfontfeatures{Scale=MatchLowercase}
  \defaultfontfeatures[\rmfamily]{Ligatures=TeX,Scale=1}
\fi
\usepackage{lmodern}
\ifPDFTeX\else
  % xetex/luatex font selection
\fi
% Use upquote if available, for straight quotes in verbatim environments
\IfFileExists{upquote.sty}{\usepackage{upquote}}{}
\IfFileExists{microtype.sty}{% use microtype if available
  \usepackage[]{microtype}
  \UseMicrotypeSet[protrusion]{basicmath} % disable protrusion for tt fonts
}{}
\makeatletter
\@ifundefined{KOMAClassName}{% if non-KOMA class
  \IfFileExists{parskip.sty}{%
    \usepackage{parskip}
  }{% else
    \setlength{\parindent}{0pt}
    \setlength{\parskip}{6pt plus 2pt minus 1pt}}
}{% if KOMA class
  \KOMAoptions{parskip=half}}
\makeatother
\usepackage{xcolor}
\usepackage{graphicx}
\makeatletter
\def\maxwidth{\ifdim\Gin@nat@width>\linewidth\linewidth\else\Gin@nat@width\fi}
\def\maxheight{\ifdim\Gin@nat@height>\textheight\textheight\else\Gin@nat@height\fi}
\makeatother
% Scale images if necessary, so that they will not overflow the page
% margins by default, and it is still possible to overwrite the defaults
% using explicit options in \includegraphics[width, height, ...]{}
\setkeys{Gin}{width=\maxwidth,height=\maxheight,keepaspectratio}
% Set default figure placement to htbp
\makeatletter
\def\fps@figure{htbp}
\makeatother
\usepackage{svg}
\setlength{\emergencystretch}{3em} % prevent overfull lines
\providecommand{\tightlist}{%
  \setlength{\itemsep}{0pt}\setlength{\parskip}{0pt}}
\setcounter{secnumdepth}{-\maxdimen} % remove section numbering
\ifLuaTeX
  \usepackage{selnolig}  % disable illegal ligatures
\fi
\IfFileExists{bookmark.sty}{\usepackage{bookmark}}{\usepackage{hyperref}}
\IfFileExists{xurl.sty}{\usepackage{xurl}}{} % add URL line breaks if available
\urlstyle{same}
%\hypersetup{
%  hidelinks,
%  pdfcreator={LaTeX via pandoc}}
%SJT: removed hidelinks option and added color links
\hypersetup{
  colorlinks=true,
  linkcolor=blue,
  urlcolor=blue,
  pdfcreator={LaTeX via pandoc}}

\author{}
\date{}

\begin{document}

%\hypertarget{ellipfor-doi}{%
%\section[ellipFor ]{\texorpdfstring{ellipFor
%\href{https://zenodo.org/doi/10.5281/zenodo.10071175}{\protect\includesvg{https://zenodo.org/badge/710577422.svg}}}{ellipFor DOI}}\label{ellipfor-doi}}

%%% SJT: took out Zenodo badge
\hypertarget{ellipfor-doi}{%
\section{ellipFor}\label{ellipfor-doi}}

Fortran software for the evaluation of Legendre elliptic integrals and
Jacobi elliptic functions for generalized input parameters.

\hypertarget{contents}{%
\subsection{Contents}\label{contents}}

\begin{enumerate}
\def\labelenumi{\arabic{enumi}.}
\tightlist
\item
  \protect\hyperlink{background}{Background}
\item
  \protect\hyperlink{variable-definitions}{Variable Definitions}
\item
  \protect\hyperlink{file-description}{File Description}

  \begin{enumerate}
  \def\labelenumii{\arabic{enumii}.}
  \tightlist
  \item
    \protect\hyperlink{ellipfor}{ellipFor/}
  \item
    \protect\hyperlink{ellipforsource}{ellipFor/source/}
  \item
    \protect\hyperlink{ellipforsourceexpected_data}{ellipFor/source/expected\_data/}
  \end{enumerate}
\item
  \protect\hyperlink{main-ellipfor-subroutines}{Main ellipFor
  Subroutines}
\item
  \protect\hyperlink{how-to-use}{How to Use}

  \begin{enumerate}
  \def\labelenumii{\arabic{enumii}.}
  \tightlist
  \item
    \protect\hyperlink{standalone}{Standalone}
  \item
    \protect\hyperlink{with-another-code}{With Another Code}
  \end{enumerate}
\item
  \protect\hyperlink{legal}{Legal}
\end{enumerate}

\hypertarget{background}{%
\subsection{Background}\label{background}}

This repository contains files and data for the ellipFor library
supporting the article ``Algorithm xxx: ellipFor, a Fortran software
library for Legendre elliptic integrals and Jacobi elliptic functions
with generalized input arguments'' by S.J. Trim and R.J. Spiteri.

\hypertarget{variable-definitions}{%
\subsection{Variable Definitions}\label{variable-definitions}}

\begin{itemize}
\tightlist
\item
  \(m\) = parameter
\item
  \(\phi\) = Jacobi amplitude
\item
  \(u\) = first argument of Jacobi elliptic functions
\item
  \(K(m)\) = complete Legendre elliptic integral of the first kind
\item
  \(E(m)\) = complete Legendre elliptic integral of the second kind
\item
  \(F(\phi|m)\) = incomplete Legendre elliptic integral of the first
  kind
\item
  \(E(\phi|m)\) = incomplete Legendre elliptic integral of the second
  kind
\item
  \(\text{sn}(u|m)\) = elliptic sine Jacobi elliptic function
\item
  \(\text{cn}(u|m)\) = elliptic cosine Jacobi elliptic function
\item
  \(\text{dn}(u|m)\) = delta amplitude Jacobi elliptic function
\end{itemize}

\hypertarget{file-description}{%
\subsection{File Description}\label{file-description}}

Headings that follow indicate directories in the ellipFor repository.
CAS (Computer Algebra System) generally refers to SageMath 10.4. In the
software development phase, SageMath values were confirmed against
values from the Wolfram Language Engine Community Edition (see
\protect\hyperlink{legal}{Legal}).

\hypertarget{ellipfor}{%
\subsubsection{\texorpdfstring{\texttt{ellipFor/}}{ellipFor/}}\label{ellipfor}}

\texttt{LICENSE}

\begin{itemize}
\tightlist
\item
  GPL-3.0 license info
\end{itemize}

\texttt{README.md}

\begin{itemize}
\tightlist
\item
  This documentation file (written in Markdown)
\end{itemize}

\hypertarget{ellipforsource}{%
\subsubsection{\texorpdfstring{\texttt{ellipFor/source/}}{ellipFor/source/}}\label{ellipforsource}}

\texttt{kind\_parameters.f90}

\begin{itemize}
\tightlist
\item
  Contains a module with portable kind parameters imported from the
  \texttt{iso\_fortran\_env} module
\end{itemize}

\texttt{elliptic.f90}

\begin{itemize}
\tightlist
\item
  Contains module procedures that evaluate Legendre elliptic integrals
  and Jacobi elliptic functions for generalized input parameter ranges
\item
  Input ranges were generalized by combining transformations with calls
  to routines from \texttt{ellipFor/source/xelbdj2\_all\_routines.f90}
  and \texttt{ellipFor/source/xgscd\_routines.f90}
\end{itemize}

\texttt{xelbdj2\_all\_routines.f90}

\begin{itemize}
\tightlist
\item
  Contains module procedures for the evaluation of associated elliptic
  integrals of the first, second, and third kinds
\item
  Assumes standard input parameter ranges
\item
  Adapted from routines by Toshio Fukushima (see
  \protect\hyperlink{legal}{Legal})
\end{itemize}

\texttt{xgscd\_routines.f90}

\begin{itemize}
\tightlist
\item
  Contains module procedures for the evaluation of the Jacobi elliptic
  functions sn, cn, and dn
\item
  Assumes standard input parameter ranges
\item
  Adapted from routines by Toshio Fukushima (see
  \protect\hyperlink{legal}{Legal})
\end{itemize}

\texttt{Makefile}

\begin{itemize}
\tightlist
\item
  Makefile for building the \protect\hyperlink{standalone}{standalone}
  version of ellipFor using gfortran or ifx
\item
  For use with GNU Make
\end{itemize}

\texttt{ellipFor\_test\_driver.f90}

\begin{itemize}
\tightlist
\item
  Test driver program for the \protect\hyperlink{standalone}{standalone}
  version of ellipFor
\item
  Evaluates \(K(m)\), \(E(m)\), \(F(\phi|m)\), \(E(\phi|m)\),
  \(\text{sn}(u|m)\), \(\text{cn}(u|m)\), and \(\text{dn}(u|m)\) for
  specified values of \(m\), \(\phi\), and \(u\)
\end{itemize}

\texttt{ellipFor\_test\_driver}

\begin{itemize}
\tightlist
\item
  Sample executable for the \protect\hyperlink{standalone}{standalone}
  driver program based on
  \texttt{ellipFor/source/ellipFor\_test\_driver.f90}
\item
  Results from building ellipFor using GNU Make via
  \texttt{ellipFor/source/Makefile} in the terminal
\item
  gfortran 14.2.0 was used
\end{itemize}

\texttt{ellipFor\_test\_driver.dat}

\begin{itemize}
\tightlist
\item
  Output file produced by executing
  \texttt{ellipFor/source/ellipFor\_test\_driver}
\item
  Contains data for \(K(m)\), \(E(m)\), \(F(\phi|m)\), \(E(\phi|m)\),
  \(\text{sn}(u|m)\), \(\text{cn}(u|m)\), and \(\text{dn}(u|m)\)
\end{itemize}

\texttt{test\_material\_driver.f90}

\begin{itemize}
\tightlist
\item
  Test material driver program that verifies the accuracy of ellipFor in
  detail
\item
  Tests \(K(m)\), \(E(m)\), \(F(\phi|m)\), \(E(\phi|m)\),
  \(\text{sn}(u|m)\), \(\text{cn}(u|m)\), and \(\text{dn}(u|m)\) against
  a large range of CAS reference values and a number of analytical
  values
\end{itemize}

\texttt{test\_material\_driver}

\begin{itemize}
\tightlist
\item
  Sample executable for the test material driver program based on
  \texttt{ellipFor/source/test\_material\_driver.f90}
\item
  Results from building ellipFor using GNU Make via
  \texttt{ellipFor/source/Makefile} in the terminal
\item
  gfortran 14.2.0 was used
\end{itemize}

\texttt{error\_complete.dat}

\begin{itemize}
\tightlist
\item
  Output file produced by executing
  \texttt{ellipFor/source/test\_material\_driver}
\item
  Contains relative error data compared to CAS for \(K(m)\) and \(E(m)\)
\item
  Used in section 6.1 in the article (see
  \protect\hyperlink{background}{Background})
\end{itemize}

\texttt{error\_incomplete.dat}

\begin{itemize}
\tightlist
\item
  Output file produced by executing
  \texttt{ellipFor/source/test\_material\_driver}
\item
  Contains relative error data compared to CAS for \(F(\phi|m)\) and
  \(E(\phi|m)\)
\item
  Used in section 6.2 in the article (see
  \protect\hyperlink{background}{Background})
\end{itemize}

\texttt{error\_functions.dat}

\begin{itemize}
\tightlist
\item
  Output file produced by executing
  \texttt{ellipFor/source/test\_material\_driver}
\item
  Contains relative error data compared to CAS for \(\text{sn}(u|m)\),
  \(\text{cn}(u|m)\), and \(\text{dn}(u|m)\)
\item
  Used in section 6.3 in the article (see
  \protect\hyperlink{background}{Background})
\end{itemize}

\hypertarget{ellipforsourceexpected_data}{%
\subsubsection{\texorpdfstring{\texttt{ellipFor/source/expected\_data/}}{ellipFor/source/expected\_data/}}\label{ellipforsourceexpected_data}}

\texttt{CAS\_complete.dat}

\begin{itemize}
\tightlist
\item
  Contains CAS reference data for complete Legendre elliptic integrals
\item
  Used by \texttt{ellipFor/source/test\_material\_program} to verify
  accuracy
\item
  Used in section 6.1 of the article (see
  \protect\hyperlink{background}{Background})
\end{itemize}

\texttt{CAS\_incomplete.dat}

\begin{itemize}
\tightlist
\item
  Contains CAS reference data for incomplete Legendre elliptic integrals
\item
  Used by \texttt{ellipFor/source/test\_material\_program} to verify
  accuracy
\item
  Used in section 6.2 of the article (see
  \protect\hyperlink{background}{Background})
\end{itemize}

\texttt{CAS\_functions.dat}

\begin{itemize}
\tightlist
\item
  Contains CAS reference data for Jacobi elliptic functions
\item
  Used by \texttt{ellipFor/source/test\_material\_program} to verify
  accuracy
\item
  Used in section 6.3 of the article (see
  \protect\hyperlink{background}{Background})
\end{itemize}

\texttt{ellipFor\_test\_driver\_OG.dat}

\begin{itemize} %%% SJT: adjusted for word wrap
\tightlist
\item
  Expected output from \texttt{ellipFor/source/ellipFor\_test\_driver}
  corresponding to \texttt{ellipFor/source/ellipFor\_test\_driver.dat}
\item
  Assumes the original values of \(m\), \(\phi\), and \(u\) defined in
  \texttt{ellipFor/source/} \texttt{ellipFor\_test\_driver.f90} are used
\item
  \texttt{ellipFor/source/ellipFor\_test\_driver} checks output against
  this reference data automatically (if desired -- see
  \protect\hyperlink{standalone}{Standalone})
\item
  Computed using gfortran 14.2.0
\end{itemize}

\texttt{args\_complete\_elliptic\_integrals.dat}

\begin{itemize}
\tightlist
\item
  Randomized values of \(m\) used for testing of ellipFor's \(K(m)\) and
  \(E(m)\) values
\item
  Used by \texttt{ellipFor/source/test\_material\_program} to verify
  accuracy
\item
  Used in section 6.1 of the article (see
  \protect\hyperlink{background}{Background})
\end{itemize}

\texttt{args\_incomplete\_elliptic\_integrals.dat}

\begin{itemize}
\tightlist
\item
  Randomized combinations of \(\phi\) and \(m\) used for testing of
  ellipFor's \(F(\phi|m)\) and \(E(\phi|m)\) values
\item
  Used by \texttt{ellipFor/source/test\_material\_program} to verify
  accuracy
\item
  Used in section 6.2 of the article (see
  \protect\hyperlink{background}{Background})
\end{itemize}

\texttt{args\_Jacobi\_elliptic\_functions.dat}

\begin{itemize}
\tightlist
\item
  Randomized combinations of \(u\) and \(m\) used for testing of
  ellipFor's \(\text{sn}(u|m)\), \(\text{cn}(u|m)\), and
  \(\text{dn}(u|m)\) values
\item
  Used by \texttt{ellipFor/source/test\_material\_program} to verify
  accuracy
\item
  Used in section 6.3 of the article (see
  \protect\hyperlink{background}{Background})
\end{itemize}

\hypertarget{main-ellipfor-subroutines}{%
\subsection{Main ellipFor Subroutines}\label{main-ellipfor-subroutines}}

\texttt{complete\_elliptic\_integrals(m,Fc,Ec)}

\begin{itemize}
\tightlist
\item
  Evaluate \(K(m)\) and \(E(m)\)
\item
  Input: \texttt{m} = \(m \in \mathbb{R}\) with \(m \geq 0\)
\item
  Output: \texttt{Fc} = \(K(m) \in \mathbb{C}\) and \texttt{Ec} =
  \(E(m) \in \mathbb{C}\)
\end{itemize}

\texttt{incomplete\_elliptic\_integrals(phi,m,F,E)}

\begin{itemize}
\tightlist
\item
  Evaluate \(F(\phi|m)\) and \(E(\phi|m)\)
\item
  Input: \texttt{phi} = \(\phi \in \mathbb{R}\), and \texttt{m} =
  \(m \in \mathbb{R}\) with \(m \geq 0\)
\item
  Output: \texttt{F} = \(F(\phi|m) \in \mathbb{C}\) and \texttt{E} =
  \(E(\phi|m) \in \mathbb{C}\)
\end{itemize}

\texttt{Jacobi\_elliptic\_functions(u,m,sn,cn,dn)}

\begin{itemize}
\tightlist
\item
  Evaluate \(\text{sn}(u|m)\), \(\text{cn}(u|m)\), and
  \(\text{dn}(u|m)\)
\item
  Input: \texttt{u} = \(u \in \mathbb{C}\), and \texttt{m} =
  \(m \in \mathbb{R}\) with \(m \geq 0\)
\item
  Output: \texttt{sn} = \(\text{sn}(u|m) \in \mathbb{C}\), \texttt{cn} =
  \(\text{cn}(u|m) \in \mathbb{C}\), and \texttt{dn} =
  \(\text{dn}(u|m) \in \mathbb{C}\)
\end{itemize}

All subroutine arguments are of double precision type
(\texttt{kind=real64} from the \texttt{iso\_fortran\_env} intrinsic
module). Note that the source code for the above routines is in
\texttt{ellipFor/source/elliptic.f90} and examples for calling the
subroutines are in \texttt{ellipFor/source/ellipFor\_test\_driver.f90}.

\hypertarget{how-to-use}{%
\subsection{How to Use}\label{how-to-use}}

\hypertarget{standalone}{%
\subsubsection{Standalone}\label{standalone}}

%%SJT: changed for word wrap
Can be used to generate values for \(K(m)\), \(E(m)\), \(F(\phi|m)\),
\(E(\phi|m)\), \(\text{sn}(u|m)\), \(\text{cn}(u|m)\), and
\(\text{dn}(u|m)\) using the driver program
\texttt{ellipFor/source/} \texttt{ellipFor\_test\_driver.f90}.

\begin{enumerate}
\def\labelenumi{\arabic{enumi}.}
\tightlist
\item
  Specify the desired \(m\), \(\phi\), and \(u\) in
  \texttt{ellipFor/source/ellipFor\_test\_driver.f90}

  \begin{itemize}
  \tightlist
  \item
    Examples are shown in
    \texttt{ellipFor/source/ellipFor\_test\_driver.f90}
  \item
    Note: this program tests output assuming the original values of
    \(m\), \(\phi\), and \(u\) are used

    \begin{itemize}
    \tightlist
    \item
      Warnings will occur if custom values are used
    \item
      To disable these warnings, set \texttt{test\_output=.false.} near
      line 10 of \texttt{ellipFor/source/ellipFor\_test\_driver.f90}\\
    \end{itemize}
  \end{itemize}
\item
  Build the code using GNU Make with \texttt{ellipFor/source/Makefile}

  \begin{itemize}
  \tightlist
  \item
    Navigate to \texttt{ellipFor/source} directory in the terminal
  \item
    Use \texttt{make} command in the terminal with the rule for the
    compiler of choice (gfortran or ifx)

    \begin{itemize}
    \tightlist
    \item
      Linux/Mac/Windows: \texttt{\$\ make\ gfortran} or
      \texttt{\$\ make\ ifx}
    \item
      Note for Intel oneAPI users: the setvars script must be applied
      before running \texttt{make} (e.g.,
      \texttt{\$\ source\ /opt/intel/oneapi/setvars.sh})
    \item
      Intel oneAPI version 2025.0.1 or later is recommended
    \item
      gfortran 14.2.0 or later is recommended
    \item
      GNU Make 4.3 or later is recommended
    \end{itemize}
  \item
    the driver programs \texttt{ellipFor/source/ellipFor\_test\_driver}
    and \texttt{ellipFor/source/test\_material\_driver} will be produced

    \begin{itemize}
    \tightlist
    \item
      Note that \texttt{ellipFor/source/test\_material\_driver} can be
      used to automatically test all ellipFor features in detail
    \end{itemize}
  \item
    if desired, the command \texttt{\$\ make\ clean} will remove build
    objects while retaining executables
  \end{itemize}
\item
  Run \texttt{ellipFor/source/ellipFor\_test\_driver} from the command
  line

  \begin{itemize} %%%SJT: word wrap
  \tightlist
  \item
    Linux/Mac: \texttt{\$\ ./ellipFor\_test\_driver}
  \item
    Windows Command Prompt: \texttt{\$\ start\ ellipFor\_test\_driver}
  \item
    This will produce data for \(K(m)\), \(E(m)\), \(F(\phi|m)\),
    \(E(\phi|m)\), \(\text{sn}(u|m)\), \(\text{cn}(u|m)\), and
    \(\text{dn}(u|m)\) in the output file
    \texttt{ellipFor/source/} \texttt{ellipFor\_test\_driver.dat}
  \end{itemize}
\end{enumerate}

\hypertarget{with-another-code}{%
\subsubsection{With Another Code}\label{with-another-code}}

Can be used to calculate \(K(m)\), \(E(m)\), \(F(\phi|m)\),
\(E(\phi|m)\), \(\text{sn}(u|m)\), \(\text{cn}(u|m)\), and
\(\text{dn}(u|m)\) from within another code. These instructions presume
that the other code is written in Fortran. The following steps are
guidelines only. The precise procedure may depend on the particular code
used.

\hypertarget{fortran}{%
\paragraph{Fortran}\label{fortran}}

\begin{enumerate}
\def\labelenumi{\arabic{enumi}.}
\tightlist
\item
  Insert calls to the subroutines for Legendre elliptic integrals and
  Jacobi elliptic functions within the source of the other code
  (referred to as \texttt{other\_code.f90} in the following examples)
  where necessary

  \begin{itemize} %%%SJT: word wrap
  \tightlist
  \item
    Examples of how to call the subroutines are shown in
    \texttt{ellipFor/source/} \texttt{ellipFor\_test\_driver.f90}\\
  \end{itemize}
\item
  Link the f90 files from the \texttt{ellipFor/source} folder named
  \texttt{kind\_parameters.f90}, \texttt{xelbdj2\_all\_routines.f90},
  \texttt{xgscd\_routines.f90}, and \texttt{elliptic.f90} to the source
  for the other code

  \begin{itemize}
  \tightlist
  \item
    \texttt{ellipFor/source/Makefile} can be used as a template to build
    \texttt{other\_code.f90} with the ellipFor libraries and build the
    executable

    \begin{itemize}
    \tightlist
    \item
      substitute references to \texttt{ellipFor\_test\_driver} with
      \texttt{other\_code} in a copy of the \texttt{Makefile} provided
    \item
      customize as desired (e.g., compiler options, etc.)
    \end{itemize}
  \item
    use \texttt{\$\ make\ gfortran} or \texttt{\$\ make\ ifx} in the terminal to build the executable
    \texttt{other\_code} with the desired compiler
  \item
    Note for Intel oneAPI users: the setvars script must be applied
    before running \texttt{make} (e.g.,
    \texttt{\$\ source\ /opt/intel/oneapi/setvars.sh})
  \item
    Intel oneAPI version 2025.0.1 or later is recommended
  \item
    gfortran 14.2.0 or later is recommended
  \item
    GNU Make 4.3 or later is recommended\\
  \item
    Warning: Duplicate variable/routine names may occur

    \begin{itemize}
    \tightlist
    \item
      Resolve any related compiler errors
    \item
      Verify that the arguments of subroutine calls correspond to the
      correct values and data types
    \end{itemize}
  \end{itemize}
\item
  Run the code executable (\texttt{other\_code}) as usual
\end{enumerate}

\hypertarget{legal}{%
\subsection{Legal}\label{legal}}

This repository is subject to the GPLv3 license
(\texttt{ellipFor/LICENSE}).

%%SJT: added url package calls
The routines contained within
\texttt{ellipFor/source/xelbdj2\_all\_routines.f90} and
\texttt{ellipFor/source/xgscd\_routines.f90} are adapted from routines
by Toshio Fukushima available under the CC BY-SA 4.0 license. Original
versions of these routines can be found at
\url{http://dx.doi.org/10.13140/RG.2.2.27011.66085} and
\url{https://www.researchgate.net/publication/233903220\_xgscdtxt\_Fortran\_program\_package\_to\_compute\_the\_Jacobian\_elliptic\_functions\_snum\_cnum\_dnum}.

Some initial software testing in the development phase was performed
using the Wolfram Language 14.1.0 Engine Community Edition. The
production version of ellipFor does not utilize the Wolfram Language
Engine.

\end{document}
