ICON External Parameter Request Guide For Zonda Data Processing

Hey guys! 👋 Want to dive into using the ICON model with specific external parameters? This guide will walk you through submitting a request via Zonda, making sure you get your data smoothly and efficiently. We'll cover everything from setting up your request in JSON format to understanding the status labels, so let’s get started!

Understanding ICON External Parameter Requests

So, you're diving into the world of ICON (ICOsahedral Nonhydrostatic), and you need to tweak some external parameters to get the exact data you're after? Awesome! This is where the Zonda request system comes in super handy. You might be wondering, "What exactly are external parameters?" Well, think of them as the settings that tell the ICON model how to behave – things like land use, soil type, and even atmospheric conditions. Getting these right is crucial for accurate simulations.

Now, why is this so important? Imagine you're trying to simulate weather patterns over a specific region. If your model doesn't accurately represent the land surface (is it forest, urban, or water?), the simulation won't be spot-on. That's where adjusting external parameters steps in. Zonda simplifies this process by allowing you to define these parameters in a structured JSON format. This means you have precise control over your data request, ensuring you get exactly what you need for your research or application.

This whole process revolves around a few key things: the grid specifications, which define the resolution and extent of your simulation; the domains, which are specific areas you're interested in; and the external parameter settings themselves. By carefully configuring these elements, you can tailor your ICON model runs to focus on specific regions and conditions. The beauty of Zonda is that it automates much of the data processing behind the scenes. You submit your request, and Zonda crunches the numbers, pulling together the datasets you need based on your specifications.

Step-by-Step Guide to Submitting Your Request

Submitting an ICON external parameter request might sound technical, but don't worry, it's pretty straightforward once you get the hang of it! The first thing you'll want to do is give your issue a meaningful title. Think of it like naming a file – you want something that clearly describes what the request is about. For example, "ICON-Global-EU Grid Level 6 Parameter Request" tells you a lot right away.

Next up is the heart of the request: the JSON payload. You'll need to replace the PASTE_YOUR_REQUEST_HERE placeholder with your actual request. This is where you define all the specifics, like the Zonda tools you want to use, the base grid configuration, and the domains you're interested in. The JSON format might look a bit intimidating at first, but it's just a structured way of telling Zonda exactly what you need. Here’s a breakdown of what you might include:

• Zonda Settings: This section specifies which versions of the icontools and extpar libraries you want to use. Think of these as the software versions that Zonda will use to process your request.
• Base Grid: This is crucial! It defines the fundamental grid on which your simulation will run. You'll specify parameters like the grid root, grid level, output file name, and even the rotation of the grid. Getting this right ensures your simulation covers the area you're interested in at the desired resolution.
• Domains: This is where you define the specific geographic areas you're interested in. You can set up multiple domains, each with its own configuration. For each domain, you'll specify things like the region type, center coordinates, and dimensions. This is super useful if you want to focus on specific regions within your overall simulation.

Once you've pasted your JSON, click on the "Preview" tab. This is a lifesaver! It lets you double-check that your JSON is correctly formatted. If there are any errors, you'll see them here, saving you from submitting a request that won't work. If everything looks good, hit that "Create" button, and you're off to the races!

Decoding the JSON Request Structure

Let’s break down the JSON request structure a bit more, so you're totally comfortable tweaking those parameters. Imagine the JSON as a detailed instruction manual for Zonda. Each section tells it something specific about your data request.

The zonda section is your starting point. Here, you're telling Zonda which versions of the icontools and extpar it should use. This is important because different versions might have different features or bug fixes. Specifying the tags ensures consistency and reproducibility in your results.

Then comes the basegrid section. This is where you define the fundamental grid for your simulation. The grid_root and grid_level parameters determine the resolution of your grid – higher levels mean finer resolution, but also more computational cost. The outfile parameter lets you name your output file, making it easier to manage your data later. Parameters like icorotation, icopole_lat, and icopole_lon control the orientation of the grid, which can be important for regional simulations. Lastly, centre and subcentre are metadata fields that help identify the data origin.

The domains array is where you specify the geographic areas you're interested in. Each domain is a separate object within this array, allowing you to define multiple regions with different configurations. For each domain, you'll have two key sections: icontools and extpar.

In the icontools section, you define the domain's spatial properties. parent_id links the domain to its parent domain (if any), creating a nested structure. region_type specifies the type of domain (e.g., global, regional). If you're defining a regional domain, you'll use parameters like center_lat, center_lon, hwidth_lat, and hwidth_lon to specify its location and size. The lrotate, pole_lat, and pole_lon parameters allow you to rotate the domain, which can be useful for aligning it with specific geographic features.

The extpar section is where you configure the external parameters for the domain. This is where things get really interesting! You can specify various types of data, such as aerosol optical thickness (iaot_type), land use (ilu_type), albedo (ialb_type), soil type (isoil_type), and topography (itopo_type). You can also enable or disable features like cloud droplet number concentration (enable_cdnc) and EDGAR emissions (enable_edgar). The nhori parameter controls the number of horizontal grid points used for some calculations, and l_use_corine enables the use of CORINE land cover data. The tcorr_lapse_rate and tcorr_offset parameters are used for temperature corrections, and use_array_cache can improve performance in some cases.

Managing Your Request and Understanding Status Labels

Okay, you've submitted your request – now what? Managing your request and understanding the status labels is key to a smooth experience. Once you've submitted, Zonda gets to work processing your data. This can take some time, depending on the complexity of your request and the system load.

To keep you in the loop, Zonda uses status labels. These are like little flags that tell you where your request is in the pipeline. Let's break them down:

• Submitted (Yellow Badge): This means your request is in the queue and waiting to be processed. Think of it as Zonda saying, "Got it! We're on it!" You don't need to do anything at this point but wait.
• Completed (Green Badge): Hooray! This is what you want to see. It means Zonda has successfully processed your data. You'll find a link in the issue where you submitted the request. This link is your gateway to downloading your data.
• Failed (Red Badge): Uh oh, something went wrong. This means Zonda couldn't process your request. But don't panic! The download link will still be there, and it will contain a zip file with log files. These logs are your best friend – they'll help you figure out what went wrong. Common issues include incorrect JSON formatting or problems with the data sources.
• Aborted (Light Gray Badge): This means your request was stopped prematurely. This can happen due to a timeout or some other system issue. If you see this, the best thing to do is try again. If the problem persists, reach out to the maintainers for help.

Now, what if you need to make a change to your request or something goes wrong? Zonda has you covered. If you want to re-submit the request with the same parameters, just type "rerun request" (exactly like that) in a comment on the issue. Zonda will pick it up and start the process again. Keep in mind that this uses the JSON snippet in the current description, so if you've edited it, those changes will be reflected in the new submission.

Also, remember that the processed data is available for up to 7 days. So, make sure you download it within that timeframe. If you encounter any issues, don't hesitate to ping a maintainer (like @stelliom or @mjaehn) on the issue. They're there to help you out. And when you do post, make sure to include all the relevant information from the log files. This will help them diagnose the problem quickly.

Troubleshooting Common Issues

Even with the best planning, you might run into some snags. Let's look at some common issues and how to troubleshoot them. One of the most frequent problems is incorrect JSON formatting. JSON is pretty strict about its syntax, so even a small mistake (like a missing comma or a misplaced bracket) can cause the request to fail.

This is where that "Preview" tab becomes your best friend. Always, always check your JSON in the preview before submitting. It will highlight any syntax errors, making them much easier to spot. If you're still struggling, there are plenty of online JSON validators that can help.

Another common issue is incorrect parameter settings. For example, you might specify a grid configuration that's too large for the available resources, or you might request data for a region that doesn't exist. The log files are crucial for diagnosing these types of problems. They'll often contain error messages that point you directly to the problematic parameter.

Pay close attention to the error messages in the logs. They might seem cryptic at first, but they often contain valuable clues. For example, an error message might tell you that a specific file is missing or that a parameter is out of range.

If you're using regional domains, double-check your coordinates and dimensions. It's easy to make a mistake when specifying latitudes and longitudes. Make sure your domain is actually located where you think it is!

Sometimes, the issue might not be with your request at all. There could be a problem with the Zonda system itself, such as a temporary outage or a bug in the code. This is where contacting the maintainers comes in handy. They can investigate the issue and let you know if it's a system-wide problem.

When you reach out to the maintainers, be sure to provide as much information as possible. Include the issue number, the JSON snippet you used, and the relevant parts of the log files. The more information you give them, the easier it will be for them to help you.

Wrapping Up: Getting the Most Out of Zonda

So there you have it! You're now equipped to submit ICON external parameter requests like a pro. Remember, the key to success is careful planning, attention to detail, and a willingness to troubleshoot. Zonda is a powerful tool, and with a little practice, you'll be able to harness its full potential.

By following these steps and understanding the status labels, you'll be well on your way to getting the data you need for your ICON model runs. Don't be afraid to experiment with different parameters and configurations. The more you use Zonda, the more comfortable you'll become with it.

And if you ever get stuck, remember that the maintainers are there to help. Just ping them on the issue, provide the necessary information, and they'll get you back on track. Happy data processing!