text:
\documentclass[DM,authoryear,toc]{lsstdoc}
% lsstdoc documentation: https://lsst-texmf.lsst.io/lsstdoc.html
\input{meta}

% Package imports go here.

% Local commands go here.

%If you want glossaries
% \input{aglossary.tex}
% \makeglossaries

\title{Guidelines for Community Participation in Data Preview 0}

% Optional subtitle
% \setDocSubtitle{A subtitle}

\author{The Community Engagement Team and the Operations Executive Team}

\setDocCurator{Melissa Graham}
\setDocRef{RTN-004}
\setDocUpstreamLocation{\url{https://github.com/rubin-observatory/rtn-004}}

\date{\vcsDate}

% Optional: name of the document's curator
% \setDocCurator{The Curator of this Document}

\setDocAbstract{%

In 2021 the Rubin Observatory began Data Preview 0 (DP0), the first of three data previews during the period leading up to the start of Rubin Operations.
DP0 makes simulated LSST-like data products, which are similar to the future LSST data releases, available in the Rubin Science Platform (RSP).
The goals of DP0 are to serve as an early integration test of the LSST science pipelines and the RSP and to enable the community to prepare to do science with the unprecedented LSST data set.
To meet these goals, the Rubin Observatory will support a total of 600 RSP accounts for "DP0 delegates": individuals who will represent the science community as early users of the RSP.
DP0 delegates benefit from an accelerated learning experience with the RSP's query, visualization, and analysis tools; are free to pursue their own science with the DP0 data set in the RSP; and have opportunities to provide feedback about their experience to Rubin Observatory.
Of these 600 accounts, 300 were allocated in 2021 as part of Phase 1 (DP0.1) and 300 new accounts will be allocated in 2022 for Phase 2 (DP0.2).
As the number of RSP accounts for community access to DP0 is limited, a set of guidelines for how Rubin Observatory should select the participants is required.
This document describes the diversity-driven application and selection process for DP0 delegates, and briefly describes some of the resources, support, and activities that will be available to them.
}

% Change history defined here.
% Order: oldest first.
% Fields: VERSION, DATE, DESCRIPTION, OWNER NAME.
% See LPM-51 for version number policy.
\setDocChangeRecord{%
  \addtohist{1}{2020-12-18}{Released for circulation and feedback.}{Melissa Graham}
  \addtohist{2}{2021-01-27}{Released.}{Melissa Graham}
  \addtohist{3}{2022-01-05}{Updated prior to DP0.2.}{Melissa Graham}
}

\begin{document}

% Create the title page.
\maketitle
% Frequently for a technote we do not want a title page  uncomment this to remove the title page and changelog.
% use \mkshorttitle to remove the extra pages

\renewcommand{\thepage}{\arabic{page}}% Arabic numerals for page counter

\setcounter{page}{1}% Start page number

% ADD CONTENT HERE
% You can also use the \input command to include several content files.

\section{Introduction to Data Preview 0}\label{sec:intro}

There are three planned Data Previews (DPs) during the period leading up to the start of Rubin Operations, termed pre-operations.
DP0 is based on simulated data.
DP1 and DP2 will be based on data taken during Rubin Observatory commissioning; DP1 based on data taken with the Rubin Observatory Commissioning Camera (ComCam), and DP2 based on data taken with the LSST Camera (LSSTCam) -- the science instrument for Rubin Observatory.
DP0 started on June 30 2021 and will continue through 2022, with DP1 currently foreseen to begin in 2023.
The Data Previews will enable the community to access and analyze LSST-like data in the Rubin Science Platform (RSP) on a shared-risk basis.

\subsection{The Goals of DP0}\label{ssec:intro_goals}

As described in \citeds{RTN-001}, the two goals of DP0 are:
\begin{enumerate}
\item To serve as an early integration test of the Data Management System (DMS) and inform further development of Rubin's LSST Science Pipelines (hereafter LSST Science Pipelines) and the Rubin Science Platform (RSP).
\item To enable the community to learn to use the LSST data products and services, to prepare for early science with commissioning and year 1 data, and to provide feedback to Rubin Observatory.
\end{enumerate}

In order to achieve these goals, community participation in DP0 has two main components:
(1) performing scientific exercises with the data products and services in the RSP, and
(2) taking action to inform or enhance the performance of the DMS, the RSP, or the science community.

Participants from the science community, "DP0 delegates", are data rights holders\footnote{Data rights holders are US or Chilean scientists, or individuals associated with an International Contribution (in-kind) proposal in progress, as defined in \citeds{RDO-013}.} who represent a diversity of backgrounds.
The term "delegates" reflects the fact that these individuals are representing the science community as learners and as contributors to the achievement of the DP0 goals, as an essential step along the path towards the success of the LSST.

\subsection{The Total Number of DP0 Delegates}

For provenance, the {\it initial} plan for DP0 (as of Jan 2021) was to have a total of 300 RSP user accounts available at the Interim Data Facility (IDF; the Google Cloud Platform\footnote{\url{https://www.lsst.org/news/rubin-observatory-will-partner-google-cloud-host-interim-data-facility}}) for DP0 delegates, with 75\% allocated for Phase 1 (DP0.1) by Jun 2021, and 25\% reserved for Phase 2 (DP0.2) in 2022 (see Section \ref{ssec:sel_dp01}).

However, the first few months of DP0.1 went so well that Rubin Observatory leadership decided to allocate RSP accounts to all of the DP0.1 applicants, and add 300 new accounts for DP0.2.
Thus, {\bf the total number of RSP accounts supported for DP0 will be 600}, and these 300 new accounts will be allocated by Jun 2022 (see Section \ref{ssec:sel_dp02}).
For reference, 600 RSP accounts for community participants marks an order of magnitude increase in the number of community accounts made available to Stack Club\footnote{\url{https://github.com/LSSTScienceCollaborations/StackClub}} members.

The number of RSP accounts remains limited during the Rubin Observatory construction and pre-operations phase -- and especially for DP0 -- due to the Rubin pre-operations team's limited scope in providing support for data products, software, and services that are still in development.
An order of magnitude increase represents a safe and sustainable scaling up of the Data Management System, which is also still in development, at the IDF.

In addition, there will be $\sim$150 accounts to cover all Rubin Observatory staff members who need one (e.g., Data Production, System Performance, and construction Commissioning, and Community Engagement team members), and to cover members of International Program teams who require DP0 access in order to complete their in-kind deliverables\footnote{Anyone in this situation should contact their Program Manager and Melissa Graham.}.

It is a primary goal of the Rubin pre-operations team to provide RSP access as soon as possible to all data rights holders over the course of the data previews.
At least by the start of Rubin Observatory Operations, all data rights holders will be able to have RSP accounts.

\subsection{Research Inclusion}\label{ssec:intro_RI}

There are 4 main ways in which research inclusion for DP0 is being supported: broad advertising, a staged application process, on-boarding resources, and flexible time commitments.

Broad advertising is necessary for delegates to self-identify as potential participants, and for reaching potential delegates who are not yet actively participating in Rubin science.
The CET works with the Rubin Observatory communications team to ensure the call for applications is broadly advertised.
The CET also works with the Rubin directorate to identify individuals, especially those at small or under-resourced institutions (Group D, Section \ref{ssec:sel_grps}), and to reach out directly to encourage applications.

A two-stage application process for DP0.1 and 0.2 is implemented to maximize the inclusion of delegates who would not be able to make a time commitment at the start of DP0.1, and because it is recognized that it might take time to achieve a diverse set of DP0 delegates and to provide equitable access to DP0.
For example, the advertisements must percolate, people must free up time in their schedules or obtain grants to fund their work, and the DP0-related resources and support network will become enriched over time (and thus more attractive to a wider variety of participants).

On-boarding resources and a supportive community are generated and maintained by the CET (see Section \ref{ssec:res_sup} and the Delegates Homepage at \url{dp0-1.lsst.io}).
Such resources are recognized as necessary for delegates to acquire the benefits of DP0 participation, regardless of their past experience or expertise.

Flexible time commitments mean that delegates are free to do their DP0-related activities on whatever timescale works for them, and that there is no minimum time commitment or expected "start date" (Section \ref{ssec:intro_del}).

\subsection{The DP0 Simulated Data Set}\label{ssec:intro_dc2}

The simulated data set adopted for DP0 was generated by the Dark Energy Science Collaboration (DESC), and is being used under an agreement between the DESC and Rubin.
This data set is the second in a series of data challenges, and is thus named DC2.

As explained in the DESC's DC2 paper \citep{2020arXiv201005926L}, the core science goals that DC2 was developed to address are all extragalactic, such as weak lensing correlations and Type Ia supernova cosmology.
For these reasons, the full DC2 simulation is five years of observations of 300 square degrees of extragalactic regions in six filters with the initial (version 1) baseline survey strategy\footnote{For readers familiar with the term, the operations simulation "OpSim minion\_1016" was used, which represented the initial (version 1) baseline strategy. The 2021 recommendations from the Survey Cadence Optimization Committee (SCOC) about updates to the baseline strategy can be found in \url{ls.st/Document-37922}.}, plus one square degree of a deep drilling field (DDF).
Realistic observing conditions and a baseline survey strategy were applied.

The types of extragalactic objects simulated for DC2 include clusters, galaxies, Type Ia supernovae, and active galactic nuclei (AGN).
The types of galactic objects include stars, about 10\% of which have periodic or non-periodic variability.
DC2 does not include solar system objects, or other types of extragalactic transients such as tidal disruption events or core collapse supernovae.
A full description of the DESC's DC2 simulation can be found in \citep{2020arXiv201005926L}, and in particular the synthetic galaxy catalog is described in \citet{2019ApJS..245...26K}.

A subset of the full DC2 simulation is being used for DP0; this subset does not contain the DDFs and, since AGN were only injected into the DDFs, thus does not contain any simulated AGN.
The image processing outputs that are available as part of DP0 simulate the LSST data release (DR) data products for the wide-fast-deep (WFD) main survey at five years, and are referred to as DR6-WFD (for LSST, DR1 is 0.5 years of data, DR2 is the first year, etc.).
DR6-WFD includes the raw images, processed visit images (PVIs, where a visit is a single 30 second observation), source catalogs for the PVIs, coadded images for each band, and multi-band object catalogs for the coadds.

Further information about DC2 and the DP0 data set can be found in the DP0.1 documentation at \url{dp0-1.lsst.io}.

\subsection{Two Stages: DP0.1 and DP0.2}\label{ssec:intro_stages}

The DP0.1 data set contains the DC2 images and catalogs as processed by the DESC using the LSST Science Pipelines (v19.0.0).
The DP0.1 data products are available in the RSP in their original format as processed by the DESC, which is similar to that of planned LSST data products.
Because the DP0.1 data set release date was June 30 2021, the selection process for the first stage of delegates (Section \ref{ssec:sel_time}) was designed to complete by May 31 2021.
For DP0.1, it is important to note that the processing does not include difference image analysis, and that the catalog photometry is all from the direct images.
Furthermore, the source catalogs for the PVIs are unassociated and forced photometry has not been run on the visit images, which means that there are no time-domain object catalogs or light curves for DP0.1.
The DP0.1 data set will remain available after the release of the DP0.2 data set \citedsp{RTN-001}.

The DP0.2 data set will contain the DC2 images and catalogs reprocessed by Rubin Observatory using a more recent version of the LSST Science Pipelines than DESC used to process the DP0.1 products.
The DP0.2 data products will be available in the RSP in a format that is consistent with the planned LSST data products.
This might include additional data products that are produced by the pipelines as of Sep 2021, for example, difference image analysis (DIA) and DIA photometry are planned as additional DC2 data products for DP0.2.
The projected date by which the DP0.2 data products will be made available to DP0 delegates in the RSP is June 30 2022.
Therefore, in Section \ref{ssec:sel_time} the second stage of DP0 delegates are scheduled to have their accounts activated by May 31 2022.

Further details about the DP0.1 data set (e.g., table schema, image types) can be found in the DP0.1 documentation at \url{dp0-1.lsst.io}, and similar resources will be available for DP0.2.

There will also be a few capability differences between the two phases, which might affect some delegates' planned activities.
For example, in DP0.1, the notebook aspect of the RSP offered image access only via the Butler\footnote{The Butler is a middleware component of the DMS for persisting and retrieving image datasets.}, whereas in DP0.2 image access will be available via the Butler, Virtual Observatory (VO) services, and the Portal Aspect of the RSP.
Further details about capability differences can be found in \citeds{RTN-001}, and will be clarified in the DP0 documentation.

\subsection{Delegate Benefits and Responsibilities}\label{ssec:intro_del}

DP0 access comes with both benefits and responsibilities.

The anticipated {\bf benefits} for DP0 delegates include, for example:
\begin{itemize}
\item an accelerated learning experience in the Rubin Science Platform
\item expertise that could be useful for grant applications or early science publications
\item the potential to develop, e.g., analysis software, visualization tools, for LSST science
\item having options to publish or publicize the results of their DP0 work (software, analysis)
\item the ability to advocate for RSP developments beneficial to their scientific field
\end{itemize}

These potential benefits of DP0 participation motivate the focus on research inclusion (Section \ref{ssec:intro_RI}) and the prioritization of diversity in the selection process (Section \ref{sec:sel}).
Documentation resources and support for delegates, provided by Rubin Observatory, are necessary for delegates to obtain these benefits, and they are described in Section \ref{ssec:res_sup}.

The most important {\bf responsibility} is that DP0 delegates understand and abide by the policies for RSP accounts at the IDF (e.g., Acceptable Use, Code of Conduct, Data Rights), which are described in detail in Section \ref{ssec:res_pol}.
Delegates are also expected to learn how to use the RSP well enough to perform some basic scientific exercises, and then take a small action that informs or enhances the DMS, the RSP, or a Science Collaboration.
Such actions are envisioned to be simple and optional (they will not be tracked), and it will be left to the discretion of individual delegates to decide what kind of actions best match their interests and expertise.
Examples of delegate actions are provided in Section \ref{ssec:res_act}.

The time spent by DP0 delegates will not be tracked and there is no minimum (or maximum), but the estimated minimum time commitment for DP0 delegates to gain at least some of the benefits of participation is approximately 12--36 hours, total.
This would be, e.g., 1--3 hours per week over three months, but this time can be distributed in any manner that is convenient to the delegate, and allocated accounts do not expire.

\section{Delegate Selection Process}\label{sec:sel}

The primary goal of this application process is to ensure that DP0 promotes research inclusion.
More specifically, to ensure that the set of DP0 delegates includes the full range of diversity in the science community, and that the beneficial opportunities of DP0 participation are provided equitably to them.

A key component of Rubin Observatory's Community Engagement Model (\url{ls.st/RTN-006}) is to build a self-sustaining LSST science community that is able to crowd-source solutions.
Ensuring diversity among the DP0 delegates is key to seeding the distributed expertise that will be the foundation of this community: a network of users from a variety of global locations, institutional types, career stages, and astronomical fields -- a network that includes representatives of groups that are underrepresented in astronomy.

\subsection{Delegate Groups}\label{ssec:sel_grps}

Achieving the goals of DP0 requires a broad diversity in the DP0 delegates, each with their own experience, expertise, or novice perspective, and each representing and reporting back to different parts of the broader community.
To guide the selection process, the groups of DP0 delegates are defined in Table \ref{tab:delegate_groups}, and the \emph{approximate} percentage of delegates in each group estimated.
Representatives in all groups have the same expectations and responsibilities, as in Section \ref{ssec:intro_del}.
These groups are only used during the selection process.

\begin{table}[!h]
\centering
\caption{Approximate targeted distribution for diversity-based DP0 delegate groups.}\label{tab:delegate_groups}
\begin{tabular}{cccl}
\hline
 & \multicolumn{2}{c}{$\sim$\% for DP} & \\
Group & 0.1 & 0.2 & Description \\
\hline \hline
A & 10 & 5 & experienced users/builders of the DESC DC2 simulated data set \\
B & 10 & 5 & experienced users of science platforms (e.g., RSP, SciServer, DataLab) \\
C & 10 & 5 & scientific expertise in Rubin science pillars, deep imaging, big data, etc. \\
D & 10 & 20 & representatives of small and/or underserved US institutions and colleges \\
E & 10 & 30 & novice-level or new-to-Rubin learners and students (and advisors of students) \\
F & 10 & 10 & representatives of the Chilean astronomy community \\
G & 40 & 25 & representatives of the Science Collaborations \\
\hline
\end{tabular}
\end{table}

For Group D, the term 'small and/or underserved US institutions and colleges' refers to, among others: institutions that do not have an R1 or R2 Carnegie classification; institutions that do not grant doctorates in astronomy or physics; institutions that identify as a minority serving institution (MSI), a historically black college or university (HBCU), or a hispanic-serving institute (HSI); or institutions that have other similar aspects.

Applicants will be able to self-identify with {\it multiple groups} on the application form (Section \ref{ssec:sel_form}).
This means that, for example, Chilean astronomers and Science Collaboration members are not restricted to gaining a delegate position via Groups F and G respectively, Stack Club members are not restricted to Group B due to their RSP experience, and so on.

For DP0.1, about one quarter of the accounts in Group G (10\% of the total) were withheld from the selection process and made available for the Science Collaborations to assign to representatives engaging in DP0 related activities such as mentoring programs, thereby enabling such programs to exist.

For DP0.2, because support services have been ramped up and tested by novice and experienced participants during DP0.1, a larger proportion of the slots are being allocated to people who are likely new to Rubin.

\subsection{Application Form Contents}\label{ssec:sel_form}

A diversity-based selection process requires that adequate and appropriate information be collected from applicants.
The application form is self-contained and self-explanatory -- applicants do not have to refer to this document (or any other) in order to complete the form.
It provides introductory text with the deadline for consideration, the date by which applicants will be notified, and a point of contact; a description of who should and should not use the application form; the goals of DP0 and the types of data included in DESC DC2; who will see the contents of the submitted applications (which are confidential to the CET); and the expectations for DP0 delegates.

Keeping in mind that DP0 is intended to be welcoming to individuals who are new to Rubin and the LSST, the form also provides a description of who has data rights, and links to additional information about DP0, the LSST, and Rubin Observatory.

The DP0 application form questions include:
\begin{itemize}
\item email address (write-in)
\item full name (write-in)
\item institutional affiliation (write-in)
\item city and country of institutional affiliation (write-in)
\item career stage (multiple choice)
\item underrepresented groups (checkboxes)
\item LSST science interests (checkboxes)
\item delegate groups (checkboxes)
\end{itemize}

Applicants who selected "Group E", and are a student (or advisor) who would like an additional account for their advisor (or student), are invited to request a "Plus One" account (see Section \ref{ssec:sel_po}).

Applicants are furthermore requested to attest that they understand that "DP0 Delegates" have responsibilities and that they are willing to take them on, and to confirm that they have Rubin data rights.
Applicants from outside the US and Chile are requested to indicate which International Team they're a member of, and an "Other" option is provided for individuals who might still be confused about the process.
Rubin staff authenticate all applicants by cross-checking their name and affiliation with, e.g., institutional websites, the International Data Rights Holders List, in-kind project managers.

The application form does {\it not} ask people to, e.g., provide a robust scientific justification for their participation in DP0, or a detailed plan for their DP0 delegate activities.
While it might at first seem reasonable to consider aspects such as "science impact" or "contributed value" in a selection process like this, doing so could run counter to diversity initiatives.
For example, not all applicants will be equally able to express such aspects, especially if they are new to Rubin (regardless of career stage).
In a supportive environment with adequate resources (Section \ref{ssec:res_sup}), all DP0 delegates should have an equivalent potential to succeed in their endeavors, and so a "merit" aspect of this application process is not necessary.

\subsection{Selection Algorithm}\label{ssec:sel_alg}

The groups described in Section \ref{ssec:sel_grps} reserve a portion of the total DP0 slots for applicants with different levels of expertise and experience with Rubin Observatory or similar projects (including novice-level), and for applicants from Chile.
A diverse population of delegates by career stage, science interest, and from groups that are underrepresented in astronomy on the basis of gender, race, disability, sexual orientation, etc. is also desired for DP0.

To achieve this, a simple selection algorithm was developed in which every applicant is assigned a weight factor, based on their career stage, science interest, and underrepresented identity.
The weight values are proportional to the fraction of applicants with those characteristics divided by a target fraction for that demographic.
Target fractions for: (1) career stage are based on promoting junior researchers; (2) science interest are approximately flat across each of the four LSST science pillars and interests outside the pillars; and (3) underrepresented identities are based on the US population.

For each of the Groups A through G (in order; Section \ref{ssec:sel_grps}), a weighted random selection is made from the pool of delegates that indicated membership in the group.
If an applicant was a member of multiple groups, after they are selected they are removed from the pool for the other groups (i.e., they cannot be selected more than once).
This selection process is done 1000 times, with applicants scoring a point every time they're selected.
A score-ranked list of applicants is then used to identify delegates and a waitlist.
The Jupyter Notebook that ran this selection algorithm for DP0.1 is available at \url{ls.st/Document-37722}.

A very similar selection algorithm will be adopted for DP0.2, if the applications are oversubscribed.
In the case of significant undersubscription from any targeted demographic (such as the delegate Groups, career stage, science interest, or underrepresented identity) or if there is a general lack of diversity in the applicant pool, some accounts will remain unassigned and a campaign of targeted advertising or participation invitations will be designed and deployed.
However, if the applications are undersubscribed but the pool is diverse, all applicants would be allocated an account.

\subsection{Plus Ones}\label{ssec:sel_po}

The concept of a "Plus One" for DP0 is that a student (or advisor) can apply to participate in DP0, and then be allocated an additional account for their advisor (or student).
The option for "Plus Ones" was intended to enable teamwork within local institutes and to enable research opportunities for students and for time-constrained advisors.
DP0 delegates allocated a "Plus One" do not need to name them at the time of their account allocation (i.e., in June 2021 or 2022), and can wait until later to have their "Plus One" account allocated (i.e., after the school year starts).
All "Plus Ones" must have Rubin data rights.

For DP0.1, the popularity of this option was underestimated: about $\sim$60 applicants requested a "Plus One" but only 10 accounts within Group E had been reserved for the "Plus Ones".
By November 2021, all applicants who had requested a "Plus One" account had been invited to provide a name.

For DP0.2, $\sim$50 accounts will be reserved for "Plus Ones".
Part of the reasoning behind increasing the number of "Plus Ones" to allocate is that, anecdotally, for scientists with a limited amount of research time the projects for which they are best able to make progress are the ones being used for student research.
Furthermore, the scientists with the most limited amount of research time are those with heavy teaching loads, which are more likely to be at small or underserved institutions.

\subsection{Selection Timeline}\label{ssec:sel_time}

The application due dates are set as late as possible to allow sufficient time for people to learn about DP0 and decide whether to invest time in participating.
Delegates will be notified at least one month in advance of DP0 data becoming available in the RSP (and potentially earlier, if the applications are not oversubscribed).
These dates are provided in Table \ref{tab:selection_timeline}.
As described in Section \ref{ssec:intro_del}, delegates need not begin their DP0.1 participation at the time of account activation, and may distribute their time over DP0 at their convenience.

\begin{table}[!h]
\centering
\caption{Applicants who submit by the dates in column 3 will be notified by the dates in column 4.}\label{tab:selection_timeline}
\begin{tabular}{lllll}
\hline
Stage & Applications Due & Delegates Notified & Data Available \\
\hline \hline
DP0.1 & Apr 30 2021   &  May 31 2021  &  Jun 30 2021 \\
DP0.2 & Apr 30 2022   &  May 31 2022  &  Jun 30 2022 \\
\hline
\end{tabular}
\end{table}

\subsection{DP0.1 Allocations}\label{ssec:sel_dp01}

When the DP0.1 selection algorithm was run in May 2021, the total number of DP0 accounts was set at 300 (not 600) and 25\% of them were reserved for DP0.2.
After subtracting the 30 accounts reserved for the Science Collaborations, that left 203 accounts to be allocated for DP0.1.
Ten of those were for "Plus Ones" (see Section \ref{ssec:sel_po}), leaving 193 allocated via the selection process.
For DP0.1, applications were oversubscribed by a factor of $\sim$1.4 with respect to this number of 193, and there was a waitlist.
Over $95\%$ of the initial invitations to participate in DP0 were accepted by applicants, meaning they took action to set up their access to the RSP and attend the kick-off information sessions in July 2021.
A few additional applicants were invited from the waitlist to compensate for the unresponsive applicants.

The first few months of DP0.1 went so well that by November 2021, the decision to increase the total number of DP0 accounts to 600 had been made.
At that time, everyone on the waitlist was invited to participate and the option to identify a "Plus One" was extended to all delegates who had requested one.
The rate at which invitees took action to set up their RSP accounts for DP0 was lower than in the early phases.
By December 2021, there were 244 delegates with RSP accounts.

\subsection{New DP0.2 Initiatives}\label{ssec:sel_dp02}

For DP0.2, $\sim$50 RSP accounts will be reserved for special circumstances that further enable science with DP0 and LSST preparatory work within the science community.
These remain to be determined at the discretion of the Rubin Observatory Director for Operations, but examples include accounts for:
\begin{itemize}
\item PIs of successful grant proposals that are LSST related (e.g., NSF AAG)
\item the first cohort of LSST Catalyst fellows (and their "Plus Ones")
\item representatives of the alert broker teams
\item developers of photometric redshift estimators (see \citeds{dmtn-049})
\item "Plus Ones" for Rubin staff advising students on DP0 research projects
\end{itemize}

The last item, "Plus Ones" for Rubin staff, has been added so that staff can avoid any apparent bias or conflict of interest in the selection process that might arise if those students applied, and so that Rubin staff can boost their own DP0-related science productivity with their discretionary science time, which would have a positive impact on DP0 as a whole when that work is shared with other delegates.

Formally, these $\sim$50 accounts would come from the 300 (new) accounts being made available for DP0.2.
However, since as of December 2021 there were only 244 DP0.1 delegates with RSP accounts (out of the 300 DP0.1 accounts; Section \ref{ssec:sel_dp01}), it is likely that these $\sim$50 accounts will absorb the DP0.1 leftovers and that all 300 new DP0.2 accounts will be allocated via the selection algorithm described in Section \ref{ssec:sel_alg}

\section{Policies, Resources, and Activities for DP0 Delegates}\label{sec:res}

For a full description of all of the policies, support resources, and activities for DP0 delegates, see the DP0.1 documentation at \url{dp0-1.lsst.io}.

\subsection{Policies for RSP Accounts}\label{ssec:res_pol}

For the duration of DP0, an instance of the RSP will be running at the IDF.
All individuals selected as DP0 delegates will be offered accounts in this deployment of the RSP.

The applicable policies are that DP0 delegates:
\begin{itemize}
\item abide by the Rubin Observatory data policy \citedsp{RDO-013}
\item comply with the Acceptable Use Policy
\item follow the Code of Conduct
\item do not share accounts or passwords
\item follow the on- and off-boarding steps
\item understand the risks inherent in using an in-development platform
\item use the appropriate citations and acknowledgements
\item report bugs and issues when encountered
\end{itemize}

The full details for these policies, and more information about the risks and appropriate use of the RSP, are provided in the DP0 documentation (e.g., \url{dp0-1.lsst.io}) and are reviewed during the initial kick-off info sessions that all new delegates must attend (or watch a recording of).

A full list of DP0 acknowledgements and references for delegates who publish results based on their DP0 activities with the DC2 data set in the RSP are provided in the DP0 documentation (e.g., \url{dp0-1.lsst.io}).
For example, DP0 delegates who publish results based on the DC2 simulation are requested to reference the DESC's DC2 paper, \citet{2020arXiv201005926L}.

\subsubsection{Rubin Data Rights and DP0}

Access to the RSP and the DP0 data products and services are limited to data rights holders, and all DP0 delegates must abide by the Rubin Data Policy in \citeds{RDO-013}.

In the Rubin Data Policy, items DPOL-302 and DPOL-507 describe how only data rights holders may have Rubin Science Platform accounts, and this is why DP0 participants must have data rights.
The simulated data sets used for DP0 are world-public in the language of DPOL-301, which means that the data can be shared with anyone, but does not mean the data will be served publicly.
Anyone may publish results based on analyses of world-public data sets.
DP0 is therefore a special case: the commissioning data planned for release in DP1 and DP2, and subsequently the survey data, will have a 2-year proprietary period before it is able to be shared with non data rights holders.

Delegate authentication for RSP access (confirming that an applicant has Rubin Data rights) is done by the Rubin staff.
Delegate authorization for RSP access is done by inviting authenticated delegates' to join the {\tt rubin-dp0} GitHub Organization's {\tt Delegates} team.
Only individuals whose GitHub accounts are associated with that team may log into the RSP at \url{data.lsst.cloud}.

\subsubsection{Oversubscription and Unused Accounts}

As the total number of accounts will be limited, if applications are oversubscribed then delegates who don't appear to be using their accounts {\it might} be periodically contacted and asked to consider voluntarily deactivating to make way for others.
In the case of a high oversubscription for DP0 participation, account holders who do not respond to \emph{multiple} such inquiries \emph{might} have their access suspended to make way for others.
It is understood that delegates might, for example, not have the work-hours to start using their accounts for a few months (due to prior commitments, teaching loads, etc.), and individuals in this situation would need only reply to confirm interest and intent.
Note that this is a temporary measure for the Data Previews, and not how accounts will be managed during Operations.

\subsection{Resources and Support for Delegates}\label{ssec:res_sup}

It is recognized that resources and support provided by Rubin Observatory will be necessary to enable equitable access and benefits for all delegates, including novice science platform users (Section \ref{ssec:intro_RI}).
However, potential DP0 delegates should be aware that the Rubin Observatory pre-operations team is still building their support resources and infrastructure, and some patience might be required.
A full description of Rubin Observatory's Community Engagement Model, which DP0's resources and support venues are based on, is avialable at \url{ls.st/RTN-006}.

The support venues and learning resources for DP0 delegates are described in full in the DP0 documentation (e.g., \url{dp0-1.lsst.io}). As a brief summary, they include:
\begin{itemize}
\item instructions and tutorials for using the RSP and the DP0 data set
\item live virtual biweekly seminars ("Delegate Assemblies", all recorded)
\item dedicated Q\&A categories in the Rubin Community Forum
\item a shared GitHub repository for collaboration
\item networking opportunities (working groups, peer mentoring, flash talks)
\item bug reporting and technical assistance via GitHub issues
\end{itemize}

DP0 delegates are responsible for engaging with the resources, and asking questions when needed, in order to learn about the RSP and the DP0 data set and obtain the benefits of DP0 participation (Section \ref{ssec:intro_del}).
Creating or enhancing the DP0 resources and support infrastructure -- e.g., writing tutorial notebooks, leading a collaborative working group, helping other delegates resolve issues -- are all potential delegate actions (Section \ref{ssec:res_act}).

\subsection{Example Delegate Actions}\label{ssec:res_act}

As described in Section \ref{ssec:intro_del}, DP0 delegates are expected to learn how to do scientific analyses in the RSP, and then take action that informs or enhances the DMS, the RSP, or a Science Collaboration.

The objective is for these delegate actions to extend the benefits of DP0 beyond the limited number of DP0 participants that Rubin Observatory is able to support, and to maximize the impact of DP0 with respect to the goals of testing and informing development of the RSP and preparing the scientific community for early science (Section \ref{ssec:intro_goals}).

These actions are envisioned to be simple and enjoyable, and they are completely voluntary and will not be tracked.
Group work is encouraged.
It is left to individual delegates to decide what kind of actions best match their interests and expertise.

Examples of potential delegate actions include but are not limited to:
\begin{itemize}
\item participate in feedback surveys managed by Rubin Observatory
\item work through an "RSP Test Checklist" provided by Rubin Observatory
\item engage in DP0-related discussions via the Community Forum
\item provide a public demo of the RSP or a science analysis (e.g., Jupyter Notebook)
\item post small written reports or recorded demos on DP0 work (e.g., in the Forum)
\item give a short presentation during a Delegate Assembly
\item participate in working groups composed of other DP0 delegates
\item help to resolve reported issues or support other delegate's work
\end{itemize}

\appendix
% Include all the relevant bib files.
% https://lsst-texmf.lsst.io/lsstdoc.html#bibliographies
\section{References} \label{sec:bib}
\renewcommand{\refname}{} % Suppress default Bibliography section
\bibliography{local,lsst,lsst-dm,refs_ads,refs,books}

% Make sure lsst-texmf/bin/generateAcronyms.py is in your path
\section{Acronyms}
\input{acronyms.tex}
% If you want glossary uncomment below -- comment out the two lines above
%\label{sec:acronyms}
%\printglossaries

% \input{checklist}
\end{document}


text:
\section{Implementation}
Most of the theory behind RS and the methodology it depends on have already been introduced.
The implementation of a RS will be described in the following.
All examples have been written in a programming language called Python.
There is also some SQL code and some UML- and EER-diagrams in order to visualize the concept.
As database \gls{sqlite3} has been used.

\subsection{Content based RS in-depth}
\label{sec:implementation-contentbased}
The general framework for a content-based RS is shown in figure~\ref{fig:framework-contentbasedrs}.
There are three main components a content-based RS consists of.
\begin{itemize}
    \item \textbf{Content Analyzer}\hfill\\
        Since all items the RS has to work with are potentially unstructured, a pre-process is necessary to filter relevant information.
        This will be mainly done by IR-techniques.
        The Content Analyzer aims to bring all items in a form which can be used by its successional components.
        \citep[p.~75-77]{lops:2011}
    \item \textbf{Profile Learner}\hfill\\
        When the items are in a suitable form, the Profile Learner can construct a user profile.
        In case of Rocchio's algorithm this includes to distinguish all relevant items from non-relevant.
        Based on all items and the user's preferences the Profile Learner can build a user profile.
        Rocchio's algorithm uses a vector representing the users attitude towards different attributes of an item.
        In case of Rocchio, the user profile is a vector representing his attitude towards the different attributes an item may have.
        \citep[p.~75-77]{lops:2011}
    \item \textbf{Filtering Component}\hfill\\
        For each user profile the Filtering Component can find items which may match the users preferences.
        Depending on the method implemented the result can be a binary or continuous relevance judgment.
        The continuous relevance judgement is a list of ranked items.
        \citep[p.~75-77]{lops:2011}
        The RS implemented for this thesis uses k-nearest-neighbours classification.
        kNN results in a list of ranked items where $k$ best-ranked items will be suggested to the user.
\end{itemize}

\begin{figure}[h]
    \center
    \includegraphics[scale=0.4,clip=true,trim=24px 0 15px 0]{inc/implementation/HighlevelContentBased}
    \caption{High level description of a content-based RS.\citep[p.~76]{lops:2011}}
    \label{fig:framework-contentbasedrs}
\end{figure}

\input{inc/implementation/contentanalyzer/contentanalyzer}
\FloatBarrier
\input{inc/implementation/profilelearner/profilelearner}
\FloatBarrier
\input{inc/implementation/filteringcomponent/filteringcomponent}
\FloatBarrier

\subsection{Recommender library}
"Recommender library" labels the whole programming code which has been written for this thesis to a build programming library capable of creating item recommendations based on Rocchio's algorithm as declared in the milestones (figure~\ref{fig:softwaremilestones}).
In short it will be called "recommender.lib".
Since the previous sections already solved the goals defined by the milestones up to the library, this section describes recommender.lib's usage.

Following tasks are managed by recommender.lib:
\begin{itemize}
    \item Adding and removing products which can be recommended
    \item Creating, updating and removing users
    \item Making recommendations based on a user profile
\end{itemize}

\paragraph{Initialize recommender.lib}
In order to use recommender.lib on has to connect it to a database.
All database-tables required by recommender.lib will be created automatically when needed.
As main component \textit{DatabaseManager} delegates all tasks to other classes and gives access to them.
\begin{lstlisting}[language=Python,caption={Startup of recommender.lib},label={lst:recommenderlib-startup}]
import recommender
databasepath = "./database/recommender.sqlite3"
manager = recommender.DatabaseManager(databasepath)
\end{lstlisting}

\paragraph{Insert products}
With \textit{DatabaseManager} one can retrieve \textit{ProductManager} who is responsible for inserting and deleting products.
Afterwards a product can be added.
A product is no more than a collection of terms which describe it.
A term can be added by \textit{Product.add\_term()} with an optional second parameter describing its frequency.
If the parameter is omitted, the term's frequency will be set to 1.
\textit{Product} as derived class of \textit{Document} has an image\_name as special tweak which is used to store the file path of an image which represents the product.
\begin{lstlisting}[language=Python,caption={Insertion of products},label={lst:recommenderlib-product-insertion}]
product_manager = manager.get_product_manager()
p = recommender.product.Product()
p.image_name = 'image_01.png'
p.add_term('white')
p.add_term('blouse', 1)
product_manager.add_document(p)
\end{lstlisting}

\paragraph{Get product vectors}
With products added one can easily get their vectors (for example their \textit{tf-idf}-vectors).
In order to do so, one calls \textit{ProductVectorManager.get\_tfidf\_vector()} with the corresponding document\_id.
\textit{ProductVectorManager} also offers methods for creating \textit{tf}-, \textit{df}- and \textit{idf}-vectors.
When new products have inserted afterwards one has to delete all cached items of the \textit{ProductVectorManager} by calling \textit{ProductVectorManager.flush()}.
\begin{lstlisting}[language=Python,caption={\textit{tf-idf} vector of a product},label={lst:recommenderlib-product-vector}]
pvm = manager.get_product_vector_manager()
tfidf_vector = pvm.get_tfidf_vector(1)
print(tfidf_vector.values)  # prints: (0.0, 0.0)
\end{lstlisting}

\paragraph{Add users}
As next step a user will be created with \textit{UserVectorManager}.
Any user requires a user name which identifies him.
Recommender.lib however gives any user a unique id.
Methods working on users either require a \textit{user\_name} or \textit{user\_id}.
When a user is freshly created his vector will consist of numeric null.
\begin{lstlisting}[language=Python,caption={Add user},label={lst:recommenderlib-user-add}]
uvm = manager.get_user_vector_manager()
user_name = 'test_user'
uvm.create_user(user_name)
user_id = uvm.get_user_id_for_name(user_name)
user_vector = uvm.get_user_vector_for_id(user_id)
print(user_vector.values)   # prints: (0.0, 0.0)
\end{lstlisting}

\paragraph{Execute Rocchio's algorithm}
At the time there are both products available and users created one can start collecting user feedback.
Assuming that the user gives positive feedback towards the currently single product available the following listing will execute it.
The product will be marked as relevant and Rocchio's algorithm applied.
\begin{lstlisting}[language=Python,caption={Execute Rocchio's algorithm},label={lst:recommenderlib-rocchio}]
product_id = 1
uvm.set_user_preference(user_id, product_id, True)

relevant = uvm.get_relevant_document_vector_list(user_id)
non_relevant = uvm.get_non_relevant_document_vector_list(user_id)

updated_user_vector = recommender.rocchio.calculate(user_vector, relevant, non_relevant)
uvm.update_user_vector(user_id, updated_user_vector)
\end{lstlisting}

\paragraph{Finding recommendations}
Finally one can search for products which are similar to the user's vector.
This can be done by using \textit{k-nearest-neighbours} on the list of products and a user.
As a result a list with $k$ entries will be returned.
This list represents all recommendations.
Since kNN requires a distance-function for finding the nearest neighbours one can pass either a custom one, or use one of the pre-defined ones.
Currently supported are euclidean and hamming distance.
Because this kNN-implementation returns a combination of the distance and product-vectors, the vectors may have to be extracted.
\begin{lstlisting}[language=Python,caption={Retrieving recommendations},label={lst:recommenderlib-knn}]
distance_function = recommender.vector.arithmetic.euclidean_distance
k = 3
list_of_products = pvm.get_all_vectors()
meta_recommendations = recommender.vector.arithmetic.k_nearest_neighbours(
    k,
    updated_user_vector,
    list_of_products,
    distance_function
)
recommendations = [ vector for (distance, vector) in meta_recommendations ]
\end{lstlisting}

%Umfang und Aufgaben der Lib erkl\"aren.
\subsection{Web-API}
In order to operate the library from different programming languages except from Python a \gls{web api} has been implemented.
This API offers the most frequently function-calls a program using recommender.lib will require.
The online-shop introduced in section~\ref{sec:online-shop} has been written in \gls{javascript} calling the \gls{web api}.
Any request received by the web api through \gls{http} will result in a result containing a \gls{json} document.
An exhaustive list of all functions offered by the \gls{web api} and their return value is available in the appendix~\ref{sec:web-api}.

\input{inc/implementation/onlineshop/onlineshop}
\FloatBarrier

ext: tex

max_stars_repo_name: dustywind/bachelor-thesis

max_issues_repo_name: dustywind/bachelor-thesis

max_forks_repo_name: dustywind/bachelor-thesis


text:
%% $Id$

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\documentclass[english]{article}
\usepackage[latin1]{inputenc}
\usepackage{babel}
\usepackage{verbatim}

%% do we have the `hyperref package?
\IfFileExists{hyperref.sty}{
   \usepackage[bookmarksopen,bookmarksnumbered]{hyperref}
}{}

%% do we have the `fancyhdr' or `fancyheadings' package?
\IfFileExists{fancyhdr.sty}{
\usepackage[fancyhdr]{latex2man}
}{
\IfFileExists{fancyheadings.sty}{
\usepackage[fancy]{latex2man}
}{
\usepackage[nofancy]{latex2man}
\message{no fancyhdr or fancyheadings package present, discard it}
}}

%% do we have the `rcsinfo' package?
\IfFileExists{rcsinfo.sty}{
\usepackage[nofancy]{rcsinfo}
\rcsInfo $Id$
\setDate{\rcsInfoLongDate}
}{
\setDate{2018/09/30}
\message{package rcsinfo not present, discard it}
}

\setVersionWord{Version:}  %%% that's the default, no need to set it.
\setVersion{=PACKAGE_VERSION=}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\begin{document}

\begin{Name}{1}{hpcrun}{The HPCToolkit Performance Tools}{The HPCToolkit Performance Tools}{hpcrun:\\ Statistical Profiling}

\Prog{hpcrun} is profiling tool that collects call path profiles of program executions
using statistical sampling of hardware counters, software counters, or timers.

See \HTMLhref{hpctoolkit.html}{\Cmd{hpctoolkit}{1}} for an overview of \textbf{HPCToolkit}.

\end{Name}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Synopsis}

\Prog{hpcrun} \oOpt{profiling-options} \Arg{command} \oOpt{command-arguments}

\Prog{hpcrun} \oOpt{info-options}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Description}

\Prog{hpcrun} profiles the execution of an arbitrary command \Arg{command} using statistical sampling.
\Prog{hpcrun} can profile an execution using multiple sample sources simultaneously,
supports measurement of applications with multiple processes and/or multiple threads, and handles complex runtime behaviors including
fork, exec, and/or dynamic loading of shared libraries.
\Prog{hpcrun} can be used in conjunction with program launchers such as \texttt{mpiexec} and SLURM's \texttt{srun}.

To profile a statically-linked executable, make sure to link with \HTMLhref{hpclink.html}{\Cmd{hpclink}{1}}.

To configure \Prog{hpcrun}'s sampling sources, specify events and periods using the \texttt{-e/--event} option.
For an event \emph{e} and period \emph{p}, after every \emph{p} instances of \emph{e}, a sample is generated that causes \Prog{hpcrun} to inspect the
current calling context and augment its execution measurements of the monitored \Arg{command}.

If no sample source is specified, by default \Prog{hpcrun} profile using the timer
CPUTIME on Linux or WALLCLOCK on Blue Gene at a frequency of 200 samples per second per thread.

When \Arg{command} terminates, a profile measurement database will be written to the directory:\\
\\
\SP\SP\SP \Prog{hpctoolkit-}\Arg{command}\Prog{-measurements}[\Prog{-}\Arg{jobid}]\\
\\
where \Arg{jobid} is a parallel job launcher id associated with the execution, if available.

\Prog{hpcrun} allows you to abort an execution and write the partial profiling data to disk by sending a signal such as SIGHUP or SIGINT
(which is often bound to Control-c).
This can be extremely useful to collect data for long-running or misbehaving applications.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Arguments}

%% SKW 7/6/18:
%%
%% The following arguments are implemented in hpcstruct's "Args.cpp" but are deprecated
%% and so not documented here, per JohnMC
%%
%%     agent-c++
%%     agent-cilk
%%     loop-intvl
%%     loop-fwd-subst
%%     -N / -normalize

Default values for optional arguments are shown in \{\}.

\subsection{Command}

\begin{Description}
\item[\Arg{command}] The command to profile.

\item[\Arg{command-arguments}] Arguments to the command to profile.
\end{Description}

\subsection{Options: Informational}

\begin{Description}
\item[\Opt{-l}, \Opt{-L}, \Opt{--list-events}]
List available events. (N.B.: some may not be profilable)

\item[\Opt{-V}, \Opt{--version}]
Print version information.

\item[\Opt{-h}, \Opt{--help}]
Print help.
\end{Description}

\subsection{Options: Profiling}

\begin{Description}

\item[\Opt{-ds}, \Opt{--delay-sampling}]
Don't start sampling until the application enables sampling under program control.
Use this option to measure specific intervals in an application's execution by bracketing code
regions where measurement is desired
with calls to \Prog{hpctoolkit_sampling_start()} and \Prog{hpctoolkit_sampling_stop()}.
Sampling may be started and stopped any number of times during an execution;
measurements from all measurement intervals are aggregated.

\item[\OptArg{-e}{event\Lbr@howoften\Rbr}, \OptArg{--event}{event\Lbr@howoften\Rbr}]
\Arg{event} may be an architecture-independent hardware or software event supported by Linux perf, a native hardware counter event,
a hardware counter event supported by the PAPI library, a Linux system timer (\Prog{CPUTIME} and \Prog{REALTIME}), or the
operating system interval timer \Prog{WALLCLOCK}.
This option may be given multiple times to profile several events at once.
While events measured using the Linux perf monitoring infrastructure will be transparently multiplexed if necessary,
for other sampling sources or on operating systems such as the Blue Gene Compute Node Kernel,
there may be system-dependent limits on how many events can be profiled simultaneously and on which events may be combined for profiling.
If the value for \Arg{howoften} is a number, it will be interpreted as a sample period.
For Linux perf events, one may specify a sampling frequency for \Arg{howoften} by writing f before a number.
For instance, to sample an event 100 times per second, specify \Arg{howoften} as '@f100'.
For Linux perf events, if no value for \Arg{howoften} is specified, \Prog{hpcrun} will monitor the event using frequency-based sampling at 300 samples/second.
\begin{itemize}
  \item For timer events \Prog{CPUTIME}, \Prog{REALTIME}, and \Prog{WALLCLOCK}, the units for a sample period are microseconds.
  \item Timer events should not be mixed with hardware events.
  \item See the ``Sample sources'' under \textbf{NOTES} for additional details.
\end{itemize}

\item[\OptArg{-c}{howoften}, \OptArg{--count}{howoften}]
                       Only available for events managed by Linux perf. This option
                       specifies a default value for how often to sample. The value for \Arg{howoften} may be a number that will be used as a default
                       event period or an f followed by a number, e.g. f100, to specify a default sampling frequency in samples/second.

By default, \Prog{hpcrun} will allow attribution of hardware counter events to have arbitrary skid.
Some processor architectures, e.g., ARM,  don't support attribution with any higher level of precision.
If a processor does not support the specified level of attribution precision for a hardware counter event,
\Prog{hpcrun} may record 0 occurrences of the event without reporting an error.

\item[\OptArg{-f}{frac}, \OptArg{-fp}{frac}, \OptArg{--process-fraction}{frac}]
Measure only a fraction \Arg{frac} of the execution's processes.
For each process, enable measurement of each thread with probability \Arg{frac}, a real number or a fraction (1/10) between 0 and 1.
To minimize perturbations, when measurement for a process is disabled
all threads in a process still receive sampling interrupts but they are ignored.

\item[\OptArg{-lm}{size}, \OptArg{--low-memsize}{size}]
Allocate an additional segment to store measurement data
whenever free space in the current segment is less than the specified \Arg{size}.
If not given, the default for \Arg{size} is~80K.

\item[\OptArg{-m}{switch}, \OptArg{--merge-threads}{switch}]  Merge non-overlapped threads into one virtual thread.
                       This option is to reduce the number of generated
                       profile and trace files as each thread generates its own
                       profile and trace data. The options are:
\begin{itemize}
   \item 0 : do not merge non-overlapped threads
   \item 1 : merge non-overlapped threads (default)
\end{itemize}

\item[\OptArg{-ms}{size}, \OptArg{--memsize}{size}]
Use the specified \Arg{size} as segment size when allocating memory for measurement data.
The specified value is rounded up to a multiple of the `system page size.
If not given, the default for \Arg{size} is~4M.

\item[\OptArg{-mp}{prob}, \OptArg{--memleak-prob}{prob}]
Monitor a subset of memory allocations performed by the application to detect leaks.
An allocation is a call to one of \Prog{malloc}, \Prog{calloc}, \Prog{realloc}, etc\.
and its matching call to \Prog{free}.
At each allocation HPCToolkit generates a pseudo-random number in the range [0.0, 1.0)
and monitors the allocation if the number is less than the value \Arg{prob} specified here,
The value may be written as a a floating point number or as a fraction.
If not given, the default for \Arg{prob} is~0.1.

\item[\OptArg{-o}{outpath}, \OptArg{--output}{outpath}]
Directory to receive output data.
If not given, the default directory ia \Prog{hpctoolkit-<command>-measurements[-<jobid>]}.
\begin{itemize}
 Caution: If no <jobid> is available and no output option is given,
 profiles from multiple runs of the same <command> will be placed into the same output directory,
 which may lead to confusing or incorrect analysis results.
\end{itemize}

 \item[\Opt{-r}, \Opt{--retain-recursion}]
Do not collapse simple recursive call chains.
Normally as \Prog{hpcrun} monitors an application that employs simple recursion, it collapses call chains of recursive calls to a single level.
This design enables a user to see how the aggregate costs of recursion are associated with each recursive call yet
saves space and time during post-mortem analysis by collapsing long chains of recursive calls.
If this option is given, \Prog{hpcrun} will record all elements of a recursive call chain.
Note: When you use the \Prog{RETCNT} sample source this option is enabled automatically
to gather accurate counts.

\item[\Opt{-t}, \Opt{--trace}]
Generate a call path trace in addition to a call path profile.

\end{Description}

\subsection{Options: HPCToolkit Development}

\begin{Description}

These options are intended for use by the HPCToolkit team,
but could be helpful to others interested in HPCToolkit's implementation.
.

\item[\Opt{-d}, \Opt{--debug}]
After initialization, spin wait until you attach a debugger
to one or more of the application's processes.
After attaching you can set breakpoints or watchpoints in your application's code
or in HPCToolkit's \Prog{hpcrun} code before beginning application execution.
To continue after attaching, use the debugger to call \Prog{hpcrun_continue()}
and then resume execution.

\item[\OptArg{-dd}{flag}, \OptArg{--dynamic-debug}{flag}]
Enable the flag \Prog{flag},
causing \Prog{hpcrun} to log debug messages guarded with that flag
during execution.
A list of dynamic debug flags can be found in HPCToolkit's source code
in the file \Prog{src/tool/hpcrun/messages/messages.flag-defns}.
Note that not all flags are meaningful on all architectures.
The special value \Prog{ALL} enables all debug flags.
\\
Caution: turning on debug flags produces many log messages,
often dramatically slowing the application and potentially distorting the measured profile.

\item[\Opt{-md}, \Opt{--monitor-debug}]
Enable debug tracing of \Prog{libmonitor}, the \Prog{hpcrun} subsystem which implements process/thread control.

\end{Description}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\section{Environment Variables}
To function correctly, \Prog{hpcrun} must know the location of the \Prog{HPCToolkit}
top-level installation directory so that it can access toolkit components located
in its \File{lib} and \File{libexec} subdirectories.
Under most circumstances, \Prog{hpcrun} requires no special environment variable settings.

There are two situations, however, where \Prog{hpcrun}
\emph{must} consult the \verb+HPCTOOLKIT+ environment variable to determine the location
of the top-level installation directory:

\begin{itemize}
\item On some systems, parallel job launchers (e.g., Cray's aprun) \emph{copy} the
       \Prog{hpcrun} script to a different location. For \Prog{hpcrun} to know
       the location of its top-level installation directory,
       you must set the \verb+HPCTOOLKIT+ environment variable to the
       top-level installation directory.
\item
       If you launch \Prog{hpcrun} script via a file system link,
       you must set \verb+HPCTOOLKIT+ for the same reason.
\end{itemize}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\section{Launching}

When sampling with native events, by default hpcrun will profile using perf events.
To force HPCToolkit to use PAPI (assuming it's available) instead of perf events, one
must prefix the event with '\texttt{papi::}' as follows:

\begin{verbatim}
hpcrun -e papi::CYCLES
\end{verbatim}

For PAPI presets, there is no need to prefix the event with 'papi::'. For instance it is
sufficient to specify \texttt{PAPI\_TOT\_CYC} event without any prefix to profile using PAPI.

To sample an execution 100 times per second (frequency-based sampling) counting
CYCLES and 100 times a second counting INSTRUCTIONS:
\begin{verbatim}
hpcrun -e CYCLES@f100 -e INSTRUCTIONS@f100 ...
\end{verbatim}

To sample an execution every 1,000,000 cycles and every 1,000,000 instructions using
period-based sampling:
\begin{verbatim}
hpcrun -e CYCLES@1000000 -e INSTRUCTIONS@1000000 ...
\end{verbatim}
By default, hpcrun will use frequency-based sampling with the rate 300 samples per
second per event type. Hence the following command will cause HPCToolkit to sample
CYCLES at 300 samples per second and INSTRUCTIONS at 300 samples per second:
\begin{verbatim}
hpcrun -e CYCLES -e INSTRUCTIONS ...
\end{verbatim}
One can a different default rate using the -c option. The command below will sample
CYCLES at 200 samples per second and INSTRUCTIONS at 200 samples per second:
\begin{verbatim}
hpcrun -c f200 -e CYCLES -e INSTRUCTIONS ...
\end{verbatim}

\section{Examples}

Assume we wish to profile the application \texttt{zoo}.
The following examples lists some useful events for different processor architectures.

\begin{itemize}
\item \Prog{hpcrun -e CYCLES -e INSTRUCTIONS zoo}
\item \Prog{hpcrun -e REALTIME@5000 zoo}
\item \Prog{hpcrun -e DC_L2_REFILL@1300013 -e PAPI_L2_DCM@510011 -e PAPI_STL_ICY@5300013 -e PAPI_TOT_CYC@13000019 zoo}
\item \Prog{hpcrun -e PAPI_L2_DCM@510011 -e PAPI_TLB_DM@510013 -e PAPI_STL_ICY@5300013 -e PAPI_TOT_CYC@13000019 zoo}
\end{itemize}

\end{enumerate}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Notes}

\subsection{Sample sources}

%\newcommand{\	exttt{perf\_events}}{{\tt perf\_events}}

\Prog{hpcrun} uses Linux perf\_events (default on Linux platform) and optionally the PAPI library to provide access to hardware performance counter events.
It is important to note that on most out-of-order pipelined architectures, a hardware counter interrupt is not precisely attributed to the instruction that induced the counter to overflow.
The gap is commonly 50-70 instructions.
This means that one should not assume that aggregation at the source line level is fully precise.
(E.g., if a L1 D-cache miss is attributed to a statement that has been compiled to register-only operations, assume the miss is attributed to a nearby load.)
However, aggregation at the procedure and loop level is reliable.

\subsubsection{Linux perf\_events Interface}

Linux \texttt{perf\_events} provides a powerful interface that supports
measurement of both application execution and kernel activity.
Using
\texttt{perf\_events}, one can measure both hardware and software events.
Using a processor's hardware performance monitoring unit (PMU), the
\texttt{perf\_events} interface can measure an execution using any hardware counter
supported by the PMU. Examples of hardware events include cycles, instructions
completed, cache misses, and stall cycles. Using instrumentation built in to the Linux kernel,
the \texttt{perf\_events} interface can measure software events. Examples of software events include page
faults, context switches, and CPU migrations.

HPCToolkit uses libpfm4 to translate from an event name string to an event code recognized by the kernel.
An event name is case insensitive and is defined as followed:
\begin{verbatim}
[pmu::][event_name][:unit_mask][:modifier|:modifier=val]
\end{verbatim}

\begin{itemize}
	\item \textbf{pmu}.  Optional name of the PMU (group of events) to which the event belongs to. This is useful to disambiguate events in case events from difference sources have the same name. If no pmu is specified, the first match event is used.
	\item \textbf{event\_name}.  The name of the event. It must be the complete name, partial matches are not accepted.
	\item \textbf{unit\_mask}.  This designate an optional sub-events. Some events can be refined using sub-events. An event may have multiple unit masks and it is possible to combine them (for some events) by repeating \texttt{:unit\_mask} pattern.
	\item \textbf{modifier}.  A modifier is an optional filter which modifies how the event counts. Modifiers have a type and a value specified after the equal sign.
		For boolean type modifiers, without specifying the value, the presence of the modifier is interpreted as meaning true. Events may support multiple modifiers, by repeating the \texttt{:modifier|:modifier=val} pattern.
	\begin{itemize}
                \item \textbf{precise\_ip}. For some events, it is possible to control the amount of skid.
Skid is a measure of how many instructions may execute between an event and the PC where the event is reported.
Smaller skid enables more accurate attribution of events to instructions. Without a skid modifier, hpcrun allows arbitrary skid because some architectures
don't support anything more precise.  One may optionally specify one of the following as a skid modifier:
                        \begin{itemize}
                                \item \verb+:p+ : a sample must have constant skid.
                                \item \verb+:pp+ : a sample is requested to have 0 skid.
                                \item \verb+:ppp+ : a sample must have 0 skid.
                                \item \verb+:P+ : autodetect the least skid possible.
                        \end{itemize}
                        NOTE: If the kernel or the hardware does not support the specified value of the skid, no error message will be reported
but no samples will be delivered.
        \end{itemize}
\end{itemize}

Some capabilities of HPCToolkit's \texttt{perf\_events} Interface include:
\begin{itemize}
	\item \textbf{Frequency-based sampling.}
Rather than picking a sample period for a hardware counter,
the Linux \texttt{perf\_events} interface enables one to specify the desired sampling frequency
and have the kernel automatically select and adjust the period
to try to achieve the desired sampling frequency.
To use frequency-based sampling, one can specify the sampling rate
for an event as the desired number of samples per second
by prefixing the rate with the letter “\verb+f+”.

\item \textbf{Multiplexing.}
Using multiplexing enables one to monitor more events
in a single execution than the number of hardware counters a processor
can support for each thread. The number of events that can be monitored in
a single execution is only limited by the maximum number of concurrent
events that the kernel will allow a user to multiplex using the
\texttt{perf\_events} interface.

When more events are specified than can be monitored simultaneously
using a thread's hardware counters,
  the kernel will employ multiplexing and divide
the set of events to be monitored into groups, monitor only one group
of events at a time, and cycle repeatedly through the groups
as a program executes.

\item \textbf{Thread blocking.} When a program executes,
a thread may block waiting for the kernel to complete some operation on its behalf.
Example operations include waiting for a \texttt{read} operation to complete or having the
kernel service a page fault or zero-fill a page. On systems running Linux 4.3 or newer, one can use the \texttt{perf\_events} sample source to monitor how much time a thread is blocked and where the blocking occurs. To measure
the time a thread spends blocked, one can profile with \verb+BLOCKTIME+ event and
another time-based event, such as \verb+CYCLES+. The \verb+BLOCKTIME+ event shouldn't have any frequency or period specified, whereas \verb+CYCLES+ should have a frequency or period specified.

\end{itemize}

\subsubsection{PAPI Interface (optional)}
The PAPI library supports a large collection of hardware counter events.
Some events have standard names across all platforms, e.g. \verb+PAPI_TOT_CYC+, the event that measures total cycles.
In addition to events whose names begin with the \verb+PAPI_+ prefix, platforms also provide access to a set of native events with names that are specific to the platform's processor.
A complete list of events supported by the PAPI library for your platform may be obtained by using the \texttt{--list-events} option.
Any event whose name begins with the \verb+PAPI_+ prefix that is listed as "Profilable" can be used as an event in a sampling source provided it does not conflict with another event.

The rules of thumb for selecting an appropriate set of events and their associated periods are complex.
\begin{itemize}

\item \textbf{Choosing sampling events.}
Some PAPI events are not profilable because of PAPI implementation details.
Also, PAPI's standard event list may not cover an architectural feature you are interested in.
In such cases, it is necessary to resort to native events.
In many cases, you will have to consult the architecture's manual to fully understand what the event means: there is no standard event list or naming scheme and events sometimes have unusual meanings.

\item \textbf{Number of sampling events.}
\Prog{hpcrun} does not multiplex hardware counters for events measured using PAPI. (Events measured using the Linux
perf interface will be multiplexed automatically.)
Without multiplexing, the number of events that you may use to profile a single execution
is limited by your architecture's performance monitoring unit.
Note that some architectures hard-wire one or more counters to a specific event (such as cycles).

\item \textbf{Choosing sampling periods.}
The key requirement in choosing sampling periods is that you obtain enough samples to provide statistical significance.
We usually recommend a sampling rate between 100s-1000s of samples per second.
This usually only produces 1-5\% execution time overhead.

Choosing sampling rates depends on the architecture and sometimes the application.

Choosing periods for cycle and instruction-related events are usually easy.
Cycles directly relates to the clock speed.
Instruction-related events relates to the issue rate and width.

Choosing periods for other events seems harder because different applications uses resources differently.
For example, some applications are memory intensive and others are not.
However, if the goal is to identify rate-limiting factors of the architecture, then it is not necessary to consider the application.
For example, if the goal is to determine whether L2 D-cache latency is a limiting factor, then it is only necessary to work backward from the architecture's specifications to determine what number of L2 D-cache misses per second would be problematic.

\item \textbf{Architectural event conflicts.}
With some performance monitoring units, certain events may not be concurrently used with other events.
\end{itemize}

\subsubsection{System itimer (WALLCLOCK).}
On Linux systems, the kernel will not deliver itimer interrupts faster than the unit of a jiffy, which defaults to 4 milliseconds; see the itimer man page.
One can configure the kernel to use a value as small as 1 millisecond, but it is unlikely the kernel will actually deliver itimer signals at that rate when a period of 1000 microseconds is requested.

However, on Linux one can get quite close to the kernel Hz rate by setting the itimer interval to something less than the Hz rate.
For example, if the Hz rate is 1000 microseconds, one can use 500 microseconds (or just 1) and obtain about 999 interrupts per second.

\subsection{Platform-specific notes}
\subsubsection{Cray Systems}
When using dynamically linked binaries on Cray systems, you
should add the \verb+HPCTOOLKIT+ environment variable to your launch
script.  Set \verb+HPCTOOLKIT+ to the top-level \verb+HPCToolkit+ install
prefix (the directory containing the \File{bin}, \File{lib} and
\File{libexec} subdirectories) and export it to the environment.  This is
only needed for running dynamically linked binaries.  For example:

\begin{verbatim}
#!/bin/sh
#PBS -l mppwidth=#nodes
#PBS -l walltime=00:30:00
#PBS -V

export HPCTOOLKIT=/path/to/hpctoolkit/install/directory

    ...Rest of Script...
\end{verbatim}

If \verb+HPCTOOLKIT+ is not set, you may see errors such as the
following in your job's error log.

\begin{verbatim}
/var/spool/alps/103526/hpcrun: Unable to find HPCTOOLKIT root directory.
Please set HPCTOOLKIT to the install prefix, either in this script,
or in your environment, and try again.
\end{verbatim}

The problem is that the Cray ALPS job launcher copies the \Prog{hpcrun}
script to a directory somewhere below \File{/var/spool/alps/} and runs
it from there.  By moving \Prog{hpcrun} to a different directory, this
breaks \Prog{hpcrun}'s default method for finding HPCToolkit's top-level
installation directory.
The solution is to add \verb+HPCTOOLKIT+ to your environment so that
\Prog{hpcrun} can find HPCToolkit's top-level installation directory.

\subsection{Miscellaneous}

\begin{itemize}
  \item \Prog{hpcrun} uses preloaded shared libraries to initiate profiling.  For this reason, it cannot be used to profile setuid programs.
  \item \Prog{hpcrun} may not be able to profile programs that themselves use preloading.
\end{itemize}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{See Also}

\HTMLhref{hpctoolkit.html}{\Cmd{hpctoolkit}{1}}.\\
\HTMLhref{hpclink.html}{\Cmd{hpclink}{1}}.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Version}

Version: \Version

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{License and Copyright}

\begin{description}
\item[Copyright] \copyright\ 2002-2020, Rice University.
\item[License] See \File{README.License}.
\end{description}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Authors}

\noindent
Rice University's HPCToolkit Research Group \\
Email: \Email{hpctoolkit-forum =at= rice.edu} \\
WWW: \URL{http://hpctoolkit.org}.

\LatexManEnd

\end{document}

%% Local Variables:
%% eval: (add-hook 'write-file-hooks 'time-stamp)
%% time-stamp-start: "setDate{ "
%% time-stamp-format: "%:y/%02m/%02d"
%% time-stamp-end: "}\n"
%% time-stamp-line-limit: 50
%% End:

max_stars_repo_name: zygyz/hpctoolkit

max_issues_repo_name: zygyz/hpctoolkit


text:
\chapter{Ruby API}
\label{chap:api:ruby}

\section{Client Library}
\label{sec:api:ruby:client}

HyperDex provides ruby bindings under the module \code{HyperDex::Client}.  This
library wraps the HyperDex C Client library and enables use of native Ruby data
types.

This library was brought up-to-date following the 1.0.rc5 release.

\subsection{Building the HyperDex Ruby Binding}
\label{sec:api:ruby:building}

The HyperDex Ruby Binding must be requested at configure time as it is not
automatically built.  You can ensure that the Ruby bindings are always built by
providing the \code{--enable-ruby-bindings} option to \code{./configure} like
so:

\begin{consolecode}
% ./configure --enable-client --enable-ruby-bindings
\end{consolecode}

\subsection{Using Ruby Within Your Application}
\label{sec:api:ruby:using}

All client operation are defined in the \code{HyperDex::Ruby} module.  You can
access this in your program with:

\begin{rubycode}
require 'hyperdex'
\end{rubycode}

\subsection{Hello World}
\label{sec:api:ruby:hello-world}

The following is a minimal application that stores the value "Hello World" and
then immediately retrieves the value:

\inputminted{ruby}{\topdir/ruby/client/hello-world.rb}

You can run this example with:

\begin{consolecode}
% ruby hello-world.rb
put "Hello World!"
got:
{:v=>"Hello World!"}
\end{consolecode}

Right away, there are several points worth noting in this example:

\begin{itemize}
\item Every operation is synchronous.  The PUT and GET operations run to
completion by default.

\item Ruby types are automatically converted to HyperDex types.  There's no need
to specify information such as the length of each string, as one would do with
the C API.

\item Ruby symbols are permitted wherever a string may be used.  By convention,
space names and attribute names are specified using Ruby symbols, e.g.
\code{:kv} and \code{:v}.  Of course, you may use strings for these parameters
too.
\end{itemize}

\subsection{Asynchronous Operations}
\label{sec:api:ruby:async-ops}

For convenience, the Ruby bindings treat every operation as synchronous.  This
enables you to write short scripts without concern for asynchronous operations.
Most operations come with an asynchronous form, denoted by the \code{async\_}
prefix.  For example, the above Hello World example could be rewritten in
asynchronous fashion as such:

\inputminted{ruby}{\topdir/ruby/client/hello-world-async-wait.rb}

This enables applications to issue multiple requests simultaneously and wait for
their completion in an application-specific order.  It's also possible to use
the \code{loop} method on the client object to wait for the next request to
complete:

\inputminted{ruby}{\topdir/ruby/client/hello-world-async-loop.rb}

\subsection{Data Structures}
\label{sec:api:ruby:data-structures}

The Ruby bindings automatically manage conversion of data types from Ruby to
HyperDex types, enabling applications to be written in idiomatic Ruby.

\subsubsection{Examples}
\label{sec:api:ruby:examples}

This section shows examples of Ruby data structures that are recognized by
HyperDex.  The examples here are for illustration purposes and are not
exhaustive.

\paragraph{Strings}

The HyperDex client recognizes Ruby's strings and symbols and automatically
converts them to HyperDex strings.  For example, the following two calls are
equivalent and have the same effect:

\begin{rubycode}
c.put("kv", "somekey", {"v" => "somevalue"})
c.put(:kv, :somekey, {:v => :somevalue})
\end{rubycode}

The recommended convention is to use symbols for space and attribute names, and
strings for keys and values like so:

\begin{rubycode}
c.put(:kv, "somekey", {:v => "somevalue"})
\end{rubycode}

\paragraph{Integers}

The HyperDex client recognizes Ruby's integers, longs, and fixnums and
automatically converts them to HyperDex integers.  For example:

\begin{rubycode}
c.put(:kv, "somekey", {:v => 42})
\end{rubycode}

\paragraph{Floats}

The HyperDex client recognizes Ruby's floating point numbers and automatically
converts them to HyperDex floats.  For example:

\begin{rubycode}
c.put(:kv, "somekey", {:v => 3.1415})
\end{rubycode}

\paragraph{Lists}

The HyperDex client recognizes Ruby lists and automatically converts them to
HyperDex lists.  For example:

\begin{rubycode}
c.put(:kv, "somekey", {:v1 => ["a", "b", "c"]})
c.put(:kv, "somekey", {:v2 => [1, 2, 3]})
c.put(:kv, "somekey", {:v3 => [1.0, 0.5, 0.25]})
\end{rubycode}

\paragraph{Sets}

The HyperDex client recognizes Ruby sets and automaticaly converts them to
HyperDex sets.  For example:

\begin{rubycode}
require 'set'
c.put(:kv, "somekey", {:v1 => (Set.new ["a", "b", "c"])})
c.put(:kv, "somekey", {:v2 => (Set.new [1, 2, 3])})
c.put(:kv, "somekey", {:v3 => (Set.new [1.0, 0.5, 0.25])})
\end{rubycode}

Note that you'll have to include the set module from the standard library.

\paragraph{Maps}

The HyperDex client recognizes Ruby hashes and automatically converts them to
HyperDex maps.  For example:

\begin{rubycode}
c.put(:kv, "somekey", {:v1 => {"k" => "v"}})
c.put(:kv, "somekey", {:v2 => {1 => 2}})
c.put(:kv, "somekey", {:v3 => {3.14 => 0.125}})
c.put(:kv, "somekey", {:v3 => {"a" => 1}})
\end{rubycode}

\subsection{Attributes}
\label{sec:api:ruby:attributes}

Attributes in Ruby are specified in the form of a hash from attribute names to
their values.  As you can see in the examples above, attributes are specified in
the form:

\begin{rubycode}
{:name => "value"}
\end{rubycode}

\subsection{Map Attributes}
\label{sec:api:ruby:map-attributes}

Map attributes in Ruby are specified in the form of a nested hash.  The outer
hash key specifies the name, while the inner hash key-value pair specifies the
key-value pair of the map.  For example:

\begin{rubycode}
{:name => {"key" => "value"}}
\end{rubycode}

\subsection{Predicates}
\label{sec:api:ruby:predicates}

Predicates in Ruby are specified in the form of a hash from attribute names to
their predicates.  In the simple case, the predicate is just a value to be
compared against:

\begin{rubycode}
{:v => "value"}
\end{rubycode}

This is the same as saying:

\begin{rubycode}
{:v => HyperDex::Client::Equals.new('value')}
\end{rubycode}

The Ruby bindings support the full range of predicates supported by HyperDex
itself.  For example:

\begin{rubycode}
{:v => HyperDex::Client::LessEqual.new(5)}
{:v => HyperDex::Client::GreaterEqual.new(5)}
{:v => HyperDex::Client::Range.new(5, 10)}
{:v => HyperDex::Client::Regex.new('^s.*')}
{:v => HyperDex::Client::LengthEquals.new(5)}
{:v => HyperDex::Client::LengthLessEqual.new(5)}
{:v => HyperDex::Client::LengthGreaterEqual.new(5)}
{:v => HyperDex::Client::Contains.new('value')}
\end{rubycode}

\subsection{Error Handling}
\label{sec:api:ruby:error-handling}

All error handling within the Ruby bindings is done via the
\code{begin}/\code{rescue} mechanism of Ruby.  Errors will be raised by the
library and should be handled by your application.  For example, if we were
trying to store an integer (5) as attribute \code{:v}, where \code{:v} is
actually a string, we'd generate an error.

\begin{rubycode}
begin
    puts c.put(:kv, :my_key, {:v => 5})
rescue HyperDex::Client::HyperDexClientException => e
    puts e.status
    puts e.symbol
    puts e
end
\end{rubycode}

Errors of type \code{HyperDexClientException} will contain both a message
indicating what went wrong, as well as the underlying \code{enum
hyperdex\_client\_returncode}.  The member \code{status} indicates the numeric
value of this enum, while \code{symbol} returns the enum as a string.  The above
code will fail with the following output:

\begin{verbatim}
8525
HYPERDEX_CLIENT_WRONGTYPE
invalid attribute "v": attribute has the wrong type
\end{verbatim}

\subsection{Operations}
\label{sec:api:ruby:ops}

\input{\topdir/ruby/client/ops}
\pagebreak

\subsection{Working with Signals}
\label{sec:api:ruby:signals}

The HyperDex client library is signal-safe.  Should a signal interrupt the
client during a blocking operation, it will raise a
\code{HyperDexClientException} with status \code{HYPERDEX\_CLIENT\_INTERRUPTED}.

\subsection{Working with Threads}
\label{sec:api:ruby:threads}

The Ruby module is fully reentrant.  Instances of
\code{HyperDex::Client::Client} and their associated state may be accessed from
multiple threads, provided that the application employs its own synchronization
that provides mutual exclusion.

Put simply, a multi-threaded application should protect each \code{Client}
instance with a mutex or lock to ensure correct operation.

max_stars_repo_name: derekchiang/HyperDex

max_issues_repo_name: derekchiang/HyperDex

max_forks_repo_name: derekchiang/HyperDex


text:
\subsection{Dynamic or lagged independent variables}

Static panel data: No lags of independent variables.
Dynamic panel data: Lags of independent variables.

OLS is consistent for static panel data, not for dynamic
This results in Nickell's bias for dynamic panel data

Dynamic panel data: \(y_{t-1}\) is a regressor
Panel data estimation: LSDV. Least squares dummy variable estimator
arnello bond

max_stars_repo_name: adamdboult/nodeHomePage

max_issues_repo_name: adamdboult/nodeHomePage

max_forks_repo_name: adamdboult/nodeHomePage


text:
\begin{appendix}
  \chapter{Problem Statement}
  \label{app:problem_statement}
  \includepdf[pages=-]{appendix/problem_statement.pdf}

  \chapter{Inference Application}
  \label{app:inference_application}
  \lstinputlisting[style=python]{appendix/aionfpga.py}
\end{appendix}

max_stars_repo_name: MuellerDominik/AIonFPGA

max_issues_repo_name: MuellerDominik/AIonFPGA

max_forks_repo_name: MuellerDominik/AIonFPGA


text:
\subsection{Multi-scale convolutions}

We use different window sizes in parallel.


text:
\appendix
\chapter{Appendices} \label{chap:appendices}

\section{Mechanical class diagrams} \label{sec:umlmeca}
Figure \ref{fig:umlMechClasses} shows the mechanical classes of \sofa. Not all members and methods are shown. For a full list, please refer to the source code documentation.

\begin{figure}[htp]
	\hspace{-2cm}
	\includegraphics*[width=20cm]{fig/uml-mechanical-classes.eps}
\label{fig:umlMechClasses}
\caption{Class diagram of the mechanics.}
\end{figure}

	%\setlength{\textwidth }{16cm}	% largeur de ligne

max_stars_repo_name: sofa-framework/issofa

max_issues_repo_name: sofa-framework/issofa

max_forks_repo_name: sofa-framework/issofa


text:
\chapter{Simple Distribution Walkthrough}
\label{app:walkthrough}
Seen below is a simple tutorial for starting with SINATRA. It can be found in the documentation/SimpleDistribution directory as ReadMe.md within each specific OS's directory.

\begin{verbatim}
SINATRA Simple Distribution Manual
Dominic Lunde

Hello! Welcome to a tutorial on how to use SINATRA.

First, requirements
1) Windows OS
2) Matlab or Matlab runtime - for output only

This will walk you through a simple simulation case.
Then it will show you how to use the GUI and then you can have fun!

Step 1 - Mesh

We must create a mesh file. This is done through
 the Mesh.exe executable.
The MeshInput.txt file is already set up to create
 8 cells through 1 cut.

Therefore we can run the mesher by either:
a) Dragging MeshInput.txt onto Mesh.exe
b) Running "Mesh MeshInput.txt" into a
 command window set to this directory

After this is done, you should see your
 mesh file as a .plt file appear. Good!

Step 2 - Simulate

Now we can simulate some particles.
Complex_Input.txt is set up to use
 8 cells and run 10 timesteps

Therefore we can run the mesher by either:
a) Dragging Complex_Input.txt onto DSMC.exe
b) Running "DSMC Complex_Input.txt"
 into a command window

All done! You will see a file called SINATRA_OUTPUT.txt.
This shows you very simple time step info.
You will also see SINATRA_uniform_properties_000001.plt.
This has Tecplot data from the first time step.

Step 3 - Analysis

We want to see those particles move right?
We need to change some things first.
Open Complex_Input.txt and go
 to the "Output Information" Section
Between the Tecplot Sample Frequency and the *** add this.

Particle Animation
0
1
VelocityOutput\velocityFromParticles_

The first line is the trigger word, next is the start time,
 then the frequency of output, and finally the base filename.
--Create the folder VelocityOutput
 so these files have a place to go.
Now run the simulation again.

Now if you open VelocityOutput you will see 11 files!
We can use those to view the particles and their movements.
--Open FlowVelocityDistributionAnim.m in Matlab and run

A file called SINATRA_gif.gif will be
 created and you can see your particles!
However, it's a mess and they don't seem to move. Let's change that.
In Complex_Input
--Change the Time Step to 1e-5
--Change the Total Simulation Time to 10e-5.
This will allow the particles to move further each frame.
Now let's make less particles.
--Set the Number Density to 1e-22.
Now rerun the simlulation and analysis
 and boom! Particles in a box.

Step 4 - GUI

Now I'm going to let you play with the GUI. Open up SINATRA_GUI.exe.
We're going to have to change a few things.
SINATRA Output file - SINATRA_OUTPUT.txt
Tecplot Output      - SINATRA_uniform_properties.plt
Velocity Output     - VelocityOutput/velocityFromParticles_
Mesh File           - FE_NodeLocations_UnitCubeQuad8Cells_TEC.plt
Input File          - Complex_Input.txt

This GUI prints input files.
Try it by pressing "Write File" then "Open File".
Then change something and see how it changes the input file.
Finally, you can press "Simulate" to run that input file on DSMC.exe.

Have fun!

\end{verbatim}

max_stars_repo_name: dclunde/thesis-template

max_issues_repo_name: dclunde/thesis-template

max_forks_repo_name: dclunde/thesis-template


text:
%\begingroup
%\let\cleardoublepage\clearpage

% English abstract
\cleardoublepage
\chapter*{Abstract}
\markboth{Abstract}{Abstract}
% \addcontentsline{toc}{chapter}{Abstract} % adds an entry to the table of contents
% put your text here
% \lipsum[1-2]
\vspace{0.05\textheight}

Understanding the relationships among objects is in some sense half of science; the other
half being the definition and discovery of these objects. Causality tries to understand the question of
relation; if we are given random variables $X$ and $Y$, under what conditions can we infer that
one causes the other, and if so, how? \\

If we are able to intervene on a system, then the problem is more straightforward; if we can force\footnote{
As a silly example imagine that we want to see if a broken switch causes a light to turn on, then clearly,
whether or not we press the switch, the light will not turn on (i.e. it's distribution does not change).}
$X$ to take two different values, but observe no change in the distribution of $Y$, then we can readily
conclude that $X$ does not cause $Y$.
The second and more challenging scenario is the observational setting: given
only \textit{observations} of $X$ and $Y$, can we conclude that one caused the other? \\

We will tackle the bivariate setting, which has
seen various methods proposed over the years. We will review the most common family of such methods:
the additive noise models (ANM) by \cite{Mooij2016jmlr}, as well as some more recent ones such as
the causal generative neural network (CGNN) \cite{goudet2017causal}. \\

We propose a new type of inference method which exploits the i.i.d
noise assumption; the idea is to split the data in different intervals, and then to regress each
interval separately. In the causal direction, one would expect that the residuals of each
interval will be more homogenous\footnote{By homogenous residuals we mean that the residuals will
be similar to each other, for example if we plot their respective histograms, these will asymptotically
converge to the same distribution.} --- in the ANM settings, asymmetries introduced
by inversion will break the i.i.d assumption. We conclude by
showing that this intuition is indeed correct, by proving that the method is consistent ---
assuming that causal discovery is indeed possible and that the additive noise is i.i.d. We
also propose a second method, which while also consistent, requires knowledge of the
noise distribution, which is a not a good assumption in practice. We will show that our former method is competitive with
other methods on popular benchmarks such as the Tübingen cause and effect dataset.

% For other languages:

% % German abstract
% \begin{otherlanguage}{german}
% \cleardoublepage
% \chapter*{Zusammenfassung}
% \markboth{Zusammenfassung}{Zusammenfassung}
% % put your text here
% \lipsum[1-2]
% \end{otherlanguage}

% % French abstract
% \begin{otherlanguage}{french}
% \cleardoublepage
% \chapter*{Résumé}
% \markboth{Résumé}{Résumé}
% % put your text here
% \lipsum[1-2]
% \end{otherlanguage}

%\endgroup
%\vfill