\documentclass{article}
\begin{document}
\section{Machine Learning}

A tangent from this article, I will briefly talk about what is machine learning.

\paragraph{Making a Prediction} Machine Learning is all about making a prediction, by looking at already curated data. \textit{We show the someone 100 pictures of rabbits and explained to them that they are rabbits, can they tell if the next picture of an animal is a rabbit?}

Same idea we have here, we show the machine hundred of beatmaps, we tell the machine how difficult all of them are (according to score regression). Can the machine predict the difficulty of the next one? The answer is yes, but it won't be accurate!

\subsection{Valid input}

Think about a neural network, you've most likely seen one, it's circle(s) connected to more circle(s), in the end, there will be circle(s) that tell you something. Each circle represents a \textbf{neuron}.

Each neuron holds a numeric value, we need to put a value in each of these neurons. Ignoring Timing Points and Scroll Speed Changes, how do we squeeze a beatmap into these neurons?

\paragraph{Hit Object Neurons} Remember that a neuron will only work with numeric values, what do you want to have in the neuron that represents a Hit Object? Putting either the \textbf{offset} or \textbf{column} will not work because both are vital!

\paragraph{Column Neurons} It is a possible idea, to have a neuron for \textbf{each millisecond}, then put \textbf{column value} on those neurons that match the \textbf{offset}. We run into a glaring issue where input neurons will stretch to the \textbf{hundred thousands}, computational power required on this scale would be too high. If we decide to \textbf{bin} the offsets (binning is the act of grouping things together to reduce the number of fields) to \textbf{100ms} steps, it might prove to be too inaccurate and prone to abuse.

\subsubsection{Subdivide the Issue}

\textbf{Does it have to be the whole map?}

It doesn't! That's what we are doing for this research, we don't look at the whole map, we look at parts of it, the inner mechanisms, the \textbf{patterns}! Sure, even though the whole map must be present to calculate difficulty but consider this:

For each note in the map, the player will have to play \textbf{a pattern} (the input) and produce \textbf{a feedback} (the output). If we can parse a pattern and get an input, we should be able to teach the machine the expected output, and predict with it afterwards.

\paragraph{Patterns to Input} In the following sections we will be discussing how we can task the machine to learn what patterns are easy and which are harder

\paragraph{Output to a Single Rating} We can get output for each specific pattern, but how do we represent the difficulty as \textbf{one number?} Do we rate it by the average, maximum or median? We will discuss those later.

\subsection{Expected output}

Just like the example in \textbf{valid inputs}, we have to tell the machine that \textbf{that picture is of a cat}, else it doesn't know what is and what isn't.

In this case, we can relate back to $Accuracy$ (from the player), where it is the most reliable source of difficulty rating as explained earlier.

One good source of this data is to grab replays (not scores!), because we can then analyse small parts of it in order to match with the input.

\subsection{Differing and Multiple Accuracies}

\paragraph{Multiple Players} There will be multiple replays, there isn't a replay that is all-encompassing (it'll be too biased!). So we need to create a middle-ground for these data.

\paragraph{Different Players} Not everyone will perform similarly for every beatmap, there will be discrepancies. We can't just take the accuracy as a raw value and run a function through them, we will have to make use of relative accuracies instead of raw accuracies before finding the "ideal" replay.

\subsection{Differing Keys}

Is it possible to mash all keys together, to form a model that works for 9 keys? I believe that it can be done, however, anything \textbf{beyond 7 keys} will be arguably bad in rating. This is mainly due to the lack of beatmaps in that category and also a lack of players. So how is it done?

\paragraph{Column to Action} Is a small keyword I would use in my script to signify, map this column to the finger used in real life. To simply put, imagine if all columns were named by their most commonly pressed finger, that's the process I'm using to funnel all of them together.

\subsection{Recap}

To sum it up

\begin{enumerate}
	\item Grab beatmap from server
	\item Grab replay from server
	\item Convert beatmap into simpler bite-sized patterns
	\item Convert replay to a list of accuracies for each note
	\item For each pattern, there's an expected accuracy
	\item Teach that concept to the machine and create a model
	\item Predict accuracies with the model
	\item Give the map a rating according to the expected accuracies
\end{enumerate}

\end{document}


\chapter{Orbital workflow} \label{workflow}

To appreciate the scope of the design and implementation Skylab, we detail the major work processes that the various user roles need to accomplish during an iteration (one year's cohort) of Orbital.  We describe the workflow for Orbital students first, and circle back to describe the workflows of other supporting roles in the process.

\section{Registration} \label{registration}

To enroll in the Orbital program, students will need to register in Skylab first. When a user first logs into Skylab, a \textit{User} object will be created for user. And since it is the first time the user logs in to the system, there is no existing role assigned to current user in current cohort. Then Skylab assumes that the user is trying to register and therefore a link to registration will be displayed. This workflow works for most users who are students in Orbital program. As for roles like \textit{Adviser}, \textit{Mentor} and \textit{Tutor}, admin users will create those roles manually. This is because there are only a few such roles and they have higher privileges and therefore creation of such roles should definitely be controlled by admin users.

For students' registration, after a user click the registration link, a form consisting of different questions will be presented to the user. Among these questions, several are to get a sense of what sort of interests the user has for the project over the summer. The user is supposed to select interested topics from different categories like programming language, web framework or mobile platform, IDE or text editor, e-commerce, cloud platform, purpose, embedded system, game framework, content management system and audience. These information will be recorded for match-making among students who need to find a teammate in Skylab.

After completing the registration form, if the user already has a teammate in mind, he/she can send an invitation to the potential teammate to form a team. Some users, on the other hand, do not have anyone to partner with for Orbital yet and a match-making algorithm will be run offline by admin user based on the interested topics they have selected during registration. An illustration of the whole workflow is as Figure~\ref{fig:RegistrationWorkflow}.

\begin{figure}[h]
  \centering
  \includegraphics[width=\textwidth]{Images/Skylab_Registration_Workflow.png}
  \caption{Illustration of registration workflow in Skylab}
  \label{fig:RegistrationWorkflow}
\end{figure}

\subsection{Match making algorithm}

For students who do not have potential teammates at the time of registration, we will run a matching making algorithm based on the interested topics recorded in registration form submission. The algorithm composes of mainly two steps:

\begin{itemize}
  \item Calculate inverse document frequency of tags: inverse document frequency is to reflect how rare a term is in the corpus\cite{citationir}. In Skylab's match making's case, a document is a user's selection of interested topics, or tags; the corpus is the collection of users' interested topic sets; a term is a tag in a users' selections. If a term(tag) is rare among registration form results, we will be more confident that if both students choose this term and they will have higher chance of forming a team. The formula of calculation is as Formula~\ref{eq:idf}.

  \begin{equation}
    idf(t,D) = \log \frac{N}{\{ d \in D : t \in d \} + 1} \
    \label{eq:idf}
  \end{equation}

  with \(N\) as total number of documents in the corpus \( N = |D| \) and \(\{ d \in D : t \in d \}\) as number of documents where the term \(t\) appears\cite{citationir}.

  \item Construct a vector space model based on students' selected tags and each tag's weight calculated in previous step and calculate similarity(cosine) of different students. The formula for calculating cosine of two vectors is as Formula~\ref{eq:veccos}\cite{citationvecspacemodel}.

  \begin{equation}
    \cos\theta  = \frac{d_2 \cdot q}{ \norm{d_2} \norm{q} } \
    \label{eq:veccos}
  \end{equation}

  And we represent a user's interested topics with tags' weights and the similarity between 2 users will be the cosine between 2 vectors representing the 2 users. The formula for calculating cosine of two vectors is as Formula~\ref{eq:similarity}\cite{citationvecspacemodel}.

  \begin{equation}
    sim(d_j, q)  = \frac{d_j \cdot q}{ \norm{d_j} \norm{q} } \ = \frac{sum_{i=1}^{N} \omega_{i,j} \omega_{i,q}}{ \sqrt{sum_{i=1}^{N} \omega_{i,j}^2} \sqrt{sum_{i=1}^{N} \omega_{i,q}^2}} \
    \label{eq:similarity}
  \end{equation}

\end{itemize}

As matching making only needs to be run once before Orbital officially starts for those students who do no have a team yet, the algorithm is currently designed to run offline as a rake task. Currently it is only for students but in the future with recoding of mentors' and advisers' interested tags, this algorithm can be easily extended to students and mentors or students and advisers as well.

\section{Submission} \label{submission}

Students in Orbital are supposed to report their progress regarding their project at each milestone via \textit{Submission}. Basically a submission contains 3 parts:

\begin{itemize}
  \item README: highlights what are the changes and new features in the project.
  \item Project Log: a summary of work done during the phase and time used for each task.
  \item Video link: a link to a video introducing the project to evaluators.
\end{itemize}

As the structure of \textit{README} and \textit{Project Log} is free and we should allow creativity of students when it comes to describing their own projects, we decided to support rich text for submissions and there are some issues coming along with this decision such as SQL injection and XSS attacks. What is more, during use of Skylab, many good suggestions regarding user experience were brought up by students and advisers, like uploading of images and auto-expanding textareas during editing.

\subsection{Handling of rich text}

We used TinyMCE to support rich text editing feature in Skylab as it is a very popular WYSIWYG(what-you-see-is-what-you-get) editor with a rich set of features\cite{citationtinymce}. There are some libraries with markdown syntax supported such as EpicEditor, Vue.js and Hallo.js which are more lightweight. However, as Skylab is built for freshmen to get more hands-on experience with coding, we do not expect students to be equipped with much prior knowledge such as markdown syntax. In the contrast, markup based editors such as TinyMCE and CKEditor do not require any learning and are easily to get started with. What is more, the large community using TinyMCE has made various plug-ins available for different features. There are also quite good resources online about integrating TinyMCE editor in a Rails project. Therefore, we decided to use TinyMCE for \textit{Submissions}' rich text support.

One particular disadvantage of using TinyMCE is that the size of this editor is pretty large and loading of the page will be slowed down because of it. Therefore, TinyMCE related resources is only loaded if the page is requiring rich text editing. This is done by configuration to disable auto loading of all JavaScript, which is the default behavior of Rails. In this way, most pages can be loaded within a very short time. What is more, assets whose names start with ``tinymce'' are set to expire in a year to reduce frequent requesting of such resources from clients --- which basically means students only need to load these resources once in one year.

Rails has built-in checking against SQL injection attacks and therefore Skylab is safe from such attacks when storing submissions' contents\cite{citationrorsecurity}. However, there is still currently a known bug in the implementation when it comes to viewing of submissions. As contents like \textit{README} and \textit{Project Log} should be rendered as rich text, it is possible for students to perform XSS attacks by injecting executable JavaScript code in the submission. This sort of vulnerabilities will be fixed in the future.

\subsection{Usability}

Skylab is a software engineering project and therefore improvements in user experience is one key part when it comes to implementation. During the use of Skylab, many suggestions were brought up by students and advisers about usability. And by addressing these issues, Skylab is serving users better with a smoother user experience.

\subsubsection{Target Milestone Selection}

When Skylab was used for the first time, students were expected to choose the target milestone, which the submission is for. However, many students reported that it is just a redundant step as every time they will only submit to the currently active milestone. After hearing this, a quick fix of automatically selecting the current milestone for students using JavaScript functions was done, while the manual selection is still possible. And then during the \textit{Adviser Focus Group Meeting}, some advisers further pointed out that the selection should not even be presented to users as it is of completely no use and therefore the whole selection was completely removed from Skylab after the meeting by moving the task to the backend logic.

\subsubsection{Rich Text Editing}

As quite some students want to insert image to \textit{README} sections, an image uploading feature was soon added to submission page for users' convenience. Behind the scene Skylab is using a third-party API from Imgur. This was done mainly for 2 reasons: using Imgur is relatively easy to implement; we can also avoid heavy server load due to file uploading and possible attacks in uploaded files.

Another improvement over user experience is auto expanding of TinyMCE editing area as feedback from students mentioned that their \textit{README} and \textit{Project Log} are usually quite lengthy. So auto expanding would not require too much scrolling during creating/editing a submission.

\section{Peer Evaluation} \label{peerevaluation}

 After students have submitted to milestones, peer evaluation process can begin. Teams will look through evaluated teams' projects and submissions and then evaluate their performance in \textit{PeerEvaluation}, which is a very important component in determining whether the evaluated teams can pass Orbital or not. Although there are different questions for each peer evaluation, all evaluations contains essentially 2 parts:

 \begin{itemize}
  \item Public: a section with general feedback on how well the evaluated team has done and the response will be viewed by target team with evaluator team name available.
  \item Private: a section with critiques and overall rating. Critiques will only be viewed by target team without any evaluator team information while overall rating is only for grading purpose and not viewable by target teams.
\end{itemize}

\subsection{Loading of Peer Evaluation templates}

When Skylab was first developed, the public part of a \textit{PeerEvaluation} templates will be one HTML form and the private part is another one. This means all questions in the public part are coded in one predefined html template and same goes for questions in private part.

This approach does not seem to have much problem at first and it really served Skylab's purpose well by delivering perfectly workable features in time. However, since questions are different for different milestones, separate templates have to be created for each new milestone. And when user wants to view/submit/edit a \textit{PeerEvaluation}, the corresponding templates will have to be loaded based on properties of the milestone. In this way, the system is not really open to extension and clearly it violates Open-Close principle. After realizing this, a system for dynamically creating questions has been implemented for \textit{Feedback} and migration of \textit{PeerEvaluations} to the survey-template-and-questions based system has been done as well. A more detailed description for how the dynamic loading of questions is in Section~\ref{feedback}.

\section{Feedback} \label{feedback}

\textit{Feedback} is for evaluated teams to evaluate the \textit{PeerEvaluations} they have received and it is also a very important component in determining whether the evaluator team can pass or not. After realizing the lack of extensibility in the design for \textit{PeerEvaluations} and with more time available for implementation of \textit{Feedback}, a survey-template-and-questions system has been set up, which made the system open to extensions for more questions and even question types.

\subsection{Survey-template-and-questions system}

The basic flow when a request to create a \textit{Feedback} is illustrated in Figure~\ref{fig:FeedbackFlow}.

\begin{figure}[h]
  \centering
  \includegraphics[width=0.8\textwidth]{Images/Skylab_Feedback_Flow.png}
  \caption{Flow of a feedback creation process}
  \label{fig:FeedbackFlow}
\end{figure}

So when a student clicks the button to create feedback, \textit{FeedbacksController}'s \textit{new} action will be invoked and inside the method, the corresponding \textit{SurveyTemplate} and all \textit{Questions} belonging to the \textit{SurveyTemplate} will be sent to view. Then instruction for the \textit{Feedback} and all questions will be rendered as response to the student. After the student completed and pressed submit button, responses to all questions will be sent to server and a Feedback instance containing all submitted responses will be created.

There currently 4 types of \textit{Questions} in the system as Figure~\ref{fig:SkylabQuestions}:

\begin{itemize}
  \item \textbf{TextQuestion}: a text question which will be rendered in the format of textarea and text-based responses are expected.
  \item \textbf{RichTextQuestion}: a rich text question which will be rendered in the format of TinyMCE editable area and rich text is expected as response.
  \item \textbf{MultipleChoiceQuestion}: a multiple choice question which will be rendered as radio buttons followed by option descriptions and one option value is expected.
  \item \textbf{MultipleSelectQuestion}: a multiple choice question which will be rendered as a select element with ``multiple'' enabled with each option as one choice of selection.
\end{itemize}

\begin{figure}[h]
    \centering
    \includegraphics[width=\textwidth]{Images/Skylab_Questions.png}
    \caption{All types of questions in Skylab}
    \label{fig:SkylabQuestions}
\end{figure}

All types of question will have \textit{title}, \textit{instruction}, \textit{content}, \textit{extras} and \textit{question\_type} and each type of question will have its own way of rendering and validation. In this way, adding new types of questions can simply be done via creating a new question model with its own rendering and validation methods.


% Chapter Template

\chapter{Topical n-grams model} % Main chapter title

\label{topicalngram} % Change X to a consecutive number; for referencing this chapter elsewhere, use \ref{ChapterX}

\lhead{Chapter 5. \emph{Topical n-grams model}} % Change X to a consecutive number; this is for the header on each page - perhaps a shortened title

%----------------------------------------------------------------------------------------
%	Introduction
%----------------------------------------------------------------------------------------

Joint sentiment and topic models have been used to tackle this classification problem. Despite having a hierarchical structure, these generative models have
a bag of words assumption. Due to this fact, they tend to misclassify texts having sentiment in the form of phrases. \textit{LDA} and it's extensions don't
work properly with phrases. To tackle this situation, we propose an unsupervised approach to sentiment analysis using the topical n-grams model which has been
shown to be effective with phrases. We train the topical n-grams model using two topics i.e., positive, and negative, list of positive and negative
words, and rules to detect positive and negative phrases. New documents are then classified using this trained model. The system gives better results than the
existing Joint Sentiment Topic model. We also propose an approach to generate a list of positive and negative words using LDA based on our observations reported in~\cref{experiments}.

\section{Introduction}

In the next section, we will discuss the topical n-gram model in detail.

\section{Topical n-grams model}

n-gram phrases (or collocations) are fundamentally important in many areas of natural language processing (e.g., parsing, machine translation and information retrieval).
Phrase as the whole carries more information than the sum of its individual components, thus it is much more crucial in determining the topics of document collections
than individual words \citep*{wang2005note}. However, most of the topic models assume that words are generated independently to each other, i.e., under the bag of words
assumption. The possible over complicacy caused by introducing phrases makes these topic models completely ignore them. It is true that these models with the bag of words
assumption have enjoyed a big success, and attracted a lot of interests from researchers with different backgrounds. A topic model considering phrases would be more
useful in certain applications. Topical n-grams model is one such generative model. It's generative process is explained as follows,

\begin{enumerate}
 \item Draw multinomial \(\phi_z\) from a Dirichlet prior \(\beta\);
 \item Draw binomial \(\psi_z\) from a Beta prior \(\gamma\);
 \item Draw multinomial \(\sigma_{zw}\) from a Dirichlet prior \(\delta\);
 \item For each document d, draw a multinomial \(θ^{(d)}\) from a Dirichlet prior \(\alpha\); then for each word \({w_i}^{(d)}\) in document \(d\),
    \begin{enumerate}
     \item Draw \({x_i}^{(d)}\) from binomial \(\psi_{{w_{i-1}}^{(d)}}\);
     \item Draw \({z_i}^{(d)}\) from multinomial \(\theta_{(d)}\);
     \item Draw \({w_i}^{(d)}\) from multinomial \(\sigma_{{w_{i-1}}^{(d)}}\) if \({x_i}^{(d)} = 1\); else draw \({w_i}^{d}\) from multinomial \(\phi_{{z_i}^{(d)}}\).
    \end{enumerate}
\end{enumerate}

The main point to infer from this generative process is that the topic assignments for the two terms in a bigram are not required to be identical. In the description of
topic n-grams given in \citep*{wang2005note}, they have used the topic of the last term as the topic of the phrase. But in our experiments, we have used certain rules
as prior information to assign topics to a phrase initially.

\includegraphics[width=\textwidth]{topicalngram.png}
\begin{center}
 Figure 5.1 Topical n-grams model
\end{center}

\subsection{Inferencing}

Gibbs sampling is used to conduct approximate inference in this paper. During Gibbs sampling, we draw the topic assignment \(z_i\) and the bigram status \(x_i\)
iteratively for each word \(w_i\) according to the following conditional probability distribution:

\begin{equation}
p(z_i,x_i | z_{-i},w_{-i},w,\alpha,\beta,\gamma,\delta) \propto
\frac{\gamma_{x_i} + p_{z_{i-1}w_{i-1}x_i}}{\sum_{k=0}^1 {(\gamma_k+p_{z_{i-1}}w_{i-1}k)}} {(\alpha_{z_i} + q_{d_{z_i}})} \times \left\{
  \begin{array}{l l}
    \frac{\beta_{w_i} + n_{z_i w_i}}{\sum_{v=1}^V {(\beta_v+n_{z_i v})}} & \quad \text{if $x_i$ is even}\\
    \frac{\delta_{w_i} + m_{z_i w_{i-1} w_i}}{\sum_{v=1}^V {(\delta_v + m_{z_i w_{i-1} v})} } & \quad \text{if $n$ is odd}
  \end{array} \right.
\end{equation}

where,

\(z_{-i}\) denotes the topic assignments for all word tokens except word \(w_i\), \\
\(x_{-i}\) represents the bigram status for all tokens except word \(w_i\), \\
\(n_{zw}\) represents how many times word \(w\) is assigned into topic \(z\) as a unigram, \\
\(m_{zwv}\) represents how many tmes word \(v\) is assigned as the second term of a bigram given the previous word \(w\), \\
\(p_{zwk}\) denotes how many times the status variable \(x\) equals \(k\) given the previous word \(w\) and previous word's topic \(z\), and \\
\(q_{dz}\) represents how many times a word is assigned to topic \(z\) in document d.

In next section, we will explain the use of topical n-grams model for sentiment analysis

\section{Topical n-grams model for Sentiment Analysis}

To make use of topical n-grams model for sentiment classification, we use an approach similar to using LDA for sentiment classification.

\begin{itemize}
 \itemsep0em
 \item Set number of topics equal to 2.
 \item Remove stop-words.
 \item Remove objective words as they won't affect sentiment. The objective words in this case do not include the negation words like \textit{doesn't,
 won't, no}, etc. This is to ensure that we can catch negation of polarity when they are used with subjective words.
 \item Apply Gibbs Sampling with prior. The prior used in this case is more sophisticated and can handle both words and phrases. In case of words, if
 is not present in a bigram then simply use a list of positive and negative words to assign positive or negative topic. If the word is present in a
 bigram then assign it the topic of the bigram. There are some rules to detect and assign topics to bigrams which are explained next.
 \item Use the trained model to classify a new document as positive or negative.
\end{itemize}

\subsubsection*{Rules for Topic assignment of phrases}

At present, our rules are restricted to bigrams. We plan to extend them as explained in Section~\cref{conclusions}.
In the following rules, we mean topic when we say polarity. The use of polarity makes it easy to understand
the rules as they are concerned with subjectivity.

\begin{enumerate}
 \itemsep0em
 \item If the first word in the bigram is a negation word and the second word is subjective then the polarity
 of the bigram is opposite to the polarity of the second word. \\
 \textbf{Examples:} \textit{won't like, won't regret, etc.}. Here, \textit{won't like} is assigned negative
 polarity and \textit{won't regret} is assigned positive polarity.
 \item If both the words in the bigram are subjective then are two cases. If both words are of the same polarity
 then resultant polarity is the same. But if their polarities are different, then the polarity of the first word
 is assigned to the bigram. \\
 \textbf{Examples:} \textit{beautifully amazing} is positive as both words as positive. \textit{lack respect} is
 assigned negative as per the rules.
\end{enumerate}

One salient feature of this approach is that it is an unsupervised method and can work on any domain.

\section*{SUMMARY}

In this chapter, we dicussed the motivation behind the topical n-grams model. Later on, we discussed the inference equation used by it. At the end,
we proposed an approach to use this model for sentiment analysis. The experiments and results obtained are discussed in ~\cref{experiments}.

In the next chapter, we will show the use of deep semantics for sentiement analysis.


\section{Calibration and detector behavior\label{sec:strategy}}

\subsection{Calibration}

This section describes how different correction factors are obtained:  the energy calibration (MIP, $\pi^{0}$, run by run), the time calibration and the bad channel mask.\

All these correction factors or masks are stored in the OCDB but also the OADB. Since these calibration parameters do not arrive before the full ALICE data reconstructions of the first periods are completed, the parameters are stored not only in the OCDB but also in the OADB so that the clusters can be corrected at the analysis level.  For the moment we do not store the time calibration and run by run correction factors in OCDB just in OADB.

\subsubsection{Energy calibration: MIP calibration before installation - Julien}
First, the calibration is done on cosmic measurements before installing the SuperModules at P2, but the accuracy obtained using MIPs is not good enough.

\subsubsection{Energy calibration: $\pi^{0}$  - Catherine}

The energy calibration relies during data taking on the measurement of the $\pi^{0}$ mass position per cell. Each tower has a calibration coefficient. In what follows, a calibration parameter is equal to the result of the fitted mass over the PDG mass value, where the fitted mass denotes the mass given by a gaussian fit on the $\pi^{0}$ invariant mass peak distribution in a given tower (plus a combinatorial background, fitted by a 2nd degree polynomial).
About 100-200 M events EMCAL (L0) triggered (trigger threshold at 1.5-2 GeV) allow to calibrate a majority of the towers. The towers located on rows 0 and 23 of each super modul (SM ) and those behind the support frame (about 5 columns per SM) have much fewer statistics and would need a minimum of 150 Mevts (probably more). It is to be noted that the run-to-run temperature variations change the towers' response in a non-uniform way, i.e. the width of the $\pi^{0}$ peak increases, and the mean $\pi^{0}$ mass is shifted differently for the various towers. Also the $\pi^{0}$ mass shifts to lower values for the towers with material in front, due to photoconversion close to the EMCAL surface.

A few iterations on the data, obtaining in each iteration improved calibration coefficients, are needed to achieve a good accuracy (1-2\%). Since the online calibration has a strong effect on the trigger efficiency, the voltage gains of the APDs are varied after each running period, to get a uniform trigger performance. Still, some towers are difficult to calibrate because they are behind of a lot of material (TRD support structures). For those MIPs or $J/\Psi$ measurements could help.

\paragraph*{$\pi^{0}$ Calibration Procedure\\}

Since $\pi^{0}$s decay into 2 gammas, their invariant mass is calculated from the energy of 2 clusters (and angle between the clusters). The position of the invariant mass peak of a tower therefore doesn't depend only on its response and calibration coefficient, but also on an average of the responses and calibration coefficients of all the other towers of the SM, weighted by  how often they appear in combination with a cluster in the considered tower. The 2nd effect, of weaker magnitude maybe, originates from the fact that a cluster most often covers more than the considered tower. To simplify the calibration process, the calibration coefficient is calculated as if the whole energy of the cluster was contained in the tower of the cluster which has the largest signal. So the position of the invariant mass peak of a tower also depends on an average of the responses and calib coeffs of its neighbouring towers. For these reasons, the calibration of the calorimeter with the  $\pi^{0}$ is an iterative procedure :
\begin{itemize}
\item Set all calib coeffs to 0 in OCDB.
\item Reconstruct the $\pi^{0}$'s with these OCDB coeffs.
\item Run the analysis code on this data to produce the analysis histograms and a 1st version of the calib coeffs.
\item Look at the fits on the towers invariant mass histograms and discard the value (or set it by hand) of the calib coeff of the towers for which the fit can't be trusted.
\item Create a 1st set of OCDB coeffs.
\item Reconstruct the $\pi^{0}$'s with these OCDB coeffs.
\item Run the analysis code on this data to produce the analysis histograms and a 2nd version of the calib coeffs.
\item Look at the fits on the towers invariant mass histograms and discard the value (or set it by hand) of the calib coeff of the towers for which the fit can't be trusted.
\item Create a 2nd set of OCDB coeffs.
\item Etc..., until the invariant mass is satisfactory in all the towers.
\end{itemize}
When the statistics is enough, 4 iterations should be enough to finalize the calibration (in practice, more are needed, due to outliers or studies that are needed).

There are 3 sets of codes :
\begin{itemize}
\item  Reco code : reads the data, reconstructs the $\pi^{0}$ inv mass distrib in each tower after it applies some cuts on the clusters and $\pi^{0}$ parameters. The output is a root file with invariant mass histograms (per tower, and summed-up per SM, per pT-bin).
\item Analysis code : reads the file produced by the reco code and analyses the histograms to produce the calib coeffs. This code is the one I present in what follows.
\item A code which reads the calib coeffs and writes them into a format that is loadable to OCDB.
\end{itemize}
The code is located in EMCAL/calibPi0/ :
\begin{itemize}
\item macros/ : contains the various macros.
\item input/ : contains the root files produced by the analysis code for the various iterations ("passes"). It has subdirectories "pass0/", "pass1/", etc... with, in each dir, the root file.
\item output/ : contains the various files produced by the analysis code for the various passes. It has subdirectories "pass0/", "pass1/", etc... with, in each dir, the various output files related to the pass.\footnote{Note that it wouldn't necessarily help to set-up a code that automatically reads and writes the pass number to avoid the hardcoded directories in the code, because it happens to do several times the same pass with various parameters (e.g. cuts in the reconstruction, or more statistics, or various masked zones, or hand-customization of a few calib coeffs, etc...).}
\end{itemize}

The cuts which must be put in the reconstruction are :
\begin{itemize}
\item Bad towers masked.
\item Both clusters in the same SM (to avoid misalignment effects).
\item Cut the 1-tower clusters out.
\item 20~ns timing cut.
\item Non-linearity correction (for the cluster energy)-- from beam test AFAIK.
\item No asymetry cut.
\item $E_{cluster} > 0.8$ ~GeV, or 0.7 GeV if there is little statistics. Tests showed that to remove the residual non-linearity (the $pi_{0}$ invariant mass rises with $p_{T}$), tightening the cut on $E_{cluster}$ was more efficient than requiring symetric decays (both gamma's of similar energy) (e.g. $asym < 0.5$ with $E_{gamma} > 0.5$~GeV).
\end{itemize}
It has the possibility to mask some areas. This is useful to disentangle the zones which have more material in front of them from those which don't. In the invariant mass distributions, the $\pi^{0}$ candidates kept are only those for which both clusters belong to the non-masked zones. In 2011, we considered masking the zones behind the support frame (in all the SMs or only in the SMs with TRD modules in front of them, i.e. SM 6-9 that year), plus additionnal problematic zones, to avoid taking clusters in these zones for the calculation of the average invariant mass in the towers with less material. (NB : not used for final calibration results, but for studies).

The analysis code has 3 input files :
\begin{itemize}
\item the root file f05 with inv mass histograms produced by the reconstruction code,
\item a file txtFileIn (output\_calibPi0\_parameters.txt) that contains the values of various parameters of the fit for each tower, at the previous pass,
\item a file txtFilePrevCalib (output\_calibPi0\_coeffs\_clean.txt) that contains the value of the calibration coefficient for each tower, at the previous pass (and after the hand-made corrections).
\end{itemize}
The 2 last files are therefore useless for the "pass0". To run the code for "pass0" (1st iteration), put the name of a valid file (e.g. one of last year) and just ignore the plots (red colour, in the last section -- see below).

There are 4 output files, that are written in the current directory (calibPi0/) : be careful not to overwrite an existing file ! After the code has been run, simply move those files to the relevant passXX directory := output/passXX/=.
\begin{itemize}
\item a postscript file psfile (output\_calibPi0.ps) with the plots described below,
\item a root file rootFileOut (output\_calibPi0.root) that contains the same plots in root format,
\item a file txtFileOut (output\_calibPi0\_parameters.txt) that contains the values of various parameters of the fit for each tower, for the current pass,
\item a file outputFile (output\_calibPi0\_coeffs.txt) that contains the value of the calib coeff for each tower, for the current pass.
Once the code has been run and the output files copied to the relevant output directory, I copy output\_calibPi0\_coeffs.txt to output\_calibPi0\_coeffs\_clean.txt, and modify the latter by hand to put the desired calib coeffs where we estimate that they can't be trusted.
\end{itemize}

9 parameters are defined to qualify the invariant mass distribution in each tower : the distribution is fitted by a gaussian + pol2 for the combinatorial background. The parameters are :
\begin{itemize}
\item amplitude of gaussian fit,
\item mean of the gaussian fit,
\item sigma of the gaussian fit,
\item c, b and a parameters of the combinatorial background fit $ax^2+bx+c$, I (histo integral),
\item I-S, S (integral of the gaussian fit). Minimal and maximal cut values are hardcoded (and to be changed at each iteration) for each parameter.
\end{itemize}
When the value of all the parameters lie between both extremes, the tower (i.e. the fit values, hence the mean, hence the calculated calib coeff) is "trusted". If one or more parameter has a value beyond the max cut value or below the min cut value, the tower is "untrusted".
Because these cut values can't be guessed in advance, the analysis code must be run twice per pass. The 1st time, so as to get the distributions of all 9 parameters, and decide on the basis of those distributions what are the suitable cut values to separate the towers to be trusted and those not to be trusted. The values are plugged in the code, and the code is then run a 2nd time, for real this time.
The macro (currently called DrawJulienFullEMCAL6.C) runs with 1 parameter in argument (set to 10 by default) : choice, which sets the number of SMs that one desires to include in the analysis. The values are either 4 (for the older SMs), or 6 (for only the newer SMs), or 10 (for the whole EMCAL). Here is the code. The macro is run this way :
\begin{lstlisting}
aliroot -b -q 'macros/DrawJulienFullEMCAL6.C++(10)'
\end{lstlisting}
There are various places where things must be customized before running the code ; they can be spotted by searching for this line : //CUSTOMIZE customize :.
\begin{itemize}
\item testChoice : this variable is a flag that allows to shorten the execution time for tests. 0 = not a test ; 1 = runs with only the 2 first columns of each SM ; 2 = runs with only the 2 first columns of the first SM,
\item the root input file f05,
\item the text input file txtFilePrevCalib (in principle not the name, only the path),
\item the text input file txtFileIn (in principle not the name, only the path),
\item if necessary : the min and max range values for the parameter histograms : tabMin and tabMax,
\item the min and max cut values for the parameters cutMin and cutMax,
\item if necessary : the number of bins in pT (for the 1st section, see below) nbPtBins and their range tabPtBins.
\item Text output on the standard output ("printf's") :
\end{itemize}

Finally, the first iteration needs the recalibration factors. This file is made running macros/RecalibrationFactors\_TextToHistoJulien\_mult\_2012.C on the output\_calibPi0\_coeffs.txt file. Once the RecalibrationFactors.root file is created it needs to be linked properly to re-run the reconstruction.

\subsubsection{Energy calibration: Run by run temperature gain variations - Evi, David  }

The SuperModules calibration depends on the temperature dependence of the different towers gains. We observe that from one period to other, where the T changes, the $\pi^{0}$ peak positions also changes. There are 2 ways to correct for this effect : either measure the mean T per run, and get the gain curves per tower a calculate the corresponding correction; or use the calibration LED events to quantify the variation from one reference run. Each of those 2 procedures have problems, poor or lack of knowledge of the gain curves of some towers or bad performance of the LED system in certain regions.
These temperature or time-dependent corrections are still under study: for further, and up-to-date, information, please see the wiki:
https://twiki.cern.ch/twiki/bin/viewauth/ALICE/EMCalTimeDependentCalibrations

\subsubsection{Time calibration - Marie }

The time of the amplitude measured by a given cell is a good candidate to reject noisy towers, identify pile up events when coming from different Bunch Crossing, or even identify heavy hadrons at low energy. The average time is around 580 ns. The aim of the time calibration is to do a relative calibration between cells to align all cells to a mean value of 0 ns, with as small spread as possible (negative values are unavoidable for the moment). The time calibration coefficient for each cell is the result of the average time of the cell when belonging to a cluster with enough energy (>1GeV).
The calibration coefficient have to be subtracted to the cell time.

\paragraph*{Time Calibration Procedure\\}

Since the some variations of mean time have been observed depending on the bunch cross numbers (BC) $\%$ 4 the computation of the time coefficients is done for each bunch cross numbers BC$\%$ 4 scheme.

The time calibration coefficient computing is done in 2 iterations.
\begin{itemize}
\item 1$^{rst}$  iteration:\\
Get Bunch Cross Number for the event.
Loop on all cluster of the event. \\ Loop on all cells in the cluster.
If cell amplitude is > 0.9 GeV and 500ns < cell time < 700ns then
compute average per cell per BC$\%$4 and fill in 1D histogam with calibration coefficients: hAveragesBC$x$ where $x$ stands for the result of BC$\%$4.
\item 2$^{nd}$iteration:\\
Get Bunch Cross Number for the event.\\
Loop on all cluster of the event. \\ Loop on all cells in the cluster.\\
Get Calibration coefficient for BC$\%$4 from  hAveragesBC$x$.  If cell amplitude is > 0.9 GeV and -20ns < (cell time-cell Calibration Coefficient)  < 20ns.\\
Compute average time per cell per BC$\%$4 and fill in 1D histogam with those new calibration coefficients: hAllAveragesBC$x$.
\end{itemize}

\paragraph*{Acces time calibration coefficients\\}

The time calibration coefficient are stored in OADB in TH1D histograms named hAllTimeAvBCx where x stands for the BC$\%$4 value.
They have the usual structure:
runrange/pass/

To use them in your analysis you may do the following:\\
\begin{DDbox}{\linewidth}
\begin{lstlisting}
 AliOADBContainer *contTRF=new AliOADBContainer("");
contTRF->InitFromFile(Form("%s/EMCALTimeCalib.root",fOADBFilePathEMCAL.Data()),"AliEMCALTimeCalib");
TObjArray trecal=(TObjArray)contTRF->GetObject(runnumber);
if(trecal)
{TObjArray trecalpass=(TObjArray)trecal->FindObject(pass);
if(trecalpass)
{printf("AliCalorimeterUtils::SetOADBParameters() - Time Recalibrate EMCAL \n");
for (Int_t ibc = 0; ibc < 4; ++ibc)
{
TH1F *h = GetEMCALChannelTimeRecalibrationFactors(ibc);
if (h)
delete h;
h = (TH1F*)trecalpass->FindObject(Form("hAllTimeAvBC%d",ibc));
}}
\end{lstlisting}
\end{DDbox}

As already  mentioned the time calibration of the cells is not done at the reconstruction level but offline during analysis. The methods to recalibrate cells is implemented in the class
\texttt{\$ALICE\_ROOT/\\EMCAL/AliEMCALRecoUtils}.
The method \texttt{RecalibrateCellTime(absId,bc,time)}: is called by the method \texttt{SwitchOnTimeRecalibration} , modifies the provided time with the calibration parameters. The inputs are the bunch crossing number that can be recovered from the event with InputEvent()->GetBunchCrossNumber(), and the absolute ID of the cell.
The way to pass  the calibration parameters to AliEMCALRecoUtils is the following.\\
\begin{DDbox}{\linewidth}
\begin{lstlisting}
AliCalorimeterUtils *cu = new AliCalorimeterUtils ;
TGeoManager::Import("geometry.root") ; //need file "geometry.root" in local dir!!!!
AliEMCALRecoUtils * reco = cu->GetEMCALRecoUtils();
and then
for(Int_t i =0; i< 4; i++) reco->SetEMCALChannelTimeRecalibrationFactors( i, (TH1F*) file->Get(Form("hAllTimeAvBC%d",i)))
\end{lstlisting}
\end{DDbox}
, where TFile *file is in the file containing the time calibration coefficients.

Some more details on time recalibration can be found in twikis:
https://twiki.cern.ch/twiki/bin/\\viewauth/ALICE/EMCalCode:HowTo\#Energy\_and\_Time\_calibration and in \\
https://twiki.cern.ch/twiki/bin/viewauth/ALICE/EMCALTimeCalibration

\subsection{Alignment - Marco}

CERN provides survey measurements of the position of different EMCAL Supermodules points at the beginning of the running period (and on request?). As soon this information is available, the ideal EMCAL positions used in the reconstruction by default, are corrected with special position matrices calculated from the measurements. Finally, once the data is reconstructed, the accuracy of the alignment is cross checked with track matching and $\pi^{0}$ mass measurements, since those values change depending on variations on the positions of the SuperModules.

\subsection{Bad channel finding - Alexis}

The analysis is done on the output of offline Quality assurance see section \ref{sec:QAOffline} histograms \texttt{TH2F EMCAL\_hAmpId} containing the distribution of amplitudes (energy) of cell versus cell Absolute ID number (AbsId). The idea is to check distributions over the cells of different observables extracted from this histograms. Then each cell is tested regarding to the distribution over all the cells for each obbservable. The different tests are the following:

\begin{enumerate}
\item average energy (average computed for Emin< E  <Emax)
\item average number of hit per event  (average computed for Emin< E  <Emax)
\item Shape criteria : A fit of the cell energy (amplitude) distribution is performed with the function:$A*e^{-B*x}/x^2$ between Emin and Emax.  Then the  $\chi^{2}/ndf$, A  and B which are parameters from the fit of each cell amplitude.
\end{enumerate}

Each criteria is tested at least once (they can be tested also for different energy i nterval). At the end of each test the marked cells are excluded (if above nsigma from mean value, usually nsigma is taken equal 4 or 5) before computing the next distribution.

The typical nsigma used is 4 or 5.
The min energy considered is 0.1 GeV/0.3 GeV.  And the maximum energy depends on the data (minbias or triggered data).

There are different levels of classification for  cells wich will enter the deadMap:
\begin{itemize}
\item kAlive = 0: cell is OK
\item kDead = 1: cell is dead
\item kHot = 2: cell is bad
\item kWarning=3: cell may have problems (warm or miscalibrated)
\end{itemize}

The distinction of the bad/warm status is done by visual check of the energy distribution of the cells detected by the different tests described above.

In the reconstruction pass the only the cells marked as kHot and kDead are not reconstructed.

The macro to compute the BadCellAnalysis can be found on \\ \texttt{\$ALICE\_ROOT/PWGGA/CaloTrackCorrelations/macros/QA/BadChannelAnalysis.C}. This macro allows first to merge all the individual run histograms in order to get the energy distribution over a large statistics. Usually this is done at the end of a data taking period. Then it computes the different tests and produces the text file with the dead and bad cells detected. Finally the macro produce a pdf file containing the individual energy distribution for all the detected cells.

All the results and  OCDB created are updated on the following twiki:\\
https://twiki.cern.ch/twiki/bin/viewauth/ALICE/EMCalQABadChannels.


\documentclass{../csopractical}
\SVN    $Id: Practical2.tex 1324 2016-01-15 18:19:56Z sufrin $

\begin{document}
\begin{center}
\Large\bf Concurrent Programming Practical
\\
2: The Game of Life
\end{center}

It is recommended that you read the chapter of the coursenotes on synchronous
data parallel programming before you attempt this practical.  The code from
the lectures is on the course website.

\subsection*{Introduction}

The aim of this practical is to implement the Game of Life, a cellular
automaton invented by John  Conway in 1970.  The Wikipedia entry on Life
describes it as
follows:\footnote{\url{http://en.wikipedia.org/wiki/Conway's_Game_of_Life}}
%
\begin{quote}
The universe of the Game of Life is an infinite two-dimensional orthogonal
grid of square cells, each of which is in one of two possible states, live or
dead. Every cell interacts with its eight neighbours, which are the cells that
are directly horizontally, vertically, or diagonally adjacent. At each step in
time, the following transitions occur:
%
\begin{enumerate}
\item
Any live cell with fewer than two live neighbours dies, as if by needs caused
by underpopulation.

\item
Any live cell with more than three live neighbours dies, as if by overcrowding.

\item
Any live cell with two or three live neighbours lives, unchanged, to the next
generation.

\item
Any tile with exactly three live neighbours cells will be populated with a
living cell.
\end{enumerate}

The initial pattern constitutes the `seed' of the system. The first generation
is created by applying the above rules simultaneously to every cell in the
seed --- births and deaths happen simultaneously, and the discrete moment at
which this happens is sometimes called a tick. (In other words, each
generation is a pure function of the one before.) The rules continue to be
applied repeatedly to create further generations.
\end{quote}
%
You might want to read the rest of the Wikipedia article.

We will consider a variant with a finite $N$ by $N$ grid, treated as a toroid,
i.e.\ where the top and bottom edges of the grid are treated as being
adjacent, as are the left and right edges.

%%%%%

\subsection*{Your task}

Your task is to implement the Game of Life.  Your program should
use $p$ processes (say 4 or 8) to update the cells on each generation.
You will probably want to allocate some region of the grid to each
process.  There are two essentially different ways to structure the
program: (1)~as a shared-variable synchronous data parallel program;
(2)~as a pure message-passing program.\footnote {In the latter case
my experience with a predecessor of thread CSO suggests that
allocating a CSO process to each square in the grid means that only
a small grid can be dealt with before the operating system/jvm
begins to run out of thread resources. Go, or the fibre-based
implementation of CSO would be a better bet for a serious attempt:
but my advice is not to try at this stage. Other message-passing
solutions have workers working on larger rectangular regions of the grid,
and exchanging the edges of their regions with neighbour workers
every generation.}  In both cases the processes need to be synchronised
in some way, so that the rules of the game are followed, so you need
to think carefully about how to avoid race conditions.

There is a file
\texttt{Display.scala} (on the course website), which defines
a \texttt{Display} class that can be used to build displays
that show the state of a grid.  A
display is created by
%
\begin{scala}
  val display = new Display(N,a)
\end{scala}
%
where \SCALA{N} is an integer, representing the size of the grid, and
\SCALA{a} is the grid, represented by an \SCALA{N} by \SCALA{N} array of \SCALA{Boolean},
e.g.\ initialised by
%
\begin{scala}
  val a =  Array.ofDim[Boolean](N,N)
\end{scala}
%
The display is made consistent with \SCALA{a} by executing
%
\begin{scala}
  display.draw
\end{scala}
%
This shows solid black squares at positions \SCALA{(i,j)} where \SCALA{a(i,j)} is true,
and grey squares where \SCALA{a(i,j)} is false.

%% You might also want to use the file {\tt Barrier.scala}, which provides an
%% implementation of barrier synchronisation.

Test your implementation by considering some interesting seeds (see the
Wikipedia page to get some ideas).

%%%%%

\subsection*{Optional}

Implement one or more of the variants from the Wikipedia page.  (You might
have to adapt {\tt Display.scala} to do this.)
%
Alternatively, devise a more complicated game that can be modelled using
cellular automata.  For example, you could model the interactions between
foxes and rabbits.  Don't make the rules too complicated, though!  You could
include some randomness in the game.

%%%%%

\subsection*{Reporting}

Your report should be in the form of a well commented program, describing any
design decisions you have made.

%% \begin{flushright}
%% Gavin Lowe \\ February 2010
%% \end{flushright}

\end{document}


\section{Resources: Costing Zerepoch Core}
\label{sec:costing}

A key, unusual, requirement of the scripting language we use is that it must have a built-in notion of resource tracking.
We are going to run untrusted code on many machines during transaction validation and diffusion - it is important that we carefully control its resource usage.

This is a familiar problem in other systems such as Ethereum (which tracks resource usage using ``gas''), but we are focussing on a somewhat different set of requirements.

\subsection{Requirements}
\begin{requirement}[Profitable fees]
\label{req:costing-profitability}
\Glspl{slot-leader} are compensated for the work that they do validating transactions by being given the transaction fees.
This ensures that it is economical (or even profitable) to run a stake pool even just based on transaction fee income.
We therefore need to ensure that the fees for script execution don't change this dynamic, e.g. by making it un-economical to run a pool.

If transactions with scripts are un-economical to process, then slot leaders may simply choose not to include them, which would compromise the usability of the system.
\end{requirement}

\begin{requirement}[DoS security]
\label{req:costing-dos}
Scripts allow the user who submits a transaction to force every node on the network to perform some computation of the user's choice.
This provides an obvious angle for DoS attacks: simply flood the network with pointless transactions that require a lot of computation, thus preventing the network from doing anything else.
Of course, any such attack must pay the script execution fees for these transactions.
So we need to make the fees high enough that such an attack is un-economical.
\end{requirement}

\begin{requirement}[Usable fees]
\label{req:costing-usable}
We do want users of \gls{bcc} to actually use scripts.
So the cost to run scripts can't be too high, otherwise nobody will use them.
The simplest way to encourage this is to make the evaluator faster, which benefits legitimate users without compromising the security of the system.
\end{requirement}

\begin{requirement}[Determinism]
\label{req:costing-determinism}
Script execution cost affects whether a transaction validates, and as such if the costs are non-deterministic then it is non-deterministic whether a transaction with scripts will validate at all.
Predictable costs ensure that users can submit transactions and be sure that they will validate (or if they don't, it will be for other reasons).

See also \cref{req:ledger-determinism}.
\end{requirement}

\begin{requirement}[Evaluator abort]
\label{req:costing-abort}
The evaluator must be able to run scripts with limited resources and stop them when they exceed it, so we actually enforce budgets.
\end{requirement}

\begin{requirement}[Intuitive costs]
\label{req:costing-intuitive}
Programmers will want to reason about costs when writing their programs.
So ideally costs should track those intuitions.
That way, if a user does something that they expect to reduce the cost of the program, then it probably does do so.
\end{requirement}

\begin{requirement}[Specifiablity]
\label{req:costing-specifiable}
We want to formally specify how the costs for a script should be calculated, which means that the method for computing them must be relatively simple and manageable to specify.
\end{requirement}

\begin{requirement}[Low overhead]
\label{req:costing-overhead}
Tracking costs during script execution should not impose too much overhead.
We don't want the process of preventing scripts from running too slow to itself slow them down significantly!
\end{requirement}

\begin{requirement}[Parameterizable models]
\label{req:costing-parameters}
We are unlikely to get all the numeric choices about how to assign costs correct first time.
Or, they might be invalidated by hardware or software changes.
Hence we should parameterize the model so that the ledger can change the parameters (e.g. with a protocol parameter update).
\end{requirement}

\begin{requirement}[Language-agnostic ledger support]
\label{req:costing-language-agnostic}
The ledger will support many different languages, which may think about costing in quite different ways.
We want to make this as easy as possible, ideally by abstracting away some of the details.
\end{requirement}

\begin{requirement}[Block budgets]
\label{req:costing-block-budget}
We have some constraints on how long block validation as a whole can take, in order to ensure that blocks can propagate across the network fast enough.
In addition, we have limits on how much peak memory we can use in a block, based on our expectations of typical hardware.

We may therefore need hard limits on resource usage per-block, in addition to setting prices for resource usage.
\end{requirement}

\subsection{Non-Requirements}
There are some things which we could have designed for, but we have chosen not to.
A few notable examples are given here.

\paragraph{Units of cost should be persistent across transactions}
On Ethereum, gas which a contract does not spend in a single transaction is persistent - it can be used later.
We don't intend to replicate this: because execution costs are predictable, it is no problem to require users to provide exactly the amount that they need.
Moreover, persistent cost units potentially allows undesirable arbitrage where a user can ``buy'' computation when it is cheap and ``spend'' it later when it is expensive, which is not what the network wants.

\paragraph{Users should be able to calculate script execution costs for any input to that script}
Users often care about the ``total cost of operation'' of an application.
But this may consist of running the same script with many different inputs across time, depending on contingent facts which will not be known until later.
To give this information to users precisely we would need to be able to predict, for any input, what the execution cost would be.
This is something that has been studied, but we believe it would be a lot of work to apply to our situation.
\footnote{
  There is research in doing this for languages with explicit recursion and datatypes.
  We would probably want to do this analysis on Zerepoch IR, and then try and translate the analysis down to Zerepoch Core.
  This seems like a substantial amount of work, probably a PhD thesis or so.
}
Users will still be able to get some idea of total cost of operation by running their script with a selection of indicative inputs.

\paragraph{Slot leaders should be compensated for the opportunity cost of memory usage}
We want to enforce a peak memory limit to avoid crashes, but we don't bother compensating slot leaders for the opportunity cost of using their memory.

\subsection{High-level approach}
This section gives a very high-level overview of the approach we take to the problem.
Further details on each of these topics are given later.

\paragraph{Abstract resources}
Rather than computing costs directly in Bcc or in real resource units (e.g. seconds), we instead compute them in \emph{abstract resource units}, which do not have a definitional link to real resources.
The reasons for this are that:
\begin{itemize}
\item Costs must be deterministic and specifiable (\cref{req:costing-determinism,req:costing-specifiable}), so we cannot use \emph{real} resource units which will differ by machine.
\item The decision for how to convert these resource units into Bcc (``pricing'') can be the ledger's responsibility alone.
\item Language-specific costing solutions don't need to worry about the (potentially strategic) concerns that affect pricing (\cref{req:costing-language-agnostic}).
\end{itemize}

\paragraph{Limiting execution}
The evaluator can run in a mode (``restricting'') where it is given a budget of abstract resources, and terminates if the execution exceeds that (\cref{req:costing-abort}).
We also provide another mode (``counting'') where we do not take a budget, and instead return the minimum budget that the script requires.

\subsubsection{Cost model}
We call the system which tells the evaluator how much an script should cost a ``cost model''.

\paragraph{Cost model strategy}
The cost model for \gls{zerepoch-core} is defined in a fairly simple, compositional way by giving costs for individual operations, and then accumulating them over the course of the evaluation.

This cost model naturally has a lot of parameters: the numbers that influence the costs for the individual operations.
We allow all of these to be changed, so the evaluator accepts a bag of parameters which gives all of these values.
These parameters will be put into the protocol parameters, so we should have a large amount of flexibility if we need to tweak the cost model later (\cref{req:costing-parameters}).

\paragraph{Choosing the cost model parameters}
The decoupling of the abstract resource units from the pricing units allows us to use a fairly simple rubric for picking cost model parameters: try and actually follow (be correlated with) real costs!

This ensures that resource costs will follow programmers' intuitions (\cref{req:costing-intuitive}), while giving plenty of flexibility in the final pricing of those resources.

If we later change our minds about the cost model parameters (e.g. because what we consider ``typical hardware'' changes), we can re-calibrate our parameters and submit a protocol parameter change.

However, we do want our choices to generally be an \emph{over-approximation}, because anywhere we under-approximate is a potential source of attacks (\cref{sec:costing-security}).

\subsubsection{Pricing model}
The conversion from abstract resources to Bcc is done by the ledger.
We call the system which tells us how to do this conversion the ``pricing model''.

\paragraph{Pricing model strategy}
The current proposed pricing model simply consists of an Bcc price for each of the abstract resources.
So a budget in terms of \gls{space} and \gls{time} will be turned into a price in terms of Bcc by multiplying the components of the limit by their respective prices.

These prices also obviously function as parameters for the pricing model.
Hence they will also be put in the protocol parameters, so that pricing can be changed with only a protocol parameter change.

\paragraph{Choosing the pricing model parameters}
Choosing the pricing model parameters is a complex problem that may have strategic considerations.
At minimum, the prices will need to be high enough to avoid DoS attacks (\cref{req:costing-dos}).

\subsubsection{Validating scripts}
Putting the pieces together, what happens when a script is validated is:
\begin{itemize}
\item
  The ledger uses the pricing model parameters to compute the price for the stated resource budget in Bcc, and ensures that the transaction has sufficient fees to cover this, and that it does not cause us to exceed the per-block budget (\cref{req:costing-block-budget}).
\item
  The ledger runs the script, passing in the stated budget and the cost model parameters.
\item
  The evaluator either terminates normally, with success or an error depending on the program, or stops early if it runs out of budget.
\end{itemize}

\subsection{Abstract resource units and resource budgets}
\label{sec:costing-units}
We use two abstract resource units:
\begin{itemize}
\item Abstract time/CPU usage (``\gls{time}'')
\item Abstract peak memory usage (``\gls{space}'')
\end{itemize}

Script execution is limited in both \gls{time} and \gls{space}.
The overall limit (budget) is therefore a pair of some amount of \gls{time} and \gls{space}.

Crucially, the interpretation of the \gls{space} limit is that it is a limit on (our over-approximation of) \emph{peak} space usage.
This is because the limit is mainly to prevent crashes due to exceeding a machine's available RAM, not to compensate the slot leader for RAM usage.

The reason we need to track memory at all is because our evaluators can use unbounded memory.
This is not true in e.g. Ethereum where there is a (small) stack limit, so programs can be assumed to fit within a constant memory budget.
Zerepoch Core has both unbounded integers and unbounded recursion, so it is not hard to use a large amount of memory.\footnote{
Most programs that use lots of memory will also use lots of time, and we could price them punitively to ensure that the time budget was always a binding constraint.
But this requires some subtle reasoning: it is easier to simply talk about memory if that's what we care about.
}

\subsection{Building the cost model}
The high-level description of the cost model said that we would give costs for ``individual operations''.
This means that the model is tied to exactly what kind of evaluator we use.
At the moment we use a fairly standard CEK machine.

\todompj{Ref into PLC section}

Our goal in producing a cost model is to make the computed costs be well-correlated with the real costs.
Since the pricing model can be used to control how these are paid for, we can stick to trying to track reality.
Hence we start by benchmarking individual parts of execution, and using statistical methods to infer model parameters from that.

\subsubsection{Mapping between real and abstract units}
Any benchmarks we run will give results in actual units (e.g. microseconds), not our abstract units.
So in order to actually use them we need to do one of two things:
\begin{enumerate}
\item
  Set a target mapping for how real units should correspond to abstract units, e.g. 1 \gls{time} = 1 microsecond.
  We can then use this to interpret our benchmarks as benchmarks of ideal abstract unit usage.
\item
  Pick one of the parameters as a baseline and relativize all the others to that.
  For example, we could declare that 1 machine step will take 1 \gls{time}, and then divide the times for other operations by the time for a machine step to get their abstract \gls{time} usage.
  Then the abstract units would indicate ``resource usage relative to the chosen baseline operation''.
\end{enumerate}

Option 1 has two advantages:
\begin{enumerate}
\item It gives us a way to calibrate abstract resource usage across multiple scripting languages, which is important if we want to use (and price) the same units for all of them.
\item It gives us an obvious way to say how many real units correspond to an abstract unit, which is useful for constructing the pricing model.
\end{enumerate}

So we adopt option 1.

The specific targets we are using at the moment are:
\begin{itemize}
\item \gls{time}: 1 \gls{time} = 1 microsecond
\item \gls{space}: 1 \gls{space} = 1 machine word (8 bytes on a 64 bit machine)
\end{itemize}

\subsubsection{Simplifying assumptions about memory usage in Haskell}
Memory usage in Haskell is quite complicated.
However, we can simplify the situation by making some assumptions.

\paragraph{No memory is ever garbage-collected or freed}
This is a pessimistic assumption, but being pessimistic is fine since we're aiming for an overestimate.
It simplifies our calculations, since it means that we can just track all \emph{allocations} of memory, and don't have to worry about the details of when things are de-allocated.

\paragraph{All references to the AST are shared}
This is an optimistic assumption, but justified by our knowledge about how Haskell works.
This means that we can work out how much memory the AST takes up, and then we can assume that references to parts of the AST (e.g. in variable environments) take no memory for the AST part.
That simplifies our accounting significantly, since the new allocations will be for small things like entries in variable environment mappings.

\subsubsection{\gls{space} for the AST}
We need to compute \gls{space} usage for the AST in several places:
\begin{itemize}
\item At the start of execution to account for loading it into memory and to handle references (see the above discussion of sharing).
\item When evaluating a builtin operation (see below) the cost may depend on the size of  the arguments.
\end{itemize}

For the AST itself we follow a fairly simple scheme where we make some assumptions about how much space the nodes themselves take up, as well as their children.
For constants, we simply think about the underlying type: how much space do we think an integer, say, takes up?

\subsubsection{\gls{space} and \gls{time} for builtin operations}
Builtin operations are in some ways the trickiest thing to cost, since they are very heterogeneous, and are implemented by external code.
Moreover, their performance characteristics often depend on the inputs to the function: adding two 1000000 digit numbers is much slower than adding two 10 digit numbers.

\paragraph{Size of builtin arguments}
We use the \gls{space} usage of an argument (typically a constant term) as a proxy for its size.
This is not perfectly precise, but it is reasonably correlated with the measures of size that e.g. addition is likely to care about.

\paragraph{Builtin accounting happens before execution}
Builtin operations can in principle use a lot of resources just in the operation itself.
For example, multiplying two sufficiently large numbers can require a large amount of memory to hold the result, much larger than that required to hold the arguments.
This leads to a conflict: builtin operations are atomic (in that we can't interrupt them), but we want to interrupt evaluation as soon as we exceed our resource budget.

Our solution is to compute the costs for a builtin operation before we run it.
Since we are not actually measuring anything, but rather computing the cost from our model, we are able to do this.
That way we can terminate evaluation if we would exceed the budget after running the operation, without actually running the operation.

\paragraph{\gls{time} for builtin operations}
The approach we take for \gls{time} is very empirical:
\begin{enumerate}
\item
  Micro-benchmark the builtin with arguments of varying sizes.
\item
  Look at the resulting data and try to pick an appropriate linear model for the running time based on the argument sizes (e.g. ``linear in both arguments'').\footnote{
  This is an imprecise approach, but choice of statistical models is always more of an art than a science.
  }
\item
  Use linear regression to infer the parameters for the model, these are the cost model parameters for this builtin.
\end{enumerate}

\paragraph{\gls{space} for builtin operations}
The approach we take for \gls{space} is more deductive.
Generally it is hard to measure memory allocation, especially when it occurs in a foreign library.
So we largely rely on reasoning about or inspecting the libraries in question.
Many perform no allocation, or a predictable amount of allocation.

\subsubsection{\gls{space} and \gls{time} for machine steps}
The CEK machine itself has many steps that it goes through, which correspond to handling e.g. application of user-defined functions.
These also need to have costs associated: naive profiling suggests that the operation of the machine itself (as opposed to builtin functions) is usually more than 50\% of evaluation time.

\paragraph{\gls{time} for machine steps}
The approach we initially took for \gls{time} is empirical, matching the approach for builtins:
\begin{enumerate}
\item Assume that the execution time is linear in all the kinds of machine steps.
\item Benchmark execution of a large number of varied programs that use all the execution steps.
\item Use linear regression to infer the parameters for the model, these are the cost parameters for the machine steps.
\end{enumerate}

However, when we actually did this, we found that the number of machine steps of different kinds are almost perfectly correlated, such that there is little point trying to infer coefficients for them individually.
So instead we fit a single-parameter linear model based only on the total number of steps.\footnote{
The argument from correlation holds even if the different steps do actually have very different execution costs!
It's possible that they are all indistinguishably similar, but even if they were quite distinct, if they're very well correlated a single-parameter model will still do a better job.
}

\paragraph{\gls{space} for machine steps}
The approach we take for \gls{space} is more deductive.
Generally we assume that machine steps incur memory usage in certain specific ways, such as creating machine frames or creating mappings in variable environments, and we handle these specifically.

\subsubsection{Summary of overall calculation}
To sum up, the cost for a program execution is:
\begin{itemize}
\item The initial \gls{space} cost of the AST.
\item The initial \gls{time} cost for starting the machine (the intercept of the linear model for the machine steps).
\item The \gls{time} and \gls{space} costs for each machine step that is taken (as determined by the coefficients of the linear model for the machine steps).
\item The \gls{time} and \gls{space} costs for each builtin call (as determined by the linear models for each builtin operation).
\end{itemize}

\subsection{Building the pricing model}
The pricing model is out of our control - it is the ledger's responsibility, and as we discussed earlier, the process of choosing the model is likely to be complex and influenced by many non-technical factors.
However, anyone making a decision about how to set prices does need at least some input from us, because prices relate to real costs (real CPU seconds, real memory usage), and so we need to know how our abstract units correspond (in reality, at the current time) to real units.

Fortunately, we have this information easily to hand, since we are targeting specific relationships between abstract units and real units when we build our models.
So we can assume that those relationships hold (e.g. 1 \gls{time} = 1 microsecond).

\subsection{Security}
\label{sec:costing-security}

The top priority of the model is to ensure the security of the ledger against attacks, particularly DoS attacks, but also economic attacks that sap profit from the system.

\paragraph{Basic structure of an attack}
The basic kind of attack we are worried about is where we have set one of our cost parameters too low, effectively under-costing a particular operation.
For example, maybe addition is too cheap, or a certain kind of machine step.

An attacker could then construct a synthetic program that disproportionately uses the under-costed operation.
Such a program would then be more expensive to execute in reality than the model predicts, allowing the attacker to force node operators to do more work than they are paying for.

How dangerous this is depends on how badly we under-estimate the parameter.
If we under-estimate it by only 10\%, then an attacker is only getting a 10\% ``discount'' on computation: probably not enough to make it worthwhile to mount an attack.
If we under-estimate it by an order of magnitude or two, then we could be in trouble.

We might think that such malicious programs would be large, and so transaction size limits would help us.
But we have loops and recursion in Zerepoch Core, so it is likely that an attacker could make a relatively small program that does a very large number of the problematic runtime operations.

\paragraph{Simple prevention approaches}
Our attack prevention approach is fairly simple.
We try and make the cost model give an \emph{over}-estimate of reality, and then we try to make the pricing model over-price the resources.

In order to keep this working, we need to:
\begin{enumerate}
\item Ensure that we take great care when updating the cost model, especially if we make things cheaper (say, on the basis of the evaluator getting faster)
\item Ensure that we adjust prices as appropriate when the cost of hardware changes.
\end{enumerate}

\paragraph{Tools for node operators to check accuracy of models on their hardware}
Our benchmarks are going to be run on a reference machine.
Of course, not all machines are alike, and it's possible that our hardware may be unusual, or certain node operators' hardware is unusual in such a way that allows an attack.

For example, perhaps addition is unusually slow on operator O's machine: then a program which does lots of addition might be costed cheaply, run fine on our reference machine, but overload O's machine.

A simple way to mitigate this risk is to provide tools for node operators to run the benchmarks on their own hardware.
If they get results that indicate that costs should be higher, then that indicates a potential attack and we may need to raise costs.


\documentclass{article}

\usepackage{amsmath,amsthm,amssymb,mathrsfs,fancyhdr,geometry,bm,graphicx,mhchem}
\pagestyle{fancy}
\newcommand{\norm}[1]{\left|#1\right|}
\newcommand{\bra}[1]{\langle #1|}
\newcommand{\ket}[1]{|#1\rangle}
\newcommand{\braket}[2]{\langle #1|#2\rangle}
\newcommand{\code}{\texttt}
\begin{document}
\lhead{\textit{HSG analysis\\Help file}}
	\rhead{Sherwin Lab\\ \today}
	\begin{center}
		\begin{Large}
			\textbf{On the Organization of the HSG Analysis Python Library}\vspace{5pt}\\
		\end{Large}
		%\emph{\today}
	\end{center}

\section{Introduction}
\indent \indent This will give a brief foray into the dark underbelly of hsganalysis.py.  The file itself will contain all of the variable information in the docstrings.  This will go deeper into how it actually functions, what things to call when.
\section{The classes}
\indent \indent There are three super classes: CCD, PMT, and Spectrum.  CCD currently handles any spectrum data from the EMCCD.  The PMT class handles data from the PMT detector.  Spectrum combines CCD and PMT classes to make whole spectra.
\subsection{CCD class}
\indent \indent As covered previously, the CCD class handles data taken with the Andor EMCCD.  The general processing guide is to initialize the CCD instance, guess the sideband locations and determine their strengths, fit those sidebands to gaussians (or any arbitrary function), and finally to save the processed spectrum and the fit results.
\subsubsection{Attributes}
\subsubsection{Methods}
There are many methods in the class, only some of which need to be called by the user.\\
Magic methods:
\begin{enumerate}
	\item \code{\_\_init\_\_(fname)} - Initializes the CCD object.
	\begin{itemize}
		\item Inputs: \code{fname} - The whole path to the spectrum file.  This file contains a dictionary with all of the important experimental descriptions and parameters.
		\item Internals:
		\begin{enumerate}
			\item \code{self.fname} - the path that the imported file came from.
			\item \code{self.parameters} - dictionary with all of the important experimental details
			\item \code{self.description} - string with a brief description of the spectrum
			\item \code{self.raw\_data} - np.array of size $1600\times2$. The first column is in nm, the second column has the raw counts from the CCD.
			\item \code{self.hsg\_data} - np.array of size $1600\times2$. The first column is in eV, the second column contains the counts normalized by the number of FEL pulses.
			\item \code{self.dark\_stdev} - standard deviation of the dark counts as calculated during the experiment divided by the number of FEL counts.
			\item \code{self.addenda} - a list of the things added to this object to make it what it is, including constant offsets and other spectra.
			\item \code{self.subtrahenda} - a list of spectra subtracted from this object.
		\end{enumerate}
		\item Outputs: \code{None}
	\end{itemize}

	\item \code{\_\_add\_\_} - Adds a number (float or int) or another spectrum.  It's unclear at the moment whether this should be \code{raw\_data} or \code{hsg\_data}.  It seems to work currently, though, because of an extra method, \code{image\_normalize}.
	\begin{itemize}
		\item Inputs: \code{other} - A number or another spectrum.  Currently adds \code{hsg\_data} if other is a CCD object.
		\item Internals:
		\begin{enumerate}
			\item \code{ret.addenda} - the two addendas are concatenated.
			\item \code{ret.subtrahenda} - the two subtrahendas are concatenated.
			\item \code{ret.parameters[`fel\_pulses']} - these are added together as well.
		\end{enumerate}
		\item Outputs: a new CCD object that is the sum of self and other.
	\end{itemize}

	\item \code{\_\_sub\_\_} - Subtracts a number (float or int) or another spectrum.  It's unclear at the moment whether this should be \code{raw\_data} or \code{hsg\_data}.  It seems to work currently, though, because of an extra method, \code{image\_normalize}.
	\begin{itemize}
		\item Inputs: \code{other} - A number or another spectrum.  Currently subtracts \code{hsg\_data} if other is a CCD object.
		\item Internals:
		\begin{enumerate}
			\item \code{ret.addenda} - the old addenda is concatenated with the new subtrahenda.
			\item \code{ret.subtrahenda} - the old subtrahenda is concatenated with the new addenda.
		\end{enumerate}
		\item Outputs: a new CCD object that is the sum of self and other.
	\end{itemize}

	\item \code{\_\_str\_\_} - prints the \code{description} of the file.
		\begin{itemize}
		\item Inputs: nothing
		\item Internals: nothing
		\item Outputs: \code{self.description}.
	\end{itemize}
\end{enumerate}

\noindent Normal methods:
\begin{enumerate}
	\item \code{add\_std\_error} -
	\begin{itemize}
		\item Inputs:
		\item Internals:
		\item Outputs:
	\end{itemize}

	\item \code{calc\_approx\_sb\_order} -
	\begin{itemize}
		\item Inputs:
		\item Internals:
		\item Outputs:
	\end{itemize}

	\item \code{image\_normalize} -
	\begin{itemize}
		\item Inputs:
		\item Internals:
		\item Outputs:
	\end{itemize}

		\item \code{guess\_better} -
	\begin{itemize}
		\item Inputs:
		\item Internals:
		\item Outputs:
	\end{itemize}

	\item \code{guess\_sidebands} -
	\begin{itemize}
		\item Inputs:
		\item Internals:
		\item Outputs:
	\end{itemize}

	\item \code{fit\_sidebands} -
	\begin{itemize}
		\item Inputs:
		\item Internals:
		\item Outputs:
	\end{itemize}

	\item \code{fit\_sidebands\_for\_NIR\_freq} -
	\begin{itemize}
		\item Inputs:
		\item Internals:
		\item Outputs:
	\end{itemize}

	\item \code{save\_processing} -
	\begin{itemize}
		\item Inputs:
		\item Internals:
		\item Outputs:
	\end{itemize}

	\item \code{stitch\_spectra} - This does nothing.
\end{enumerate}

\subsection{PMT class}
\indent \indent This class imports and handles data from the PMT.
\subsubsection{Attributes}
\subsubsection{Methods}
Magic methods:
\begin{enumerate}
	\item \code{\_\_init\_\_} - Initializes the PMT object. Requires all of the tiny files to be in the same folder
	\begin{itemize}
		\item Inputs: \code{folder\_path} - the complete path of the folder that contains all of the tiny PMT data files.
		\item Internals:
		\begin{enumerate}
			\item
		\end{enumerate}
		\item Outputs:
	\end{itemize}
\end{enumerate}

\noindent Normal methods:
\begin{enumerate}
	\item \code{fit\_sidebands} -
	\begin{itemize}
		\item Inputs:
		\item Internals:
		\item Outputs:
	\end{itemize}

	\item \code{save\_processing} -
	\begin{itemize}
		\item Inputs:
		\item Internals:
		\item Outputs:
	\end{itemize}
\end{enumerate}

\subsection{Spectrum class}
\indent \indent This class takes PMT and CCD class data and combines them.
\subsubsection{Attributes}
\subsubsection{Methods}
Magic methods:
\begin{enumerate}
	\item \code{\_\_init\_\_} - Initializes the Spectrum object. At the moment it requires a PMT and a CCD object.  It would be cool if it could handle two CCD objects (hint hint).
	\begin{itemize}
		\item Inputs:
		\begin{enumerate}
			\item \code{PMT\_spectrum}
			\item \code{CCD\_spectrum}
		\end{enumerate}
		\item Internals:
		\begin{enumerate}
			\item \code{self.pmt\_results}
			\item \code{self.ccd\_results}
			\item \code{self.parameters}
			\item \code{self.pmt\_dict}
			\item \code{self.full\_dict}
		\end{enumerate}
		\item Outputs: \code{None}
	\end{itemize}
\end{enumerate}

\noindent Normal methods:
\begin{enumerate}
	\item \code{plot\_prep} - This makes an np.array, \code{self.full\_results}, that is identical to the \code{sb\_results} np.array in other objects.
	\begin{itemize}
		\item Inputs: Nothing
		\item Internals: \code{self.full\_results}
		\item Outputs: \code{None}
	\end{itemize}

	\item \code{add\_sidebands} - This method takes another CCD object and adds \code{sb\_results} to the current \code{self.full\_results} attribute in the dumbest way possible.
	\begin{itemize}
		\item Inputs: CCD\_spectrum - a CCD object that is part of the same spectrum making up this object.
		\item Internals:
		\begin{enumerate}
			\item \code{self.ccd2\_results} - copied from \code{CCD\_spectrum.sb\_results}.
			\item \code{self.ccd2\_dict} - keys are sb order, values are the results from before.
			\item \code{self.full\_dict} - gets stitched with \code{self.ccd2\_dict} to make a complete thing.  No averaging, no nothing.
		\end{enumerate}
		\item Outputs: \code{None}
	\end{itemize}

	\item \code{save\_processing} - This saves things like the other save-y things.
	\begin{itemize}
		\item Inputs:
		\begin{enumerate}
			\item \code{file\_name} - the base of the file name that will be saved.
			\item \code{folder\_str} - the folder that the file will be saved in.  It will create the folder if necessary.
			\item \code{marker=`'} - an extra piece of the file name to be saved.  Can be a parameter or something.
			\item \code{index=`'} - indexer that has to be external because numpy's saving system sucks.
		\end{enumerate}
		\item Internals:
		\begin{enumerate}
			\item \code{spectra\_fname} - \code{file\_name + `\_' + marker + `\_' + str(index) + `.txt'}
			\item \code{fit\_fname} - \code{file\_name + `\_' + marker + `\_' + str(index) + `\_fits.txt'}
			\item \code{parameter\_str} - the json string created from \code{self.parameters}
			\item \code{origin\_import\_fits} - header created to be read by Origin.
		\end{enumerate}
		\item Outputs: \code{None}
	\end{itemize}
\end{enumerate}
\end{document}