Microlensing Data Challenge Submission Toolkit

Welcome to the official documentation for microlens-submit, a comprehensive toolkit for managing and submitting microlensing data challenge solutions.

What is microlens-submit?

During the 2018 Data Challenge, teams mailed in spreadsheets and wrote pages of answers by hand. That process was tedious and error-prone. For Data Challenge 2, we provide this tool to automate everything from project setup to the final submission package.

microlens-submit is a stateful submission toolkit that provides:

• Project Management: Initialize and organize your submission project

• Solution Tracking: Add, edit, and manage microlensing solutions

• Validation: Comprehensive parameter and submission validation

• Export: Generate submission packages ready for upload

• Documentation: Create HTML dossiers for review and presentation

• CLI & API: Both command-line and programmatic interfaces

Key Features

• Complete Workflow: From initial project setup to final submission

• Parameter Validation: Automatic checking of model parameters and uncertainties

• Multiple Model Types: Support for 1S1L, 1S2L, 2S1L, and other microlensing models

• Higher-Order Effects: Parallax, finite source, limb darkening, and more

• Rich Documentation: Markdown notes with syntax highlighting

• HTML Dossiers: Beautiful, printable reports for submission review

• GitHub Integration: Automatic repository linking and commit tracking

• Compute Tracking: CPU and wall time monitoring for resource usage

Quick Start

# Install the toolkit
pip install microlens-submit

# Initialize your project
microlens-submit init --team-name "Your Team" --tier "beginner" ./my_submission

# Add your first solution
microlens-submit add-solution EVENT123 1S1L \
     --param t0=2459123.5 --param u0=0.15 --param tE=20.5 \
     --log-likelihood -1234.56 --n-data-points 1250

# Generate a dossier for review
microlens-submit generate-dossier

# Export your submission
microlens-submit export submission.zip

Documentation Sections

Contents:

• CLI Tutorial: A Step-by-Step Guide
  • Prerequisites
  • Learning Objectives
  • Tutorial Contents
  • Step-by-Step Guide
  • Comprehensive Best Practices Guide
  • Troubleshooting
  • Getting Help
  • About this Notebook
• Usage Examples
  • Quick Start
  • Command Line Usage
  • Supported Model Types
  • Higher-Order Effects
  • Extended Example
  • Inspecting Solutions and Resolving Duplicate Aliases (Python API)
  • Solution-Level Hardware Overrides (Python API)
  • Dossier Generation Examples
• Python API Reference
  • Core Classes
  • Loading and Saving
  • Submission Class
  • Event Class
  • Solution Class
  • Advanced Usage
  • Best Practices
  • Error Handling
• Microlensing Submission Format Manual
  • Minimal Workflow: Create → Import → (Optional: Generate Dossier) → Export
  • CSV Import Format
  • Manual Submission Format
  • Validation

Additional Resources

• CLI Tutorial: Complete step-by-step guide to using microlens-submit

• API Reference: Detailed documentation of the Python API

• Submission Manual: Complete specification for manual submission format and CSV import

• Jupyter Notebooks: Interactive tutorials in the docs directory

Getting Help

• GitHub Issues: Report bugs or request features on the GitHub repository

• Documentation: This site contains comprehensive guides and examples

• Examples: Check the Jupyter notebooks in the docs directory for detailed examples

Why Use microlens-submit?

Using microlens-submit is strongly recommended for packaging your results because it:

• Reduces Errors: Automatic validation catches common mistakes

• Saves Time: Automated workflow eliminates manual steps

• Ensures Consistency: Standardized format across all submissions

• Provides Documentation: Rich HTML dossiers for review

• Supports Collaboration: Version control friendly project structure