opengate.base ============= .. py:module:: opengate.base Classes ------- .. autoapisummary:: opengate.base.MetaSingletonFatal opengate.base.GateSingletonFatal opengate.base.MetaUserInfo opengate.base.GateObject opengate.base.DynamicGateObject opengate.base.GateUserInputSwitchDict Functions --------- .. autoapisummary:: opengate.base.process_cls opengate.base.wrap_init_method opengate.base.check_property_name opengate.base.check_property opengate.base.digest_user_info_defaults opengate.base.add_properties_to_class opengate.base._make_property opengate.base.make_docstring_for_user_info opengate.base.make_docstring opengate.base.restore_userinfo_properties opengate.base.recursive_userinfo_to_dict opengate.base.find_paths_in_gate_object_dictionary opengate.base.recursively_search_object opengate.base.find_all_gate_objects opengate.base.find_all_paths opengate.base._get_user_info_options opengate.base.create_gate_object_from_dict Module Contents --------------- .. py:class:: MetaSingletonFatal Bases: :py:obj:`type` .. py:attribute:: _instances .. py:method:: __call__(*args, **kwargs) .. py:class:: GateSingletonFatal .. py:class:: MetaUserInfo Bases: :py:obj:`type` .. py:attribute:: _created_classes .. py:method:: __call__(*args, **kwargs) .. py:function:: process_cls(cls) The factory function is meant to process classes inheriting from GateObject. It digests the user info parametrisation from all classes in the inheritance tree and enhances the __init__ method, so it calls the __finalize_init__ method at the very end of the __init__ call, which is required to check for invalid attribute setting. .. py:function:: wrap_init_method(cls) This is a factory function to process classes which inherit from GateObject. It is called from the main factory function process_cls(). This function wraps and reattaches the __init__ method of this class, if it implements one. The wrapped __init__ first calls the "original" __init__ and subsequently the method __finalize_init__, which has a base implementation in GateObject, in case the __init__ is the furthest down in the inheritance chain. The method __finalize_init__ is needed to allow GateObject.__setattr__ to check for invalid attribute setting. .. py:function:: check_property_name(name) .. py:function:: check_property(property_name, value, defaultvalue) .. py:function:: digest_user_info_defaults(cls) .. py:function:: add_properties_to_class(cls, user_info_defaults) Add user_info defaults as properties to class if not yet present. .. py:function:: _make_property(property_name, default_value, options=None, container_dict=None) Return a property that stores the user_info item in a dictionary which is an attribute of the object (self). .. py:function:: make_docstring_for_user_info(name, default_value, options) .. py:function:: make_docstring(cls, user_info_defaults) .. py:function:: restore_userinfo_properties(cls, attributes) .. py:class:: GateObject(*args, simulation=None, **kwargs) This is the base class used for all objects that handle user input in GATE. The class is assumed to be processed by process_cls(), either explicitly or via the metaclass MetaUserInfo, before any instances of the class are created. Some class attributes, e.g. inherited_user_info_defaults, are created as part of this processing. .. py:attribute:: name :type: str .. py:attribute:: inherited_user_info_defaults :type: dict .. py:attribute:: user_info_defaults .. py:method:: has_been_processed() :classmethod: .. py:attribute:: _simulation .. py:attribute:: number_of_warnings :value: 0 .. py:attribute:: _temporary_warning_cache :value: [] .. py:attribute:: user_info .. py:property:: simulation .. py:method:: __str__() .. py:method:: __getstate__() Method needed for pickling. May be overridden in inheriting classes. .. py:method:: __setstate__(d) Method needed for pickling. May be overridden in inheriting classes. .. py:method:: __reduce__() This method is called when the object is pickled. Usually, pickle works well without this custom __reduce__ method, but objects handling user_infos need a custom __reduce__ to make sure the properties linked to the user_infos are properly created The return arguments are: 1) A callable used to create the instance when unpickling 2) A tuple of arguments to be passed to the callable in 1 3) The dictionary of the object's properties to be passed to the __setstate__ method (if defined) .. py:method:: __setattr__(key, value) .. py:method:: __enter__() .. py:method:: __exit__(exception_type, exception_value, traceback) .. py:method:: __finalize_init__() This method should be called once all attributes have been defined, usually at the end of the __init__ method. It defines the set of known_attribues that will be used to detect errors when the user tries to use a new attribute or misspells an attribute, e.g. box.mohter instead of box.mother. .. py:method:: __add_to_simulation__() Hook method which can be called by managers. Specific classes can use this to implement actions to be taken when an object is being added to the simulation, e.g. adding a certain actor implies switching on certain physics options. .. py:property:: type_name .. py:method:: close() Dummy implementation for inherited classes which do not implement this method. .. py:method:: release_g4_references() Dummy implementation for inherited classes which do not implement this method. .. py:method:: copy_user_info(other_obj) .. py:method:: to_dictionary() .. py:method:: from_dictionary(d) .. py:method:: warn_user(message) .. py:class:: DynamicGateObject(*args, simulation=None, **kwargs) Bases: :py:obj:`GateObject` This is the base class used for all objects that handle user input in GATE. The class is assumed to be processed by process_cls(), either explicitly or via the metaclass MetaUserInfo, before any instances of the class are created. Some class attributes, e.g. inherited_user_info_defaults, are created as part of this processing. .. py:attribute:: dynamic_params :type: Optional[List] .. py:attribute:: user_info_defaults .. py:property:: is_dynamic .. py:property:: dynamic_user_info .. py:method:: process_dynamic_parametrisation(params) .. py:method:: _add_dynamic_parametrisation_to_userinfo(params, name) This base class implementation only acts as a setter. Classes inheriting from this class should implement an add_dynamic_parametrisation() method which actually does something with the parameters and then call super().add_dynamic_parametrisation(). Inheriting classes should avoid calling this method directly. .. py:method:: add_dynamic_parametrisation(name=None, **params) .. py:method:: create_changers() .. py:class:: GateUserInputSwitchDict(default_switches, *args, **kwargs) Bases: :py:obj:`box.Box` NOT USED YET! Specialized version of a Box (dict) to represent a dictionary with boolean switches. The switches handled by the object need to be defined when the object is created via a dictionary passed as argument 'default_switches'. No switches can be added later, nor can switches be removed. Switch values are automatically converted to Bool if possible. .. py:attribute:: _switches .. py:method:: __setitem__(key, value) .. py:method:: __delitem__(key) :abstractmethod: The 'del' operator applied on items is blocked so no entries can be removed. .. py:method:: __setattr__(key, value) Make sure to by-pass the __setattr__ method from the Box class for the key '_switches' because Box would otherwise turn this into an entry in self, but we want it to be a pure attribute. .. py:function:: recursive_userinfo_to_dict(obj) Walk recursively across entries of user_info and convert to appropriate structure. Dictionary-like structures are mapped to dictionary and walked across recursively. List-like structures are mapped to lists and walked across recursively. GateObject-like objects are converted through their to_dictionary() method. All other input (presumably common data types including numpy structures) is left untouched. .. py:function:: find_paths_in_gate_object_dictionary(go_dict, only_input_files=False) .. py:function:: recursively_search_object(obj, condition=lambda x: True) .. py:function:: find_all_gate_objects(dct) .. py:function:: find_all_paths(dct) .. py:function:: _get_user_info_options(user_info_name, object_type, class_module) Utility function to retrieve the options associated with a user info given the class name, the module in which the class is defined, and the name of the user info. .. py:function:: create_gate_object_from_dict(dct) Function to (re-)create an object derived from GateObject based on a dictionary. Used as part of the deserialization chain, when reading simulations stored as JSON file.