-
Notifications
You must be signed in to change notification settings - Fork 11
pyMCell Documentation
PyMcell allows for interfacing with PyNeuron. test_mcell_neuron_python.py shows some of these capabilities at a basic level. The ability of the two programs to affect each other during a simulation. In order to run this test however there are some necessary requirements. First you must get a version of neuron configured with python3 which is used for pymcell. If you have windows this is simply done with a pip3 command. Other wise you will need to download the neuron code from source and configure it with python3. The source can be found at NEURON's homepage. From there you need to configure neuron with python3 as an alternative interpreter. This can be done by following the direction for setup. The instructions can be found for macs, and linux. The instructions on these pages can be followed mostly verbatim with the except to replace the path to the regular python binary with a path to your python3 binary when you add python as an alternative interpreter.
Functions that begin with "mcell_" are basically straight swig wrapped c code (specifically the stuff we were exposing for libmcell). Obviously, the way you would design a c api versus a python api are very different. You want to play to the strengths of the language. Python code should feel pythonic; it should use python idioms. Right now, it doesn't do that, but we're slowly moving in the right direction.
Most of the functions require the "world" object, which basically contains all the information about the running simulation. This will probably always be the case unless we do a massive rewrite of MCell. The functions described below are a higher level representation of the swig wrapped c functions. They are the beginning of a transition from the basic swig wrapped c code to a more pythonic interface. Most are made to help the user accomplish tasks without having to call some of the less intuitive c functions. Some simply save the user from having to write code that is superfluous for understanding the simulation but important for the transition from c to python.
create_count(self, world, where, mol_sym, file_path)
create_count generates a reaction output block so that a molecule can is initialized to be counted in a specific region. It packages the swig wrapped mcell functions mcell_create_count, mcell_create_new_output_set and mcell_add_reaction_output_block. Therefore the user simply provides where the want the count, which molecule they want to count and the file path where the want the information output.
create_species(self, world, name, D, is_2d)
create_species generates an mcell_species_spec and then fills the structure with basic information (provided by the function arguments) and then uses the swig wrapped c function mcell_create_species
create_release_site(world, scene, pos_vec3, diam_vec3, shape, number, number_typ, mol_sym, name)
create_release_site generates a release site (named "name") with diameter diam_vec at position pos_vec3. The release site will release the molecule described by mol_sym and it will release the the number of molecules given by number. The function starts by generating two vector3 structures for the position and diameter of the release site. Then it uses the swig wrapped c functions mcell_add_to_species_list and mcell_create_geometrical_release_site to generate a list using the molecule provided as an argument in create_release_site (mol_sym) and with the list generate the release site using the rest of the arguments given in create_release_site.
world (object) -- the world object which has been generated by mcell create_instance_object
scene (instance object) -- scene for mcell simulation
pos (vector3) -- position of release site
diam (vector3) -- diameter of release site
number (int or float) -- number to be release at release site
number_type (int) -- 0 for NUMBER, 1 for CONCENTRATION
mol_sym (mcell_symbol) -- species to be released
name (string) -- name of the release site
create_reaction(world, reactant, products, rate_constant, backward_rate_constant=None, surfs=None, name=None)
create_reaction creates a reaction between the molecules provided in reactants which produces the moleculues provided in products. The rate of the reaction is given as an argument. Other details may be provided. The function begins by inspecting whether or not a mcell species struct (mcell species list) named surf was given. If not, the function generates a NULL one. The function then describes the reaction directions and rates whether reversible (given by backward_rate_constant) or not using the function mcell_create_reaction_rates. finally the reaction is generated using mcell_add_reaction_simplified which is a wrapper function for the swig wrapped c function mcell_add_reaction with some of the more specific details provided (subject to change with further development?).
def create_box_verts_elements(half_length)
create_box_verts_elements creates verteces and edges of a basic cube with volume (2*half_length)^3 centered about the orirgin. This function uses the swig wrapped c functions mcell_add_to_vertex_list and mcell_add_to_connection_list.
create_instance_object(self, world, name)
create_instance_object is effectively the same as mcell_create_instance_object.
create_surf_class(self, world, name)
Next we describe the swig wrapped c functions used in test_api.py. These functions are straigh translations from the original c code and not meant to be handled by the user. The idea is to have python functions which the user will interface with that call these low level swig translations so that the speed and power of c can be handled with the ease and tractability of Python.
mcell_add_to_species_list(mcell_symbol *species_ptr, bool is_oriented, int orientation, struct mcell_species *species_list)
mcell_add_to_species_list is a general function that creates a linked list of mcell_species from mcell_symbols. This list can be of reactants, produts, or surface classes needed for creating reactions.
mcell_set_time_step(MCELL_STATE *state, double step)
mcell_set_time_step sets the global timestep for the simulation
mcell_set_iterations(state, 1000)
mcell_set_iterations sets the number of iterations for the simulation
mcell_create_species(MCELL_STATE *state, struct mcell_species_spec *species, mcell_symbol **species_ptr)
mcell_create_species creates a new species using arguments for the molecule name, diffusion constant, custom time step, and max step length, as well as a boolean for whether the species is 2D.
mcell_create_reaction_rates(int forwardRateType, double forwardRateConstant, int backwardRateType, double backwardRateConstant)
mcell_create_reaction_rates creates a structure of the reaction rates for specific reactions
mcell_add_reaction(struct notifications *notify, double **r_step_release, struct sym_table_head *rxn_sym_table, u_int radial_subdivisions, double vacancy_search_dist2, struct mcell_species *reactants, struct reaction_arrow *react_arrow, struct mcell_species *surf_class, struct mcell_species *products, struct sym_entry *pathname, struct reaction_rates *rates, const char *forward_rate_filename, const char *backward_rate_filename)
mcell_add_reaction adds a single reaction to the simulation.
mcell_delete_species_list(struct mcell_species *species)
mcell_delete_species_list frees all memory associated with an mcell_species list.
mcell_create_surf_class( MCELL_STATE *state, char *surf_class_name, mcell_symbol **sc_sym)
mcell_create_surf_class creates the initial declaration of a surface class.
mcell_add_mol_release_to_surf_class(MCELL_STATE *state, struct sym_entry *sc_sym, struct mcell_species *sm_info, double quantity, int density_or_num, struct sm_dat *smd_list)
mcell_add_mol_release_to_surf_class creates a surface clase property to release molecules. This class needs to be added to a surface region.
mcell_add_surf_class_properties(MCELL_STATE *state, int reaction_type, mcell_symbol *sc_sym, mcell_symbol *reactant_sym, short orient)
mcell_add_surf_class_properties adds a property to a surface class.
mcell_create_instance_object(MCELL_STATE *state, char *name, struct object **new_obj)
mcell_create_instance_object creates a new instance object. You must provide the state of the system, the name of the object as well as a point to the object itself.
mcell_add_to_vertex_list(double x, double y, double z, struct vertex_list *vertices)
mcell_add_to_vertex_list creates a liked list of mesh vertices belonging to a polygon object.
mcell_add_to_connection_list(int v1, int v2, int v3, struct element_connection_list *elements)
mcell_add_to_connection_list creates a linked list of element connections describing a polygon object.
mcell_create_poly_object(MCELL_STATE *state, struct object *parent, struct poly_object *poly_obj, struct object **new_obj)
mcell_create_poly_object creates a new polygon object.
mcell_create_region(MCELL_STATE *state, struct object *obj_ptr, char *name)
mcell_create_region creates a named region on a specified object.
mcell_add_to_region_list(struct element_list *elements, u_int region_idx)
mcell_add_to_region_list adds to a linked list elements for a region.
mcell_set_region_elements(struct region *rgn, struct element_list *elements, int normalize_now)
mcell_set_region_elements sets the elements for a region normalizing the region if it's on a polygon list object. It is effectively the same as the mdl_set_region_elements function. It takes the region which will receive the elements, as well as a element list of the elements which will be embedded.
mcell_assign_surf_class_to_region(struct sym_entry *sc_sym, struct region *rgn)
mcell_assign_surf_class_to_region assigns a given surface class to a given region.
mcell_create_geometrical_release_site(MCELL_STATE *state, struct object *parent, char *site_name, int shape, struct vector3 *position, struct vector3 *diameter, struct mcell_species *mol, double num_molecules, double rel_prob, char *pattern_name, struct object **new_obj)
mcell_create_geometrical_release_site is the API function for create a geometrical molecule release site.
mcell_create_count(MCELL_STATE *state, struct sym_entry *target, short orientation, struct sym_entry *location, int report_flags, char *custom_header, struct output_column_list *count_list)
mcell_create_count creates a single count expression and returns it as an output_column list. You must pass in the MCELL_STATE the sym_entry of the target molecule as well as the molecules orientation and location (also a sym_entry). The function also asks for report flags and a custom_header.
mcell_create_new_output_set(char *comment, int exact_time, struct output_column *col_head, int file_flags, char *outfile_name)
mcell_create_new_output_set creates a new output set. Where output set is the count/trigger block which goes to a single data output file.
mcell_add_reaction_output_block(MCELL_STATE *state, struct output_set_list *osets, int buffer_size, struct output_times_inlist *otimes)
mcell_add_reaction_output_block adds a reaction data output block the to the simulation (world object).
mcell_create_viz_output(MCELL_STATE *state, char *filename, struct mcell_species *mol_viz_list, long long start, long long end, long long step, bool ascii_output)
mcell_create_viz_ouput creates a new set of viz output to be exported to a specified file. When ascii_output is True, the output is in readable text format, otherwise binary cellblender mode is used.