Misc
Here are the remaining exported Vahana definitions that do not fit into any of the previous categories:
Agents
Vahana.ProcessID — TypeProcessIDThe rank on which the agent is currently managed.
Vahana.AgentID — Type AgentIDThe AgentID is a combination of different (Vahana internal) information about an agent, like e.g. the position where the agent state is stored. It's important to understand that at different times different agents can have the same agent id, therefore those ids can not be used to identify an agent a simulation run. If you need this, you must add an field to the agent state and create an unique value for this field in the agent constructor by yourself.
Vahana.all_agents — Functionall_agents(sim, ::Type{T}, [all_ranks=true])This function retrieves a vector of the states for all agents of type T of the simulation sim.
The all_ranks argument determines whether to include agents from all ranks or just the current rank in parallel simulations. When all_ranks is true, the function returns a vector of all agent identifiers across all ranks.
The states and IDs of the agents returned by all_agents and all_agentids are in the same order.
all_agents cannot be called within a transition function if the argument all_ranks is set to true.
See also all_agentids, add_agents! and num_agents.
Vahana.all_agentids — Functionall_agentids(sim, ::Type{T}, [all_ranks=true])This function retrieves a vector of the current ids for all agents of type T of the simulation sim.
These ids are not stable and can change during parallel simulations, e.g. by calling finish_init! (and hopefully in the future through dynamic load balancing).
The all_ranks argument determines whether to include agents from all ranks or just the current rank in parallel simulations. When all_ranks is true, the function returns a vector of all agent identifiers across all ranks.
The states and IDs of the agents returned by all_agents and all_agentids are in the same order.
all_agentids cannot be called within a transition function if the argument all_ranks is set to true.
See also all_agents, add_agents! and num_agents.
Vahana.num_agents — Functionnum_agents(sim, ::Type{T}, [all_ranks=true])If all_ranks is true this function retrieves the number of agents of type T of the simulation sim. When it is set to false, the function will return the number of agents managed by the process.
See also [add_agents!] and all_agents.
Vahana.add_agent_per_process! — Functionadd_agent_per_process!(sim::Simulation, agent::T) where TAdd a single agent of type T to each process in the simulation. This function is designed to be used after initialization (when the simulation is distributed to the different processes in a parallel run) but outside of transition functions. It allows each process to have its own dedicated agent, useful for tasks like random agent selection or process-specific operations.
The function takes the simulation and the agent to be added as arguments. It returns the AgentID of the agent created on the current process.
This function is not designed or optimized for adding many agents. Use it sparingly, typically to create a single agent per process for special purposes. For adding multiple agents, use the standard add_agent! or add_agents! functions within the appropriate simulation phases.
See also add_agent! and add_agents!.
Edges
Vahana.all_edges — Functionall_edges(sim, ::Type{T}, [all_ranks=true])This function retrieves a vector of (AgentID, Edge) tuples for all edges of type T of the simulation sim.
The AgentID in the tuple is the target of the edge. The specific form of the edge in the tuple depends on the hints for type T.
The all_ranks argument determines whether to include edges from all ranks or just the current rank in parallel simulations. When all_ranks is true, the function returns a vector of all edges identifiers across all ranks.
Vahana.num_edges — Methodnum_edges(sim, ::Type{T}, [sum_ranks=true])If all_ranks is true this function retrieves the number of edges of type T of the simulation sim. When it is set to false, the function will only return the number of edges of type T managed by the process.
REPL
Vahana has some features that support model development via Julia's interactive command line REPL. In this case, the simulation is not parallelized, but the same code runs later via parallelization without requiring any (or minimal) changes.
Beside the pretty-printing of a simulation as shown in the tutorial(s), there are also additional functions that allows to investigate the current state of a simulation:
Vahana.show_agent — Functionshow_agent(sim, Type{T}, [id=0; max=5, neighborstate = []])
show_agent(sim, id=0; [max=5, neighborstate = []])Display detailed information about the agent with ID id, or in the case that id is a value < 2^36, the information of the nth agent of type T. If id is 0 (the default value), a random agent of type T is selected.
Returns the ID of the agent (which is especially useful when a random agent is selected).
Keyword arguments:
max controls the maximal number of edges that are shown per network (per direction).
If a field of an agent on the source side of an edge is listed in the neighborstate vector, the value of this field will be also shown.
DataFrames.DataFrame — MethodDataFrame(sim::Simulation, T::DataType; types = false, localnr = false)Creates a DataFrame with the current state of agents or edges of type T. By default, the ID columns show the complete AgentID. for readability (and the use of show_agent) it may be useful to show only the lowest 36 bits, which gives a much more readable value, by setting the localnr argument to true. Since for edges the type information of the source and target agents is no longer available in this case, the types argument can be used to create additional columns containing the types of these agents.
DataFrame is only available when the DataFrame.jl package is imported by the model implementation.
In parallel simulations, the DataFrame method converts only the local graph partition (agents or edges) residing on the current MPI rank. It does not provide a global view of the entire distributed graph. To obtain a complete list of all agent states across all ranks, use the all_agents function. Similarly, for edges, use the all_edges function to get a global view of all edges in the distributed graph.
apply can be used to calculate a transition function without modifying the original state. This can be useful in the development process, but for the final simulation the function should be replaced with the modifying version apply!.
Simulation
Vahana.copy_simulation — Functioncopy_simulation(sim)Create an independent copy of the simulation sim. Since part of the memory is allocated via MPI, you should not use deepcopy.
Also, the copy is detached from any output or logger file so that not sim and copy tried to write to the same file(s). If these are needed, you can create these files for the copy by calling create_h5file! and/or create_logger! and assigning the results to the h5file/logging field of the returned simulation.
Returns the copy of the simulation.
Vahana.finish_simulation! — Functionfinish_simulation!(sim)Remove all agents/edges and rasters from the simulation to minimize the memory footprint. The parameters and globals of the simulation are still available, the remaining state of the simulation is undefined.
The function serves as a finalizer for the simulation object ('sim'). While it executes automatically during garbage collection, it can also be called explicitly to provide more precise control over memory management (e.g. if you only want to keep the globals as the result from the simulation).
Returns the globals of the simulation.