Interactive Tutorial: Getting Started with COLIB

Welcome to the Interactive COLIB Tutorial!

This tutorial will guide you through the basics of contributing to COLIB step by step. You’ll learn by doing - each section includes interactive exercises where you’ll write code and get immediate feedback.

What You’ll Learn

• Basic QMD syntax and structure
• How to write mathematical equations for power systems
• Creating proper documentation for models
• COLIB contribution standards

Step 1: Your First QMD Header

1Let’s start with the basics!

Every QMD page needs a YAML header. Try writing a basic header for a new model page about a synchronous generator.

Your task: Write a YAML header that includes:

• A title: “Synchronous Generator Model”
• Author: “Your Name”
• Categories: model, generator

🎉 Excellent! You’ve successfully created a YAML header. The header provides essential metadata for your page and helps organize content in COLIB.

❌ Not quite right. Make sure you include:

• Three dashes (—) at the beginning and end
• title: “Synchronous Generator Model”
• author: “Your Name”
• categories: [model, generator]

Step 2: Mathematical Equations

2Power system models need math!

One of COLIB’s strengths is beautiful mathematical documentation. Let’s write the fundamental equation for active power in a synchronous generator.

Your task: Write the equation for electrical power output: P = (E × V × sin(δ)) / X

Where:

• P is electrical power output
• E is internal EMF
• V is terminal voltage
• δ is power angle
• X is synchronous reactance

Use LaTeX syntax with double dollar signs for display equations and add a label {#eq-power}.

🎉 Perfect! You’ve written a properly formatted equation. LaTeX equations make your documentation professional and precise.

❌ Try again. Remember to:

• Use double dollar signs ($$)
• Write the equation: P =
• Add the label {#eq-power}

Step 3: Model Description Section

3Document your model clearly!

Good documentation explains the model’s purpose and assumptions. Let’s create a model description section.

Your task: Write a brief model description that includes:

• A heading ## Model Description
• A paragraph explaining this is a simplified synchronous generator model
• A callout block (note type) listing the key assumptions

🎉 Great work! You’ve created a well-structured model description. Clear documentation helps other researchers understand and use your models correctly.

❌ Keep trying. Make sure you include:

• The heading: ## Model Description
• A paragraph about the synchronous generator model
• A callout note using :::{.callout-note} syntax

Step 4: Cross-References

4Link it all together!

Professional documentation uses cross-references to connect different parts. Let’s reference the equation you created earlier.

Your task: Write a sentence that references the power equation from Step 2 using Quarto’s cross-reference syntax.

Hint: Use @eq-power to reference your equation.

🎉 Excellent! Cross-references make your documentation professional and help readers navigate between related content easily.

❌ Not quite. Make sure to:

• Write a complete sentence
• Include ?@eq-power somewhere in your sentence
• Explain how the equation relates to the model

Step 5: Complete Model Template

5Put it all together!

Now let’s combine everything into a complete mini model page. This is your final challenge!

Your task: Create a complete QMD page that includes:

1. YAML header (from Step 1)
2. A ## Mathematical Model section with your equation (from Step 2)
   
3. Model description section (from Step 3)
4. A reference to the equation (from Step 4)

🎊 Congratulations! You’ve successfully created a complete COLIB model page! You now understand the basic structure and can start contributing to COLIB.

Next steps: - Download the full model template from the How to Contribute page - Browse existing models for inspiration - Start working on your own contribution!

❌ Almost there! Make sure your complete page includes all elements from the previous steps in the correct order.

Congratulations! 🎉

You’ve completed the interactive COLIB tutorial! You now know how to:

• ✅ Create proper YAML headers
• ✅ Write mathematical equations in LaTeX
• ✅ Structure model documentation
  
• ✅ Use cross-references effectively
• ✅ Combine elements into a complete page

Ready for More?

• Check out Quarto Basics for advanced features
• Start your first contribution using the How to Contribute guide
• Explore the Model Template and Test Case Template for detailed guidelines
• Browse existing models and test cases in the Models section and Test Cases section for inspiration