core

exception pynetlogo.core.NetLogoException

Base project exception

Create a link with NetLogo. Underneath, the NetLogo JVM is started through Jpype.

If netlogo_home, netlogo_version, or jvm_home are not provided, the link will try to identify the correct parameters automatically on Mac or Windows. netlogo_home and netlogo_version are required on Linux.

Parameters:

  • gui (bool, optional) – If true, displays the NetLogo GUI (not supported on Mac)

  • thd (bool, optional) – If true, use NetLogo 3D

  • netlogo_home (str, optional) – Path to the NetLogo installation directory (required on Linux)

  • jvm_path (str, optional) – path of the jvm

  • jvmargs (list of str, optional) – additional arguments that should be used when starting the jvm

command(netlogo_command)

Execute the supplied command in NetLogo

Parameters:

netlogo_command (str) – Valid NetLogo command

Raises:

NetLogoException – If a LogoException or CompilerException is raised by NetLogo

kill_workspace()

Close NetLogo and shut down the JVM.

load_model(path)

Load a NetLogo model.

Parameters:

path (str) – Path to the NetLogo model

Raises:

  • FileNotFoundError – in case path does not exist

  • NetLogoException – In case of a NetLogo exception

patch_report(attribute)

Return patch attributes from NetLogo

Returns a pandas DataFrame with same dimensions as the NetLogo world, with column labels and row indices following pxcor and pycor patch coordinates. Values of the dataframe correspond to patch attributes.

Parameters:

attribute (str) – Valid NetLogo patch attribute

Returns:

DataFrame containing patch attributes

Return type:

pandas DataFrame

Raises:

NetLogoException – If a LogoException or CompilerException is raised by NetLogo

patch_set(attribute, data)

Set patch attributes in NetLogo

Inverse of the patch_report method. Sets a patch attribute using values from a pandas DataFrame of same dimensions as the NetLogo world.

Parameters:

  • attribute (str) – Valid NetLogo patch attribute

  • data (Pandas DataFrame) – DataFrame with same dimensions as NetLogo world

Raises:

NetLogoException – If a LogoException or CompilerException is raised by NetLogo

repeat_command(netlogo_command, reps)

Execute the supplied command in NetLogo a given number of times

Parameters:

  • netlogo_command (str) – Valid NetLogo command

  • reps (int) – Number of repetitions for which to repeat commands

Raises:

NetLogoException – If a LogoException or CompilerException is raised by NetLogo

repeat_report(netlogo_reporter, reps, go='go', include_t0=True)

Return values from a NetLogo reporter over a number of ticks.

Can be used with multiple reporters by passing a list of strings. The values of the returned DataFrame are formatted following the data type returned by the reporters (numerical or string data, with single or multiple values). If the reporter returns multiple values, the results are converted to a numpy array.

netlogo_reporterstr or list of str

Valid NetLogo reporter(s)

repsint

Number of NetLogo ticks for which to return values

gostr, optional

NetLogo command for running the model (‘go’ by default)

include_t0boolean, optional

include the value of the reporter at t0, prior to running the go command

dict

key is the reporter, and the value is a list order by ticks

NetLogoException

If reporters are not in a valid format, or if a LogoException or CompilerException is raised by NetLogo

This method relies on files to send results from netlogo back to Python. This is slow and can break when used at scale. For such use cases, you are better of using a model specific way of interfacing. For example, have a go routine which accumulates the relevant reporters into lists. First run the model for the required time steps using command, and next retrieve the lists through report.

report(netlogo_reporter)

Return values from a NetLogo reporter

Any reporter (command which returns a value) that can be called in the NetLogo Command Center can be called with this method.

Parameters:

netlogo_reporter (str) – Valid NetLogo reporter

Raises:

NetLogoException – If a LogoException or CompilerException is raised by NetLogo

report_while(netlogo_reporter, condition, command='go', max_seconds=10)

Return values from a NetLogo reporter while a condition is true in the NetLogo model

Parameters:

  • netlogo_reporter (str) – Valid NetLogo reporter

  • condition (str) – Valid boolean NetLogo reporter

  • command (str) – NetLogo command used to execute the model

  • max_seconds (int, optional) – Time limit used to break execution

Raises:

NetLogoException – If a LogoException or CompilerException is raised by NetLogo

write_NetLogo_attriblist(agent_data, agent_name)

Update attributes of a set of NetLogo agents from a DataFrame

Assumes a set of NetLogo agents of the same type. Attribute values can be numerical or strings.

Parameters:

  • agent_data (pandas DataFrame) – DataFrame indexed with a row for each agent, and columns for each attribute to update. Requires a ‘who’ column for the NetLogo agent ID

  • agent_name (str) – Name of the NetLogo agent type to update (singular, e.g. a-sheep)

Raises:

NetLogoException – If a LogoException or CompilerException is raised by NetLogo