core

Documentation

Index

• type Application
  • func (a *Application) CompetitionType() Competition
  • func (a *Application) Heading() *Heading
  • func (a *Application) Priority() int
  • func (a *Application) RatingPlace() int
  • func (a *Application) Score() int
  • func (a *Application) StudentID() string
• type ApplicationDTO
• type CalculationResult
  • func (r *CalculationResult) CheckRegularsAdmitted() bool
  • func (r *CalculationResult) LastAdmittedRatingPlace() (int, error)
  • func (r *CalculationResult) PassingScore() (int, error)
• type CalculationResultDTO
• type Capacities
  • func (c Capacities) PrintRvalue() string
  • func (c Capacities) String() string
• type Competition
  • func (c Competition) String() string
• type DrainedResultDTO
• type GeneralApplicationHeap
  • func (h *GeneralApplicationHeap) Len() int
  • func (h *GeneralApplicationHeap) Less(i, j int) bool
  • func (h *GeneralApplicationHeap) Peek() *Application
  • func (h *GeneralApplicationHeap) Pop() interface{}
  • func (h *GeneralApplicationHeap) Push(x interface{})
  • func (h *GeneralApplicationHeap) Swap(i, j int)
• type Heading
  • func (h *Heading) Capacities() Capacities
  • func (h *Heading) Code() string
  • func (h *Heading) FullCode() string
  • func (h *Heading) GobDecode(data []byte) error
  • func (h *Heading) GobEncode() ([]byte, error)
  • func (h *Heading) PrettyName() string
  • func (h *Heading) TotalCapacity() int
  • func (h *Heading) VarsityCode() string
  • func (h *Heading) VarsityPrettyName() string
• type HeadingAdmissionStateGS
  • func NewHeadingAdmissionStateGS(h *Heading) *HeadingAdmissionStateGS
• type HeadingDTO
• type QuotaApplicationHeap
  • func (h *QuotaApplicationHeap) Len() int
  • func (h *QuotaApplicationHeap) Less(i, j int) bool
  • func (h *QuotaApplicationHeap) Peek() *Application
  • func (h *QuotaApplicationHeap) Pop() interface{}
  • func (h *QuotaApplicationHeap) Push(x interface{})
  • func (h *QuotaApplicationHeap) Swap(i, j int)
• type Student
  • func (s *Student) Application(heading *Heading) *Application
  • func (s *Student) Applications() []*Application
  • func (s *Student) ID() string
  • func (s *Student) OriginalSubmitted() bool
  • func (s *Student) Quit() bool
• type StudentDTO
• type UploadPayload
  • func NewUploadPayloadFromCalculator(vc *VarsityCalculator, results []CalculationResult, ...) *UploadPayload
• type VarsityCalculator
  • func NewVarsityCalculator(code, prettyName string) *VarsityCalculator
  • func (v *VarsityCalculator) AddApplication(headingCode, studentID string, ratingPlace, priority int, ...)
  • func (v *VarsityCalculator) AddHeading(code string, capacities Capacities, prettyName string)
  • func (v *VarsityCalculator) CalculateAdmissions() []CalculationResult
  • func (v *VarsityCalculator) DrainedPercent() int
  • func (v *VarsityCalculator) ForEachOriginalSubmitted(f func(studentID string))
  • func (v *VarsityCalculator) ForEachQuit(f func(studentID string))
  • func (v *VarsityCalculator) GetHeading(code string) *Heading
  • func (v *VarsityCalculator) GetStudent(studentID string) *Student
  • func (v *VarsityCalculator) Headings() []*Heading
  • func (v *VarsityCalculator) NormalizeApplications()
  • func (v *VarsityCalculator) SetOriginalSubmitted(studentID string)
  • func (v *VarsityCalculator) SetQuit(studentID string)
  • func (v *VarsityCalculator) SimulateOriginalsDrain(drainPercent int)
  • func (v *VarsityCalculator) Students() []*Student

Types

type Application

type Application struct {
	// contains filtered or unexported fields
}

Application represents a student's application to a specific heading.

func (*Application) CompetitionType

func (a *Application) CompetitionType() Competition

func (*Application) Heading

func (a *Application) Heading() *Heading

func (*Application) Priority

func (a *Application) Priority() int

func (*Application) RatingPlace

func (a *Application) RatingPlace() int

func (*Application) Score

func (a *Application) Score() int

func (*Application) StudentID

func (a *Application) StudentID() string

type ApplicationDTO

type ApplicationDTO struct {
	StudentID       string      `json:"student_id"`
	HeadingCode     string      `json:"heading_code"`
	Priority        int         `json:"priority"`
	CompetitionType Competition `json:"competition_type"`
	RatingPlace     int         `json:"rating_place"`
	Score           int         `json:"score"`
	MSUInternalID   *string     `json:"msu_internal_id,omitempty"`
}

ApplicationDTO is a lean version of core.Application.

type CalculationResult

type CalculationResult struct {
	// The heading for which this calculation result is generated.
	Heading *Heading
	// List of students admitted to the heading, sorted according to admission criteria (e.g., quota, BVI, Regular, then rating).
	Admitted []*Student
}

CalculationResult holds the outcome of the admission process for a single heading.

func (*CalculationResult) CheckRegularsAdmitted

func (r *CalculationResult) CheckRegularsAdmitted() bool

func (*CalculationResult) LastAdmittedRatingPlace

func (r *CalculationResult) LastAdmittedRatingPlace() (int, error)

func (*CalculationResult) PassingScore

func (r *CalculationResult) PassingScore() (int, error)

type CalculationResultDTO

type CalculationResultDTO struct {
	HeadingCode             string       `json:"heading_code"`
	Admitted                []StudentDTO `json:"admitted"`
	RegularsAdmitted        bool         `json:"regulars_admitted"`
	PassingScore            int          `json:"passing_score"`
	LastAdmittedRatingPlace int          `json:"last_admitted_rating_place"`
}

CalculationResultDTO is a lean version of core.CalculationResult.

type Capacities

type Capacities struct {
	Regular        int // Guaranteed number of places for Regular & BVI competitors
	TargetQuota    int
	DedicatedQuota int
	SpecialQuota   int
}

Capacities hold the quotas and capacities of a heading for different competition types. If any quota is not used fully, the remaining places are available for Regular and BVI competitors. Max num of students who can be admitted to a heading is the sum of all quotas and the Regular capacity. Max num of students who can be admitted using each quota is limited by the corresponding field in Capacities. If a student fails to be admitted to a heading using their quota, they fail at all; quotas don't fall back to each other nor to the Regular capacity.

func (Capacities) PrintRvalue

func (c Capacities) PrintRvalue() string

PrintRvalue returns a string representation of the Capacities struct as a Go literal.

func (Capacities) String

func (c Capacities) String() string

type Competition

type Competition int

const (
	CompetitionRegular Competition = iota
	CompetitionBVI
	CompetitionTargetQuota
	CompetitionDedicatedQuota
	CompetitionSpecialQuota
)

Competition represents the type of competition for a student's application.

func (Competition) String

func (c Competition) String() string

type DrainedResultDTO

type DrainedResultDTO struct {
	HeadingCode                string `json:"heading_code"`
	DrainedPercent             int    `json:"drained_percent"`
	AvgPassingScore            int    `json:"avg_passing_score"`
	MinPassingScore            int    `json:"min_passing_score"`
	MaxPassingScore            int    `json:"max_passing_score"`
	MedPassingScore            int    `json:"med_passing_score"`
	AvgLastAdmittedRatingPlace int    `json:"avg_last_admitted_rating_place"`
	MinLastAdmittedRatingPlace int    `json:"min_last_admitted_rating_place"`
	MaxLastAdmittedRatingPlace int    `json:"max_last_admitted_rating_place"`
	MedLastAdmittedRatingPlace int    `json:"med_last_admitted_rating_place"`
	RegularsAdmitted           bool   `json:"regulars_admitted"`
	IsVirtual                  bool   `json:"is_virtual"`
}

DrainedResultDTO is a lean version of drainer.DrainedResult. It's a flattened version, as the original's fields are already primitive.

type GeneralApplicationHeap

type GeneralApplicationHeap struct {
	// contains filtered or unexported fields
}

GeneralApplicationHeap stores applications for general competition (Regular/BVI) for a heading. It's a min-heap where the root is the *least preferred* accepted student according to outscores.

func (*GeneralApplicationHeap) Len

func (h *GeneralApplicationHeap) Len() int

func (*GeneralApplicationHeap) Less

func (h *GeneralApplicationHeap) Less(i, j int) bool

func (*GeneralApplicationHeap) Peek

func (h *GeneralApplicationHeap) Peek() *Application

func (*GeneralApplicationHeap) Pop

func (h *GeneralApplicationHeap) Pop() interface{}

func (*GeneralApplicationHeap) Push

func (h *GeneralApplicationHeap) Push(x interface{})

func (*GeneralApplicationHeap) Swap

func (h *GeneralApplicationHeap) Swap(i, j int)

type Heading

type Heading struct {
	// Unique identifier for the heading. Exported so that encoding/gob can access it.
	CodeValue string

	// Maximum number of students that can be admitted to this heading using various quotas and general competition.
	CapacitiesValue Capacities
	// A human-readable code or identifier for the heading.
	PrettyNameValue string
	// contains filtered or unexported fields
}

Heading represents a program or specialization within a varsity.

func (*Heading) Capacities

func (h *Heading) Capacities() Capacities

Capacities returns the capacities of the heading, including quotas of different types.

func (*Heading) Code

func (h *Heading) Code() string

Code returns the unique identifier of the heading.

func (*Heading) FullCode

func (h *Heading) FullCode() string

func (*Heading) GobDecode

func (h *Heading) GobDecode(data []byte) error

func (*Heading) GobEncode

func (h *Heading) GobEncode() ([]byte, error)

func (*Heading) PrettyName

func (h *Heading) PrettyName() string

PrettyName returns the human-readable name of the heading.

func (*Heading) TotalCapacity

func (h *Heading) TotalCapacity() int

func (*Heading) VarsityCode

func (h *Heading) VarsityCode() string

func (*Heading) VarsityPrettyName

func (h *Heading) VarsityPrettyName() string

type HeadingAdmissionStateGS

type HeadingAdmissionStateGS struct {
	// contains filtered or unexported fields
}

HeadingAdmissionStateGS tracks the admission status for a single heading using heaps for Gale-Shapley.

func NewHeadingAdmissionStateGS

func NewHeadingAdmissionStateGS(h *Heading) *HeadingAdmissionStateGS

NewHeadingAdmissionStateGS creates a new state for a heading for Gale-Shapley.

type HeadingDTO

type HeadingDTO struct {
	Code                   string `json:"code"`
	Name                   string `json:"name"`
	RegularCapacity        int    `json:"regular_capacity"`
	TargetQuotaCapacity    int    `json:"target_quota_capacity"`
	DedicatedQuotaCapacity int    `json:"dedicated_quota_capacity"`
	SpecialQuotaCapacity   int    `json:"special_quota_capacity"`
}

HeadingDTO carries all essential information about a heading.

type QuotaApplicationHeap

type QuotaApplicationHeap struct {
	// contains filtered or unexported fields
}

QuotaApplicationHeap stores applications for a specific quota type for a heading. It's a min-heap where the root is the *least preferred* (highest ratingPlace) accepted student.

func (*QuotaApplicationHeap) Len

func (h *QuotaApplicationHeap) Len() int

func (*QuotaApplicationHeap) Less

func (h *QuotaApplicationHeap) Less(i, j int) bool

func (*QuotaApplicationHeap) Peek

func (h *QuotaApplicationHeap) Peek() *Application

Peek is helper method for heaps (assuming heap is not empty)

func (*QuotaApplicationHeap) Pop

func (h *QuotaApplicationHeap) Pop() interface{}

func (*QuotaApplicationHeap) Push

func (h *QuotaApplicationHeap) Push(x interface{})

func (*QuotaApplicationHeap) Swap

func (h *QuotaApplicationHeap) Swap(i, j int)

type Student

type Student struct {

	// Unique identifier of the student. Exported to allow gob encoding.
	IDValue string
	// contains filtered or unexported fields
}

Student represents a student in the system.

func (*Student) Application

func (s *Student) Application(heading *Heading) *Application

application retrieves the student's highest priority application details for a specific heading. It panics if no application is found for the given heading for this student. WARNING: This might not be suitable for all contexts if a student has multiple applications to the same heading with different competition types/priorities and the specific one is needed.

func (*Student) Applications

func (s *Student) Applications() []*Application

func (*Student) ID

func (s *Student) ID() string

func (*Student) OriginalSubmitted

func (s *Student) OriginalSubmitted() bool

func (*Student) Quit

func (s *Student) Quit() bool

type StudentDTO

type StudentDTO struct {
	ID                string `json:"id"`
	OriginalSubmitted bool   `json:"original_submitted"`
}

StudentDTO contains only essential data for an uploader.

type UploadPayload

type UploadPayload struct {
	VarsityCode  string                     `json:"varsity_code"`
	VarsityName  string                     `json:"varsity_name"`
	Headings     []HeadingDTO               `json:"headings"`
	Students     []StudentDTO               `json:"students"`
	Applications []ApplicationDTO           `json:"applications"`
	Calculations []CalculationResultDTO     `json:"calculations"`
	Drained      map[int][]DrainedResultDTO `json:"drained"` // key = drainedPercent
}

UploadPayload is the contract between producer → aggregator.

func NewUploadPayloadFromCalculator

func NewUploadPayloadFromCalculator(vc *VarsityCalculator, results []CalculationResult, drainedDTOs map[int][]DrainedResultDTO, msuInternalIDs map[string]string) *UploadPayload

NewUploadPayloadFromCalculator creates an UploadPayload from a VarsityCalculator and its results Note: drainedResults parameter should be map[int][]drainer.DrainedResult but we avoid the import cycle msuInternalIDs parameter is optional map of studentID -> msuInternalID for MSU-specific data

type VarsityCalculator

type VarsityCalculator struct {
	// contains filtered or unexported fields
}

func NewVarsityCalculator

func NewVarsityCalculator(code, prettyName string) *VarsityCalculator

NewVarsityCalculator creates a new varsity calculator.

func (*VarsityCalculator) AddApplication

func (v *VarsityCalculator) AddApplication(headingCode, studentID string, ratingPlace, priority int, competitionType Competition, scoresSum int)

AddApplication adds a student's application to a specific heading.

func (*VarsityCalculator) AddHeading

func (v *VarsityCalculator) AddHeading(code string, capacities Capacities, prettyName string)

AddHeading adds a new heading to the varsity.

func (*VarsityCalculator) CalculateAdmissions

func (v *VarsityCalculator) CalculateAdmissions() []CalculationResult

CalculateAdmissions performs the main admission calculation logic for the varsity.

func (*VarsityCalculator) DrainedPercent

func (v *VarsityCalculator) DrainedPercent() int

func (*VarsityCalculator) ForEachOriginalSubmitted

func (v *VarsityCalculator) ForEachOriginalSubmitted(f func(studentID string))

func (*VarsityCalculator) ForEachQuit

func (v *VarsityCalculator) ForEachQuit(f func(studentID string))

func (*VarsityCalculator) GetHeading

func (v *VarsityCalculator) GetHeading(code string) *Heading

func (*VarsityCalculator) GetStudent

func (v *VarsityCalculator) GetStudent(studentID string) *Student

func (*VarsityCalculator) Headings

func (v *VarsityCalculator) Headings() []*Heading

func (*VarsityCalculator) NormalizeApplications

func (v *VarsityCalculator) NormalizeApplications()

NormalizeApplications iterates through all headings and normalizes the applications for each one. This should be called after all applications have been loaded and before any calculation is performed.

func (*VarsityCalculator) SetOriginalSubmitted

func (v *VarsityCalculator) SetOriginalSubmitted(studentID string)

SetOriginalSubmitted marks a student as submitting their original.

func (*VarsityCalculator) SetQuit

func (v *VarsityCalculator) SetQuit(studentID string)

SetQuit marks a student as having quit.

func (*VarsityCalculator) SimulateOriginalsDrain

func (v *VarsityCalculator) SimulateOriginalsDrain(drainPercent int)

SimulateOriginalsDrain drains randomly selected drainPercent% of students who DID not submit their original but who hasn't already quit the varsity.

func (*VarsityCalculator) Students

func (v *VarsityCalculator) Students() []*Student

Students returns a slice of all students in the varsity. Useful for iterating over all students in a stable manner.