Using the AstroCodEx#
The astrocodex is organized as a jupyter-book built with myst tools. This allows for exercises to be rendered as webpages with rich text annotation (such as tips and warnings) which can also be rendered directly within jupyter notebooks with the jupyterlab myst plugin. To install the jupyterlab myst plugin, run pip install jupyterlab_myst in your terminal. Any exercise can be downloaded as a jupyter notebook by selecting the .ipynb option from the Download icon on each exercise page. Required external datasets are linked from the respective exercise. All required Python packages are listed on each exercise page.
Materials on the site—including both jupyter notebooks and external datasets—can be copied and modified to suit teaching needs. Users agree not to use downloaded materials for commercial purposes. Credit should be given to the AstroCodEx Collaboration and authors if materials are used in a public format (outside of a classroom setting), including modified versions of the activities. We request that users withhold from uploading AstroCodEx materials into AI tools.
Solutions to individual exercises in the repository may be granted upon request, and solutions to the full solution set may be granted upon joining the AstroCodEx Peer Review Community. See the Solutions section below for more details.
Searching for Exercises#
We organize the exercises in the AstroCodEx along several axes to make it easy for instructors to find examples relevant to their needs. The tags and intended audience categories discussed below are searchable and filterable on the site.
Intended Audience#
We also assign each exercise an intended audience, from either “Early Undergraduate”, “Intermediate Undergraduate”, “Advanced Undergraduate”, and “Graduate”. These are, if relevant, assigned independently for the coding level and astronomical background assumed by the assignment. We note that these categories are inherently limited, given significant variance in when and how people learn astronomy and coding. Because the primary intended use of these exercises is within formal courses, we felt that some general pinning to academic progression may be useful for users. For context, these categories generally assume a standard astronomy major curriculum track in terms of astronomy content, and they assume that students begin learning to code in “Early Undergraduate”, with Intermediate Undergraduate corresponding to 1-2 years of coding experience, and so on. Instructors should adjust the level they are searching for if their course does not meet these general assumptions.
Submitting New Exercises#
The astrocodex is open-source, and we encourage contributions. If you have an exercise that you think would fit well into the codex, you may submit it through the AstroCodEx Submission and Modification Form. All submissions should be formatted with the provided template, which will ensure proper rendering and formatting on the website using MyST Markdown. Every contribution to AstroCodEx is reviewed by one AstroCodEx maintainer (assigned as the “editor”) and undergoes a peer review by at least one other person (assigned as the “reviewer”). This review assesses clarity of the activity instructions, the appropriateness of the assignment’s level, and whether the activity is appropriate to be included in the AstroCodEx. Any concerns regarding the assignment’s content or structure will be communicated to the contributors for revision before it is uploaded to AstroCodEx. During the peer review process, maintainers will also proofread and edit the assignment for grammatical and typological errors, and may add elements to match the styles used on the site. Contributors can expect to hear back from maintainers about acceptance of their contributions within 2-4 weeks, with potentially longer wait times following events such as Hack Days.
The exercise submission form requires the following inputs:
An author / contributor list with associated ORCIDs,
A short (one-line) description of the contents,
The intended audience (Early Undergraduate, Intermediate Undergraduate, Advanced Undergraduate, Graduate) ,
A set of tags highlighting Python or Astronomy concepts covered,
A requirements.txt file with a list of any packages needed to complete the exercises,
Any images or external data files needed,
A list of learning objectives for the assignment,
Any relevant instructor notes for carrying out the assignment,
Solutions for the submitted exercise.
For external data files over 50 MB, a publicly available link should be provided to the data. Following the peer review process, the files will be uploaded to Zenodo for long-term accessibility.
Maintenance#
The AstroCodEx Team includes maintainers who are responsible for maintenance of the AstroCodEx page and submissions. Maintainers will update the AstroCodEx website for readability and accessibility. Given that Python packages may lose compatibility with newer versions, maintainers will periodically verify that assignments can still be completed using the provided requirements.txt files. Minor adjustments may be made automatically by the maintainers for the purpose of supporting version compatibility over time. If major adjustments are necessary, maintainers will reach out to the assignment author(s) to make changes. To modify your assignment yourself, see the AstroCodEx Submission and Modification Form. Maintainers will review and update modified assignments within 2-4 weeks.
Solutions#
Solutions to AstroCodEx exercises are not publicly distributed in order to preserve their effectiveness in classroom and instructional settings. Individual solutions are available upon request via the Solution Request Form. Access is granted by the AstroCodEx maintainers on a case-by-case basis. Generally, faculty and instructors of record should expect to be granted solution access, while teaching assistants or other instructors may be asked for additional context or verification.
Members of the AstroCodEx Peer Review Community will be granted access to the full solution set. Members of the Peer Review Community agree to review up to 3 repository submissions per year, and membership is renewed on an annual basis. In general, we seek peer reviewers who have a masters degree in physics/astrophysics and who have contributed at least one exercise to the repository.
Users who are granted access to solutions agree not to share, distribute, or post solutions publicly. This includes sharing with students, uploading to public repositories, or redistributing in any form outside of the approved instructional context. We also request that solutions not be submitted to AI tools or platforms. We ask instructors to use discretion in handling solutions. As these exercises are designed for reuse across courses and institutions, limiting the circulation of solutions helps to maintain their long-term value.
AI Policy#
AstroCodEx is intended to be a community-driven collection of exercises developed by instructors and researchers with domain expertise. These exercises are designed to reflect authentic scientific workflows, including working with real and often complex datasets.
We ask that contributors take full responsibility for the content and quality of the exercises they submit. Limited use of AI tools is permitted during the development process; however, contributions should reflect the author’s own understanding and intent. Any use of AI in the creation of an exercise should be clearly indicated at the time of submission.
To preserve the integrity and instructional value of the materials, we request that users do not upload AstroCodEx exercises or solutions into AI tools or platforms. Our goal is to maintain a high-quality, thoughtfully curated resource grounded in real scientific practice. These guidelines help to ensure that AstroCodEx remains a reliable and pedagogically meaningful tool for both instructors and students.