Troubleshooting

Steps to take when things go wrong

  1. Check the Messages tab of the CLEM component to see all errors and warnings clearly displayed with fixes and suggestions where available.
  2. Address each simulation or validation error and run the simulation again (you may need to clear the data store see Some known issues below)
  3. If the errors occurred as you open your simulation file after upgrading APSIM Next Generation, read the Important updates section of the What's New page to assist you with updating your simulation files (*.apsimx) to work with the latest changes in CLEM.
  4. Read the related sections of this help system. For example, read the sections relating to the resource type and activity reported in the error. These entries will often give details of what is needed.
  5. Submit a question or issue to the APSIM git repository issues page. The CLEM or APSIM developers, or the wider CLEM community, will respond in this forum.

Git is a free and open-source, version control system used by software developers and data analysts to manage and track collaborative changes in shared code and data files. APSIM developers use Git to further develop and request updates to the APSIM software. The APSIM GitHub repository is where you will find all APSIM Next Generation code. This is also the place where Issues, Questions and New Feature Requests can be submitted and these will be acted upon by the community of developers.

In order to interact with the Git Repository you will require a a github account which is free to create. Using Git is also a useful skill when sharing files such as your simulation files with a team. Once you have logged in click the repository link above to be taken directly to the Issues page where you can submit your request.

Alternatively, you can move to step 6, but emailed requests may be slower to be acted upon.

  1. Contact us for assistance

We are currently planning a FAQ blog to provide some of the detailed assistance we have given to users, as well as providing walk through and video tutorials. Please let us know what aspects of using the model you would find beneficial.

 

Errors and warnings

The CLEM modelling environment will provide you with any errors, warnings and invalid parameters as you develop your model after running a simulation (see Summary information).

The APSIM Next Generation software reports errors generated during a simulation in the lower panel of the screen (as well as in the data store database). The error details provided in this panel are created by the programming language and may not be easily understood by users. Even CLEM generated errors displayed in this panel are influenced by formatting characters and only the first of multiple warnings will be provided.

We highly recommend that you check the Messages tab of the CLEM component to display the outcome of any simulation! This display will provide full details of any errors and warnings, often including how to address the problem, in a clean and clear format. This display will also provide warnings that did not cause the simulation to be terminated and that you should take into consideration.

During the development of CLEM we have not yet tested every aspect of using the model. The following list provides help with some known issues:

You may be presented with an old error or warning even after you believe it has been addressed. In this situation try clearing the DataStore component and re-run your simulation. This can be achieved by right clicking the DataStore and selecting Empty the data store from the pop-up menu. If the error appears when you next run the model you can be sure it is a current problem that needs addressing.

This issue should now be fixed with the 2025 Major Update. Some issues still arise form the use of Report query and Report pivot reports (see below).

Sometimes the APSIM environment will benefit from clearing of the DataStore especially if you have run different simulation components or an experiment. This can be achieved by right clicking the DataStore and selecting Empty the data store from the pop-up menu. Next, re-run your simulation.

This will also fix blank columns when you change the style of the ledger reports and reorder columns to the order inn your report.

When adding a new model to the simulation tree (see Managing model components) you may find that an error is thrown when you try and view the descriptive summary. This is merely a problem in producing the summary information. Please report the issue at the APSIM GIT Repository issues section or email us. You may find that you can set your initial values by opening the JSON based apsimx file in a text editor if you feel confident to do so. This may resolve the issue when opened again in CLEM.

The experiment functionality offer by APSIM allows a full-factorial approach to running a suite of simulations across a defined parameter space. This approach takes advantage of multi-processor systems by running a number of simulations on different threads of the computer or high performance computer CPUs. In doing so we can currently experience issues in modifying the database to add table views generated by Report pivot and Report query components. To try and fix this issue try the following approaches

  1. Try run the simulation again

  2. Empty the data store and try run again

  3. Delete the data store and try run again. This database file will be named [simulation name].db and found in your project directory

  4. Run the underlying base model before running any of the simulations from the experiment (after deleting the database). To do this right click on the Simulation component nested inside the Experiment and select Run Simulation. Once the results of the simulation have been created and can be viewed, run the simulations required from the experiment.

APSIM help

The Using CLEM section will provide step by step instructions for using CLEM in the APSIM Next Generation modelling environment. While this help system provides information on reporting and graphing, we refer you to the APSIM help for further details of using APSIM models and tools.

Model improvement and bugs

During the initial release of CLEM you may find a bug or have a suggestion for improvement. These can be reported to us via the APSIM git repository issues page. See note above regarding using Git and GitHub.

Research collaboration

Some research projects will require further assistance to set up the simulation and add new functionality to the model. Please contact us to discuss collaborative research projects and CLEM training workshops.