General-purpose agent-based modeling framework
Project description
General purpose agent-based modeling library
Getting started
Quick start
pip install --upgrade cppyabm
# inside your script, e.g. test.py
from ABC import tools
obj = tools.ABC(settings = settings, free_params = free_params)
obj.sample()
obj.run()
obj.postprocess()
# in terminal
mpiexec -n available_cpu_core python test.py
# or
mpiexec -n available_cpu_threads --use-hwthread-cpus python test.py
More on it
ABC module receives two inputs from users. First, the free parameters' list that is a python dictionary that contains the names and bounds (min and max) of each free parameter, as shown below:
free_params = {
'p_name_1': [1.1,4.3], # [min,max]
'p_name_2': [6.4,23.1]
}
Second, the settings that is another python dictionary that contains user-specific information:
settings = {
"MPI_flag": True, # Use of MPI
"sample_n": 10000, # Sample number
"top_n": 100, # Number of top selected samples, i.e. posterior
"output_path": "outputs", # Relative output directory to save the results
"run_func":custom_func, # A custom function that calculates the error for a given dataset
"args":{ # Optional arguments that `custom_func` requires during calculations
"model": Model, # e.g. the model that reads parameter set and returns some results
"replica_n":3 # e.g. number of replica run for each param set
}
}
run_func
is the most important parameter that needs to be designed specifically for each problem. It can be generally formatted as:
def custom_func(paramset,args):
return distance
Which receives a paramset, passed by the ABC algorithm, alongside with other parameters encapsulated as args that would be needed to calculate distance function by the user. This function ultimately returns the distance calculated for the given paramset, which is Python float
variable.
To elaborate run_func
for a case example:
def custom_func(paramset,args):
model = args['model']
empirical_data = user_defined_variable
results = model(paramset) # runs the model for the given param set
distance = np.abs(results - empirical_data) # distance is defined in this case as absolute difference
return distance
Attentions: paramset
is a python dictionary contenting a set of parameter-value items as shown below. The user defined model
must be able to integrate this parameter set.
{
'p_name_1':2.3,
'p_name_2':7.8
}
More elaboration and examples will come soon.
Parallel or serial use
For serial use case, simply command:
from ABC import tools
obj = tools.ABC(settings = settings, free_params = free_params)
obj.sample()
obj.run()
obj.postprocess()
To run the model in parallel using MPI, save the above mentioned commands as a script and run it from Terminal:
# in terminal
mpiexec -n available_cpu_core python test.py
available_cpu_core
is the CPU core number that user intend to allocate for this process. For more info, see MPI for Python.
Outputs
The posteriors are outputed for each parameter as a json file which can be found on the given output directory. A box plot is also generated to compare prior and posterior distributions in a single graph, in SVG format.
Install/compile
###For Python development:
Using pip manager:
pip install --upgrade cppyabm
Or, download the package and in the root folder, command:
python3 setup.py install
###For Cpp development: Clone the library and add the main root as a subdirectory. Using modern Cmake, the following command will include the library:
add_subdirectory("dir_to_cppyabm")
target_include_directories("your_project" "dir_to_include/ABM")
Authors
- Jalil Nourisa
Useful links
Acknowledgments
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for cppyabm-1.0.12-cp37-cp37m-macosx_10_9_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 78b75a027627dae46685f32e6fd65a0ef1fdf4c73dc0b2ecdc090dea3c78b0e1 |
|
MD5 | a0da886f33f9eeae96d9449ec2bc3e52 |
|
BLAKE2b-256 | 39e63f20b8b29d93affbbc28530f3efb0f72b7ea44cb7743198f2498b2060800 |