Running and Retrieving Results

Running loaded models

Running loaded models implies executing the model to generate simulated outputs. This is implemented via run() method as shown below. Users can provide the report_name, which specifies data table name from the simulation for retrieving the results.

from apsimNGpy.core.apsim import ApsimModel
# Option 1: Load default maize simulation
model = ApsimModel('Maize') # case sensitive
# Run the simulation
model.run(report_name='Report')

Tip

Please note that report_name can be a string (str), implying a single database table or a list, implying that one or more than one database tables. If the later is true, then the results will be concatenated along the rows using pandas.concat method. By default, apsimNGpy looks for these report database tables automatically, and returns a concatenated pandas data frame. This may not be ideal if they are many report tables, hence the need to clearly specify the preferred report table names

Accessing Simulated Results

After the simulation runs, results can be accessed via results property attribute as pandas DataFrames. Please see note above. These results can be saved to a CSV file or printed to the console.

Another way to access the results is to use get_simulated_output() on the instantiated class object. This method accepts only one argument report_names and under the same principle explained above.

Using a context manager for class ApsimModel

Instantiate, use model and discard the edited model afterwards

from apsimNGpy.core.apsim import ApsimModel
with ApsimModel('Maize') as model:
    model.run()
    df =model.results
    summary= df.mean(numeric_only=True)
    print(summary)
    # beyond this point, the cloned files from the model are automatically deleted

CheckpointID                     1.000000
SimulationID                     1.000000
Maize.AboveGround.Wt          1225.099950
Maize.AboveGround.N             12.381196
Yield                         5636.529504
Maize.Grain.Wt                 563.652950
Maize.Grain.Size                 0.284941
Maize.Grain.NumberFunction    1986.770519
Maize.Grain.Total.Wt           563.652950
Maize.Grain.N                    7.459296
Maize.Total.Wt                1340.837427
dtype: float64

Added in version v0.39.10.20.

Saving the Simulation

When we load the model, it is usually assigned a random name. However, you can save the file using the save() method. This method takes a single argument: the desired file path or name.

see Save API details

save()

Hint

Without specifying the full path to the desired storage location, the file will be saved in the current working directory

model.save('./edited_maize_model.apsimx')

Reloading Saved Models

By default, when a model is saved, the saved file path is automatically reloaded into memory and becomes the new reference for the active ApsimModel object.

Recent versions of apsimNGpy allow users to explicitly control this behavior using the reload argument in save().

Controlling Reload Behavior

You can indicate whether the saved model should be reloaded into the current model object using the reload flag.

model.save("./edited_maize_model.apsimx", reload=False)

Example: Reload Enabled (Default Behavior)

When reload=True (the default), the saved file becomes the new active model and the internal model.path is updated accordingly, as shown in the code below.

from apsimNGpy.core.apsim import ApsimModel
from pathlib import Path

model = ApsimModel("Maize", out_path=Path("my_model.apsimx").resolve())

# Current model path
print(Path(model.path).name)
# 'my_model.apsimx'

model.save("./edited_maize_model.apsimx", reload=True)

# Model path is updated in memory
print(Path(model.path).name)
# 'edited_maize_model.apsimx'

Example: Reload Disabled

With reload=False, the model is written to disk, but the in-memory model object continues to reference the original path as shown in the code below.

from apsimNGpy.core.apsim import ApsimModel
from pathlib import Path

model = ApsimModel("Maize", out_path=Path("my_model.apsimx").resolve())

print(Path(model.path).name)
# 'my_model.apsimx'

model.save("./edited_maize_model.apsimx", reload=False)

# Path remains unchanged in memory
print(Path(model.path).name)
# 'my_model.apsimx'

Here, the new file exists on disk, but the active model object continues to reference the original file.

Using `save` Inside a Context Manager

When using ApsimModel as a context manager, special care is required. The saved file path must be different from the current model.path and reload must be set to False as shown below.

from apsimNGpy.core.apsim import ApsimModel
from pathlib import Path

with ApsimModel("Maize", out_path=Path("my_model.apsimx").resolve()) as model:
    print(Path(model.path).name)
    # 'my_model.apsimx'

    model.save("./edited_maize_model.apsimx", reload=False)

    print(Path(model.path).name)
    # 'my_model.apsimx'

In this case, the saved file remains on disk, and the in-memory model continues to reference the original path.

Warning

If the saved path matches the active model path and reload=True, the saved model file may be deleted when exiting the context.

When reload=False, only associated APSIM database files are cleaned up, and the newly saved model file is preserved.