📚 API Documentation

Auto-generated documentation from model and function docstrings.

Updated in real-time from the source code.

🏗️ Models

Interview

Interview model.

This contains the interview step data for the simulation.
It records the interview status between each student and school in the simulation.
This includes the student's interview rank of the school and the school's interview rank of the student

Fields:

Name Type Description
id BigAutoField -
status CharField -
student_applied BooleanField Whether the student has been applied to the school.
student_signal IntegerField Signal value from the student to the school
student_accepted BooleanField Whether the student has been accepted to the school invitation to interview.
student_true_score_of_school FloatField True score of school with respect to student
school_invited BooleanField Whether the school has been invited to the interview. Must have applied to school first
student_pre_observed_score_of_school FloatField Pre interview "total" score of student
school_pre_observed_score_of_student FloatField Pre interview "total" score of school
school_true_score_of_student FloatField True score of student with respect to school
students_pre_rank_of_school IntegerField Pre interview rank of student
schools_pre_rank_of_student IntegerField Pre interview rank of school
student_post_observed_score_of_school FloatField Post interview "total score" of student
school_post_observed_score_of_student FloatField Post interview "total" score of school
students_post_rank_of_school IntegerField Post interview rank of student
schools_post_rank_of_student IntegerField Post interview rank of school

Match

Match model.

This contains the match step data for the simulation.
It records the match status between each student and school in the simulation
This includes the student's match rank of the school and the school's match rank of the student

Fields:

Name Type Description
id BigAutoField -
students_rank_of_school IntegerField -
schools_rank_of_student IntegerField -

School

School model.

This contains each school in a simulation. The school "population".

Fields:

Name Type Description
interviews ManyToOneRel -
matches ManyToOneRel -
id BigAutoField -
name CharField Name of the school.
capacity IntegerField Capacity of the school.
score FloatField Score of the school.
meta_stddev FloatField Standard deviation of the score.
score_meta JSONField Meta score names and value {"Research":5, "Reputation": 10} for the score.
meta_stddev_preference FloatField Standard deviation of the preference.
meta_preference JSONField Meta score names and value {"USMLE Setp 2":5, "Grades": 10} for the preference.

Simulation

Simulation model.

This contains the very basic simulations setup and links to the others parts of a simulation

method: create_students() -> builds the population of students
method: create_schools() -> builds the population of schools
method: upload_students() -> uploads students from a CSV file
method: upload_schools() -> uploads schools from a CSV file

Fields:

Name Type Description
configs ManyToOneRel -
students ManyToOneRel -
schools ManyToOneRel -
interviews ManyToOneRel -
matches ManyToOneRel -
id BigAutoField -
name CharField -
public BooleanField -
description TextField -
iterations IntegerField -
created_at DateTimeField -
status CharField -

Methods:

create_schools(self) -> int
Create the school population for this simulation using its latest SimulationConfig.

Behavior:
- Uses the most recent SimulationConfig linked to this Simulation (by id desc).
- Clears existing schools for this simulation before creation.
- Generates `number_of_schools` schools named "School {i}" with scores drawn from a
  beta distribution using school_score_mean and school_score_stddev, ensuring scores stay between 0-1.
  Capacities use Gaussian distribution. Capacity is coerced to an int >= 0.
- Uses school_meta_scores_stddev from config when generating score_meta values based on
  config.applicant_meta_preference: each meta gets beta-distributed scores with base_score as mean.
- Also generates meta_preference weights per school using config.school_meta_preference and
  config.school_meta_preference_stddev, storing the stddev into meta_stddev_preference.
- Returns the number of schools created.
create_students(self) -> int
Create the student population for this simulation using its latest SimulationConfig.

Behavior:
- Uses the most recent SimulationConfig linked to this Simulation (by id desc).
- Clears existing students for this simulation before creation.
- Generates `number_of_applicants` students named "Student {i}" with scores drawn from a
  beta distribution using applicants_score_mean and applicant_score_stddev, ensuring scores stay between 0-1.
- Uses applicant_meta_scores_stddev from config when generating score_meta values based on
  config.school_meta_preference: each meta gets beta-distributed scores with base_score as mean.
- Also generates meta_preference weights per student using config.applicant_meta_preference and
  config.applicant_meta_preference_stddev, storing the stddev into meta_stddev_preference.
- Returns the number of students created.
delete_schools(self) -> int
Delete the school population for this simulation.
delete_students(self) -> int
Delete the student population for this simulation.
get_next_by_created_at(self, *, field=<django.db.models.fields.DateTimeField: created_at>, is_next=True, **kwargs)
get_previous_by_created_at(self, *, field=<django.db.models.fields.DateTimeField: created_at>, is_next=False, **kwargs)
upload_schools(self) -> int
Upload schools from a CSV file located in BASE_DIR/data.

Expected CSV format (with header): name,capacity,score[,score_meta]
- score_meta: JSON object string mapping meta names to values.
File path convention: data/simulation_{self.id}_schools.csv
- Replaces existing schools for this simulation.
- Returns the number of schools created. Returns 0 if the file does not exist.
upload_students(self) -> int
Upload students from a CSV file located in BASE_DIR/data.

Expected CSV format (with header): name,score[,score_meta]
- score_meta: JSON object string mapping meta names to values.
File path convention: data/simulation_{self.id}_students.csv
- Replaces existing students for this simulation.
- Returns the number of students created. Returns 0 if the file does not exist.

SimulationConfig

Simulation configuration model.

This contains the configuration of the simulation

Fields:

Name Type Description
id BigAutoField -
number_of_applicants IntegerField Total number of applicants to generate.
number_of_schools IntegerField Total number of schools to generate.
applicant_score_mean FloatField Mean of the applicants' base scores.
applicant_score_stddev FloatField Std. dev. of the applicants' base scores (>= 0).
applicant_interview_limit IntegerField Max number of interviews each applicant can attend.
applicant_meta_preference JSONField List of applicant preference meta fields (e.g., program_size, prestige).
applicant_meta_preference_stddev FloatField Std. dev. of meta preference scores (>= 0).
applicant_meta_scores_stddev FloatField Std. dev. of meta scores per applicant (>= 0).
applicant_pre_interview_rating_error FloatField Pre-interview rating error stddev
applicant_post_interview_rating_error FloatField Pre-interview rating error stddev
school_score_mean FloatField Mean of the schools' base scores.
school_score_stddev FloatField Std. dev. of the schools' base scores (>= 0).
school_capacity_mean FloatField Mean capacity per school.
school_capacity_stddev FloatField Std. dev. of capacity per school (>= 0).
school_interview_limit FloatField Max number of interviews each school can conduct In percent of capacity.
school_meta_preference JSONField List of school preference meta fields (e.g., board_scores, research).
school_meta_preference_stddev FloatField -
school_meta_scores_stddev FloatField Std. dev. of meta scores per school (>= 0).
school_pre_interview_rating_error FloatField The stddev scoreing error used to calculate the observed score for each student
school_post_interview_rating_error FloatField The stddev scoreing error used to calculate the observed score for each student

Student

Student model.

This contains each student in a simulation. The student "population".

Fields:

Name Type Description
interviews ManyToOneRel -
matches ManyToOneRel -
id BigAutoField -
name CharField Name of the student.
score FloatField Score of the student.
meta_stddev FloatField Standard deviation of the score.
score_meta JSONField Meta score names and value {"USMLE Setp 2":5, "Grades": 10} for the score.
meta_stddev_preference FloatField Standard deviation of the preference.
meta_preference JSONField Meta score names and value {"School size":5, "Reputation": 10} for the preference.

User

Custom user model extending Django's AbstractUser.
Note: Django's AbstractUser already includes username, password, email fields

Fields:

Name Type Description
logentry ManyToOneRel -
simulations ManyToOneRel -
id BigAutoField -
password CharField -
last_login DateTimeField -
is_superuser BooleanField Designates that this user has all permissions without explicitly assigning them.
username CharField Required. 150 characters or fewer. Letters, digits and @/./+/-/_ only.
first_name CharField -
last_name CharField -
email EmailField -
is_staff BooleanField Designates whether the user can log into this admin site.
is_active BooleanField Designates whether this user should be treated as active. Unselect this instead of deleting accounts.
date_joined DateTimeField -
full_name CharField -
disabled BooleanField -
status CharField -
created_at DateTimeField -
updated_at DateTimeField -
groups ManyToManyField The groups this user belongs to. A user will get all permissions granted to each of their groups.
user_permissions ManyToManyField Specific permissions for this user.

Methods:

acheck_password(self, raw_password)
See check_password().
aget_all_permissions(self, obj=None)
aget_group_permissions(self, obj=None)
See get_group_permissions()
aget_user_permissions(self, obj=None)
See get_user_permissions()
ahas_module_perms(self, app_label)
See has_module_perms()
ahas_perm(self, perm, obj=None)
See has_perm()
ahas_perms(self, perm_list, obj=None)
See has_perms()
check_password(self, raw_password)
Return a boolean of whether the raw_password was correct. Handles
hashing formats behind the scenes.
email_user(self, subject, message, from_email=None, **kwargs)
Send an email to this user.
get_all_permissions(self, obj=None)
get_full_name(self)
Return the first_name plus the last_name, with a space in between.
get_group_permissions(self, obj=None)
Return a list of permission strings that this user has through their
groups. Query all available auth backends. If an object is passed in,
return only permissions matching this object.
get_next_by_created_at(self, *, field=<django.db.models.fields.DateTimeField: created_at>, is_next=True, **kwargs)
get_next_by_date_joined(self, *, field=<django.db.models.fields.DateTimeField: date_joined>, is_next=True, **kwargs)
get_next_by_updated_at(self, *, field=<django.db.models.fields.DateTimeField: updated_at>, is_next=True, **kwargs)
get_previous_by_created_at(self, *, field=<django.db.models.fields.DateTimeField: created_at>, is_next=False, **kwargs)
get_previous_by_date_joined(self, *, field=<django.db.models.fields.DateTimeField: date_joined>, is_next=False, **kwargs)
get_previous_by_updated_at(self, *, field=<django.db.models.fields.DateTimeField: updated_at>, is_next=False, **kwargs)
get_session_auth_fallback_hash(self)
get_session_auth_hash(self)
Return an HMAC of the password field.
get_short_name(self)
Return the short name for the user.
get_user_permissions(self, obj=None)
Return a list of permission strings that this user has directly.
Query all available auth backends. If an object is passed in,
return only permissions matching this object.
get_username(self)
Return the username for this User.
has_module_perms(self, app_label)
Return True if the user has any permissions in the given app label.
Use similar logic as has_perm(), above.
has_perm(self, perm, obj=None)
Return True if the user has the specified permission. Query all
available auth backends, but return immediately if any backend returns
True. Thus, a user who has permission from a single auth backend is
assumed to have permission in general. If an object is provided, check
permissions for that object.
has_perms(self, perm_list, obj=None)
Return True if the user has each of the specified permissions. If
object is passed, check if the user has all required perms for it.
has_usable_password(self)
Return False if set_unusable_password() has been called for this user.
natural_key(self)
set_password(self, raw_password)
set_unusable_password(self)

⚙️ Utility Functions

default_applicant_meta_preference()

default_school_meta_preference()

generate_beta_score(mean: float, stddev: float) -> float

Generate a score from beta distribution with given mean and stddev.

get_beta_parameters(mean: float, desired_stddev: float) -> tuple[float, float]

Convert mean and desired standard deviation to beta distribution parameters.

For a beta distribution, if stddev is too large for the given mean,
it will be automatically reduced to the maximum possible value.

Returns:
    tuple: (alpha, beta) parameters for beta distribution

This documentation is generated in real-time from Python docstrings. To update the documentation, modify the docstrings in your source code.