Cyclus Tutorial Update: Enhancements & Fixes

This article details the necessary updates and changes to the Cyclus user tutorial on cyclus.github.com. These enhancements aim to improve clarity, accuracy, and user experience. Let's dive into the specifics of each section that requires attention.

Index.rst: Streamlining the Introduction

The primary focus here is to refine the initial experience for new users. Our goal is to ensure that the tutorial accurately reflects the current state of Cyclus and provides a seamless entry point. First and foremost, remove the outdated mention of needing an internet connection. This requirement is no longer valid and can confuse users. Second, ensure the second scenario accurately portrays a growing energy demand as described. This consistency between description and scenario is crucial for comprehension and engagement. A clear and accurate introduction sets the tone for a positive learning experience.

Improving the Index.rst is essential to give the user the correct information at the start of the process. To make sure it's easy to understand, focus on clarity and correctness. First, it's important to remove any reference to needing an internet connection. This information is outdated and may confuse users, particularly those new to the system. The goal is to provide a seamless experience that allows users to focus on learning Cyclus without unnecessary complications. Remove the outdated information and replace it with clear, concise instructions that are relevant to the current version of Cyclus.

Another crucial update is to verify that the second scenario in the tutorial accurately demonstrates a growing energy demand. The description of the scenario should align perfectly with what the simulation actually does. Ensure that the simulation parameters are configured to reflect an increase in energy demand over time. This consistency is essential for reinforcing the concepts being taught and preventing confusion among users. Provide clear examples and explanations of how the energy demand grows in the scenario, and highlight the relevant parameters that control this growth. By aligning the description with the actual scenario, users will gain a more intuitive understanding of how Cyclus models energy demand.

To further enhance the user experience, consider adding a brief overview of what Cyclus is and what it can be used for. This overview should be concise and avoid technical jargon, making it accessible to a wide range of users. Highlight the key features and capabilities of Cyclus, such as its ability to model nuclear fuel cycles and simulate different scenarios. Providing this context upfront will help users understand the value of learning Cyclus and motivate them to explore the tutorial further. Additionally, include links to relevant resources, such as the Cyclus website and documentation, so that users can easily access more information if they need it. By creating a welcoming and informative introduction, you can set the stage for a successful learning experience.

Install_launch_cyclus.rst: Clarifying Installation and Access

This section requires a careful reconciliation of navigation and links to ensure users can easily install Cyclus and access necessary resources. Reconcile the navigation to the install Cyclus page with the instructions for installing Cycamore. Clarify the relationship between Cyclus and Cycamore, explaining that installing Cyclus also includes Cycamore. Verify all links to the Cycamore GitHub source code are accurate and functional. Moreover, carefully consider the relevance of the mailing list link. If appropriate, replace it with a link to the GitHub discussions page to foster a more active and accessible community forum. This shift can encourage user engagement and provide a more modern platform for questions and support.

To clarify the installation process, begin by streamlining the navigation to the install Cyclus page. Ensure that the path to this page is intuitive and easy to find from the main tutorial menu. Review the instructions on the install Cyclus page to make sure they are clear, concise, and up-to-date. Provide step-by-step guidance on how to install Cyclus on different operating systems, such as Windows, macOS, and Linux. Include screenshots or videos to illustrate the installation process and make it easier for users to follow along. Additionally, address common installation issues and provide troubleshooting tips to help users resolve any problems they may encounter.

Clarify the relationship between Cyclus and Cycamore. Explain that Cycamore is a library of archetypes that are commonly used with Cyclus, and that installing Cyclus also includes installing Cycamore. Provide a brief overview of what Cycamore is and what it can be used for, highlighting its key features and capabilities. Explain how Cycamore archetypes can be used to model different types of nuclear facilities and fuel cycle processes. By clarifying this relationship, users will gain a better understanding of how Cyclus and Cycamore work together and how they can be used to solve real-world problems.

To further enhance the user experience, consider adding a section on how to verify that Cyclus and Cycamore have been installed correctly. Provide instructions on how to run a simple Cyclus simulation to confirm that the software is working as expected. Include examples of input files and output files so that users can compare their results to the expected results. Additionally, provide links to relevant documentation and resources, such as the Cyclus website and the Cycamore GitHub repository, so that users can easily access more information if they need it. By providing clear instructions and helpful resources, you can help users successfully install Cyclus and Cycamore and get started with their own simulations.

Sim_param.rst: Enhancing Simulation Parameter Understanding

This section calls for several detailed improvements to enhance user understanding of simulation parameters. First, consider adding a page about VS Code extensions to facilitate code editing and debugging. Then, change the text order in the first paragraph to improve flow and readability. Correct the indentation of Item 5 in the control block description for better presentation. Add a note emphasizing the flexibility of time steps; they are not always limited to one month. Adjust the first activity description to be clearer about the user's role and what they should accomplish. These changes will result in a more intuitive and user-friendly learning experience.

To enhance the understanding of simulation parameters, consider adding a dedicated page or section about VS Code extensions that can be used with Cyclus. VS Code is a popular code editor that offers a wide range of extensions for different programming languages and tools. There are several VS Code extensions that can be particularly helpful for working with Cyclus input files, such as extensions for syntax highlighting, code completion, and debugging. Provide instructions on how to install and configure these extensions, and explain how they can be used to improve the user's workflow. Additionally, highlight the benefits of using VS Code extensions, such as increased productivity, reduced errors, and improved code quality. By introducing users to these tools, you can help them become more efficient and effective Cyclus users.

Readability plays a critical role in ensuring that users can quickly grasp the key concepts and information presented in the tutorial. Reorganize the text in the first paragraph to follow a more logical and intuitive flow. Consider starting with a broad overview of simulation parameters and their importance in Cyclus simulations. Then, delve into the specifics of different types of simulation parameters, such as time steps, control blocks, and activity descriptions. Use clear and concise language, and avoid technical jargon whenever possible. Break up long paragraphs into shorter, more manageable chunks, and use headings and subheadings to guide the reader through the content. By improving the readability of the tutorial, you can make it easier for users to learn and retain the information presented.

To further enhance the clarity of the tutorial, pay close attention to formatting and presentation. Correct any indentation issues in the control block description, and ensure that all code examples are properly formatted and easy to read. Use consistent formatting throughout the tutorial to maintain a professional and polished look. Consider adding visual aids, such as diagrams and charts, to illustrate key concepts and relationships. Additionally, provide clear and concise explanations of all terminology and acronyms used in the tutorial. By paying attention to these details, you can create a more engaging and informative learning experience for users.

add_arche.rst: Refining Archetype Definitions and Usage

This section involves fixing errors and expanding on available information about archetypes. Correct the missing word in the Source description (