Merge lp:~maddevelopers/mg5amcnlo/3.0.4-qcdonly into lp:~maddevelopers/mg5amcnlo/3.0.4

[Olivier Mattelaer]

add an option
set mixed_coupling_expansion T/F (default T)
to go back to v2 mode of generation of loop/CT.
However the new v3 phase-space is very very slow and that is handle...

[lp:~maddevelopers/mg5amcnlo/3.0.4-qcdonly]

996. By marco zaro on 2021-03-16

fix for bug https://bugs.launchpad.net/mg5amcnlo/+bug/1918942
The problem was that the coupling hierarchy was hardcoded to be 1 for QCD and 2 for QED,
while this is not the case in general

997. By olivier-mattelaer on 2021-03-17

reset NHelForMCoverHels to official default + avoid forcing widht to 0 in pure QCD case

998. By olivier-mattelaer on 2021-03-24

merge with latest 3.0.4 (including 2.9.3)

[marco zaro (marco-zaro)]

Hi Olivier,
the changes to the code look fine.
As I wrote you on skype, I would warn the user if one has nlo_mixed_expansion = False but the LO diagrams have more than one coupling combination. While this may be OK in some cases (EFT), it may be completely wrong in other (I guess for these cases one has check-poles failing, etc..)

Thanks a lot!

Cheers,

Marco

review: Approve

=== modified file 'Template/NLO/Cards/FKS_params.dat'
--- Template/NLO/Cards/FKS_params.dat	2020-05-13 10:13:31 +0000
+++ Template/NLO/Cards/FKS_params.dat	2021-03-24 10:22:46 +0000
@@ -136,7 +136,7 @@
 ! this to '-1' if you want to forbid the use of this method
 ! altogether.
 #NHelForMCoverHels
--1
+4
 ! Default :: 4
 !
 ! This parameter sets for which fraction of the events the virtual

=== modified file 'madgraph/fks/fks_base.py'
--- madgraph/fks/fks_base.py	2021-02-26 15:58:51 +0000
+++ madgraph/fks/fks_base.py	2021-03-24 10:22:46 +0000
@@ -45,13 +45,14 @@
     """A multi process class that contains informations on the born processes 
     and the reals.
     """
-    
+
     def default_setup(self):
         """Default values for all properties"""
         super(FKSMultiProcess, self).default_setup()
         self['real_amplitudes'] = diagram_generation.AmplitudeList()
         self['pdgs'] = []
         self['born_processes'] = FKSProcessList()
+
         if not 'OLP' in list(self.keys()):
             self['OLP'] = 'MadLoop'
             self['ncores_for_proc_gen'] = 0
@@ -122,6 +123,13 @@
         Real amplitudes are stored in real_amplitudes according on the pdgs of their
         legs (stored in pdgs, so that they need to be generated only once and then reicycled
         """
+
+
+        if 'nlo_mixed_expansion' in options:
+            self['nlo_mixed_expansion'] = options['nlo_mixed_expansion']
+            del options['nlo_mixed_expansion']
+
+
         #swhich the other loggers off
         loggers_off = [logging.getLogger('madgraph.diagram_generation'), 
                        logging.getLogger('madgraph.loop_diagram_generation')]
@@ -241,7 +249,7 @@
                 for real in born.real_amps:
                     real.find_fks_j_from_i(born_pdg_list)
             if amps:
-                if self['process_definitions'][0].get('NLO_mode') == 'all':
+                if self['process_definitions'][0].get('NLO_mode') in ['all']:
                     self.generate_virtuals()
                 
                 elif not self['process_definitions'][0].get('NLO_mode') in ['all', 'real','LOonly']:
@@ -316,15 +324,31 @@
                                      '%s at the output stage only.'%self['OLP'])
             return
 
+        if not self['nlo_mixed_expansion']:
+            # determine the orders to be used to generate the loop
+            loop_orders = {}
+            for  born in self['born_processes']:
+                for coup, val in fks_common.find_orders(born.born_amp).items():
+                    try:
+                        loop_orders[coup] = max([loop_orders[coup], val])
+                    except KeyError:
+                        loop_orders[coup] = val
+
+
         for i, born in enumerate(self['born_processes']):
             myproc = copy.copy(born.born_amp['process'])
+            #misc.sprint(born.born_proc)
+            #misc.sprint(myproc.input_string())
+            #misc.sprint(myproc['orders'])
             # if [orders] are not specified, then
             # include all particles in the loops
             # i.e. allow all orders to be perturbed
             # (this is the case for EW corrections, where only squared oders 
             # are imposed)
-            if not myproc['orders']:
-                myproc['perturbation_couplings'] = myproc['model']['coupling_orders']
+            if not self['nlo_mixed_expansion']:
+                myproc['orders'] = loop_orders
+            elif not myproc['orders']:
+                    myproc['perturbation_couplings'] = myproc['model']['coupling_orders']
             # take the orders that are actually used bu the matrix element
             myproc['legs'] = fks_common.to_legs(copy.copy(myproc['legs']))
             logger.info('Generating virtual matrix element with MadLoop for process%s (%d / %d)' \
@@ -335,6 +359,7 @@
                 myamp = loop_diagram_generation.LoopAmplitude(myproc)
                 born.virt_amp = myamp
             except InvalidCmd:
+                logger.debug('invalid command for loop')
                 pass
 
 

=== modified file 'madgraph/fks/fks_common.py'
--- madgraph/fks/fks_common.py	2020-03-27 19:40:16 +0000
+++ madgraph/fks/fks_common.py	2021-03-24 10:22:46 +0000
@@ -52,14 +52,17 @@
         return [((leg.get('id'), leg.get('number')), leg.get('number'))]
 
 
-def get_qed_qcd_orders_from_weighted(nexternal, weighted):
+def get_qed_qcd_orders_from_weighted(nexternal, hierarchy, weighted):
     """computes the QED/QCD orders from the knowledge of the n of ext particles
     and of the weighted orders"""
+    qed_w = hierarchy['QED']
+    qcd_w = hierarchy['QCD']
     # n vertices = nexternal - 2 =QED + QCD
-    # weighted = 2*QED + QCD
-    QED = weighted - nexternal + 2
-    QCD = weighted - 2 * QED
-    return QED, QCD
+    # weighted = qed_w*QED + qcd_w*QCD
+
+    QED = (weighted - qcd_w * (nexternal - 2) ) / (qed_w - qcd_w)
+    QCD = (weighted - qed_w * QED) / qcd_w
+    return int(QED), int(QCD)
 
 
 def link_rb_configs(born_amp, real_amp, i, j, ij):

=== modified file 'madgraph/interface/amcatnlo_interface.py'
--- madgraph/interface/amcatnlo_interface.py	2021-03-24 08:33:08 +0000
+++ madgraph/interface/amcatnlo_interface.py	2021-03-24 10:22:46 +0000
@@ -328,6 +328,7 @@
                          'real_processes', 'born_processes', 'virt_processes']
 
     _nlo_modes_for_completion = ['all','real']
+    display_expansion = False
 
     def __init__(self, mgme_dir = '', *completekey, **stdin):
         """ Special init tasks for the Loop Interface """
@@ -457,6 +458,26 @@
             run_interface.check_compiler(self.options, block=False)
         #validate_model will reset self._generate_info; to avoid
         #this store it
+        
+        if not aMCatNLOInterface.display_expansion:
+            if proc_type[2] != ['QCD'] and proc_type[1] == 'all':
+                aMCatNLOInterface.display_expansion = True
+                if 'QED' in proc_type[2]:
+                    logger.info(
+"""------------------------------------------------------------------------
+This computation involves NLO EW corrections.
+Please also cite ref. 'arXiv:1804.10017' when using results from this code.
+------------------------------------------------------------------------
+""", '$MG:BOLD')
+                else:
+                    logger.info(
+"""------------------------------------------------------------------------
+This computation involve not SM-QCD corrections at NLO.
+Please also cite ref. 'arXiv:1804.10017' when using results from this code.
+------------------------------------------------------------------------
+""", '$MG:BOLD')
+
+
         geninfo = self._generate_info
         self.validate_model(proc_type[1], coupling_type=proc_type[2])
         self._generate_info = geninfo
@@ -477,13 +498,13 @@
         # set the orders
         # if some orders have been set by the user,
         # check that all the orders of the model have been specified
-        # set to zero those which have not been specified and warn the user
+        # set to default those which have not been specified and warn the user
         if myprocdef['orders'] and not all([o in list(myprocdef['orders'].keys()) for o in myprocdef['model'].get_coupling_orders()]):
             for o in myprocdef['model'].get_coupling_orders():
                 if o not in list(myprocdef['orders'].keys()):
-                    myprocdef['orders'][o] = 0
-                    logger.warning(('%s order is missing in the process definition. It will be set to 0.\n' + \
-                                   'If this is not what you need, please regenerate with the correct orders.') % o)
+                    myprocdef['orders'][o] = self.options['default_unset_couplings']
+                    logger.warning(('%s order is missing in the process definition. It will be set to "default unser couplings": %s\n' + \
+                                   'If this is not what you need, please regenerate with the correct orders.') % (o,myprocdef['orders'][o]))
 
         # this is in case no orders have been passed
         if not myprocdef['squared_orders'] and not myprocdef['orders']:
@@ -495,23 +516,43 @@
                                       'Please specify them from the command line.')
 
             # this is a very rough attempt, and works only to guess QED/QCD
-            qed, qcd = fks_common.get_qed_qcd_orders_from_weighted(len(myprocdef['legs']), weighted['WEIGHTED'])
+            qed, qcd = fks_common.get_qed_qcd_orders_from_weighted(len(myprocdef['legs']), 
+                                                                   self._curr_model.get('order_hierarchy'), 
+                                                                   weighted['WEIGHTED'])
+
             if qed < 0 or qcd < 0:
                 raise MadGraph5Error('\nAutomatic process-order determination lead to negative constraints:\n' + \
                       ('QED: %d,  QCD: %d\n' % (qed, qcd)) + \
                       'Please specify the coupling orders from the command line.')
-            orders = {'QED': 2*qed, 'QCD': 2*qcd}
-            # set all the other coupling to zero
-            for o in myprocdef['model'].get_coupling_orders():
-                if o not in ['QED', 'QCD']:
-                    orders[o] = 0
-
-            myprocdef.set('squared_orders', orders)
-            # warn the user of what happened
-            logger.info(('Setting the born squared orders automatically in the process definition to %s.\n' + \
-                            'If this is not what you need, please regenerate with the correct orders.'), 
-                            ' '.join(['%s<=%s' %(k,v) if v else '%s=%s' % (k,v) for k,v in myprocdef['squared_orders'].items()]), 
-                            '$MG:BOLD')
+            if self.options['nlo_mixed_expansion']:
+                orders = {'QED': 2*qed, 'QCD': 2*qcd}
+                # set all the other coupling to zero
+                for o in myprocdef['model'].get_coupling_orders():
+                    if o not in ['QED', 'QCD']:
+                        orders[o] = 0
+
+                myprocdef.set('squared_orders', orders)
+                # warn the user of what happened
+                logger.info(('Setting the born squared orders automatically in the process definition to %s.\n' + \
+                                'If this is not what you need, please regenerate with the correct orders.'), 
+                                ' '.join(['%s^2<=%s' %(k,v) if v else '%s=%s' % (k,v) for k,v in myprocdef['squared_orders'].items()]), 
+                                '$MG:BOLD')
+            else:
+                orders = {'QED': qed, 'QCD': qcd}
+                sqorders = {'QED': 2*qed, 'QCD': 2*qcd}
+                # set all the other coupling to zero
+                for o in myprocdef['model'].get_coupling_orders():
+                    if o not in ['QED', 'QCD']:
+                        orders[o] = 0
+                        sqorders[o] = 0
+
+                myprocdef.set('orders', orders)
+                myprocdef.set('squared_orders', sqorders)
+                # warn the user of what happened
+                logger.info(('Setting the born orders automatically in the process definition to %s.\n' + \
+                                'If this is not what you need, please regenerate with the correct orders.'), 
+                                ' '.join(['%s<=%s' %(k,v) if v else '%s=%s' % (k,v) for k,v in myprocdef['orders'].items()]), 
+                                '$MG:BOLD')                
 
         # now check that all couplings that are there in orders also appear
         # in squared_orders. If not, set the corresponding one
@@ -530,6 +571,7 @@
         myprocdef['born_sq_orders'] = copy.copy(myprocdef['squared_orders'])
         # split all orders in the model, for the moment it's the simplest solution
         # mz02/2014
+        #if proc_type[1] != 'only':
         myprocdef['split_orders'] += [o for o in myprocdef['model'].get('coupling_orders') \
                 if o not in myprocdef['split_orders']]
 
@@ -541,10 +583,15 @@
 
         # then increase the orders which are perturbed
         for pert in myprocdef['perturbation_couplings']:
+
+            if not self.options['nlo_mixed_expansion'] and pert not in proc_type[2]:
+                    continue
+
+
             # if orders have been specified increase them
             if list(myprocdef['orders'].keys()) != ['WEIGHTED']:
                 try:
-                    myprocdef['orders'][pert] += 2
+                    myprocdef['orders'][pert] += 1
                 except KeyError:
                     # if the order is not specified
                     # then MG does not put any bound on it
@@ -572,7 +619,7 @@
         # This is necessary because when doing EW corrections one only specifies
         # squared-orders constraints. In that case, all kind of splittings/loop-particles
         # must be included
-        if not myprocdef['orders']:
+        if not myprocdef['orders'] and self.options['nlo_mixed_expansion']:
             myprocdef['perturbation_couplings'] = list(myprocdef['model']['coupling_orders'])
 
         self._curr_proc_defs.append(myprocdef)
@@ -595,11 +642,36 @@
         fks_options = {'OLP': self.options['OLP'],
                        'ignore_six_quark_processes': self.options['ignore_six_quark_processes'],
                        'init_lep_split': self.options['include_lepton_initiated_processes'],
-                       'ncores_for_proc_gen': self.ncores_for_proc_gen}
+                       'ncores_for_proc_gen': self.ncores_for_proc_gen,
+                       'nlo_mixed_expansion': self.options['nlo_mixed_expansion']}
+
+        fksproc =fks_base.FKSMultiProcess(myprocdef,fks_options)
         try:
-            self._fks_multi_proc.add(fks_base.FKSMultiProcess(myprocdef,fks_options))
+            self._fks_multi_proc.add(fksproc)
         except AttributeError: 
-            self._fks_multi_proc = fks_base.FKSMultiProcess(myprocdef,fks_options)
+            self._fks_multi_proc = fksproc
+
+        if not aMCatNLOInterface.display_expansion and  self.options['nlo_mixed_expansion']:
+            base = {}
+            for amp in self._fks_multi_proc.get_born_amplitudes():
+                nb_part = len(amp['process']['legs'])
+                for diag in amp['diagrams']:   
+                    if nb_part not in  base:
+                        base[nb_part] = diag.get('orders')
+                    elif base[nb_part] != diag.get('orders'):
+                        aMCatNLOInterface.display_expansion = True
+                        logger.info(
+"""------------------------------------------------------------------------
+This computation can involve not only purely SM-QCD corrections at NLO.
+Please also cite ref. 'arXiv:1804.10017' when using results from this code.
+------------------------------------------------------------------------
+""", '$MG:BOLD')
+                        break
+                else:
+                    continue
+                break
+
+
 
 
     def do_output(self, line):

=== modified file 'madgraph/interface/common_run_interface.py'
--- madgraph/interface/common_run_interface.py	2021-03-24 08:33:08 +0000
+++ madgraph/interface/common_run_interface.py	2021-03-24 10:22:46 +0000
@@ -940,9 +940,15 @@
                 #raise Exception, "%s %s %s" % (sys.path, os.path.exists(pjoin(self.me_dir,'bin','internal', 'ufomodel')), os.listdir(pjoin(self.me_dir,'bin','internal', 'ufomodel')))
                 import ufomodel as ufomodel
                 zero = ufomodel.parameters.ZERO
-                no_width = [p for p in ufomodel.all_particles
-                        if (str(p.pdg_code) in pids or str(-p.pdg_code) in pids)
-                           and p.width != zero]
+                if self.proc_characteristics['nlo_mixed_expansion']:
+                    no_width = [p for p in ufomodel.all_particles
+                            if (str(p.pdg_code) in pids or str(-p.pdg_code) in pids)
+                            and p.width != zero]
+                else:
+                    no_width = [p for p in ufomodel.all_particles
+                            if (str(p.pdg_code) in pids or str(-p.pdg_code) in pids)
+                            and p.width != zero and p.color!=1]
+
                 done = []
                 for part in no_width:
                     if abs(part.pdg_code) in done:

=== modified file 'madgraph/interface/madgraph_interface.py'
--- madgraph/interface/madgraph_interface.py	2021-03-24 08:33:08 +0000
+++ madgraph/interface/madgraph_interface.py	2021-03-24 10:22:46 +0000
@@ -820,7 +820,10 @@
         logger.info(" > (default: True) [Used ONLY for tree-level output with madevent]")
         logger.info(" > set the width to zero for all T-channel propagator --no impact on complex-mass scheme mode")
         logger.info("auto_convert_model <value>",'$MG:color:GREEN')   
-        logger.info(" > (default: False) If set on True any python2 UFO model will be automatically converted to pyton3 format")     
+        logger.info(" > (default: False) If set on True any python2 UFO model will be automatically converted to pyton3 format")   
+        logger.info("nlo_mixed_expansion <value>",'$MG:color:GREEN') 
+        logger.info("deactivates mixed expansion support at NLO, goes back to MG5aMCv2 behavior")
+          
 #===============================================================================
 # CheckValidForCmd
 #===============================================================================
@@ -1531,7 +1534,7 @@
             if not args[1].isdigit():
                 raise self.InvalidCmd('%s values should be a integer' % args[0])
             
-        if args[0] in ['loop_optimized_output', 'loop_color_flows', 'low_mem_multicore_nlo_generation']:
+        if args[0] in ['loop_optimized_output', 'loop_color_flows', 'low_mem_multicore_nlo_generation', 'nlo_mixed_expansion']:
             try:
                 args[1] = banner_module.ConfigFile.format_variable(args[1], bool, args[0])
             except Exception:
@@ -2583,7 +2586,7 @@
             if args[1] in ['group_subprocesses', 'complex_mass_scheme',\
                            'loop_optimized_output', 'loop_color_flows',\
                            'include_lepton_initiated_processes',\
-                           'low_mem_multicore_nlo_generation']:
+                           'low_mem_multicore_nlo_generation', 'nlo_mixed_expansion']:
                 return self.list_completion(text, ['False', 'True', 'default'])
             elif args[1] in ['ignore_six_quark_processes']:
                 return self.list_completion(text, list(self._multiparticles.keys()))
@@ -2921,8 +2924,9 @@
                     'max_t_for_channel',
                     'zerowidth_tchannel',
                     'default_unset_couplings',
+                    'nlo_mixed_expansion'
                     ]
-    _valid_nlo_modes = ['all','real','virt','sqrvirt','tree','noborn','LOonly']
+    _valid_nlo_modes = ['all','real','virt','sqrvirt','tree','noborn','LOonly', 'only']
     _valid_sqso_types = ['==','<=','=','>']
     _valid_amp_so_types = ['=','<=', '==', '>']
     _OLP_supported = ['MadLoop', 'GoSam']
@@ -2989,6 +2993,7 @@
                           'default_unset_couplings': 99, # 99 means infinity
                           'max_t_for_channel': 99, # means no restrictions
                           'zerowidth_tchannel': True,
+                          'nlo_mixed_expansion':True,
                         }
 
     options_madevent = {'automatic_html_opening':True,
@@ -7768,6 +7773,8 @@
                 logger.warning("Turning off option 'loop_color_flows'"+\
                     " since it is not available for non-optimized loop output.")
                 self.do_set('loop_color_flows False',log=False)
+        elif args[0] == "nlo_mixed_expansion":
+            self.options[args[0]] = banner_module.ConfigFile.format_variable(args[1],bool,args[0])
         elif args[0] == 'loop_color_flows':
             if log:
                     logger.info('set loop color flows to %s' % args[1])

=== modified file 'madgraph/interface/master_interface.py'
--- madgraph/interface/master_interface.py	2020-08-21 10:29:35 +0000
+++ madgraph/interface/master_interface.py	2021-03-24 10:22:46 +0000
@@ -228,10 +228,10 @@
         try:
             return  self.cmd.do_add(self, line, *args, **opts)
         except fks_base.NoBornException:
-            logger.info("------------------------------------------------------------------------", '$MG:BOLD')
+            logger.info("---------------------------------------------------------------------------", '$MG:BOLD')
             logger.info(" No Born diagrams found. Now switching to the loop-induced mode.        ", '$MG:BOLD')
-            logger.info(" Please cite ref. 'arXiv:1507.00020' when using results from this mode. ", '$MG:BOLD')
-            logger.info("------------------------------------------------------------------------", '$MG:BOLD')            
+            logger.info(" Please also cite ref. 'arXiv:1507.00020' when using results from this mode. ", '$MG:BOLD')
+            logger.info("---------------------------------------------------------------------------", '$MG:BOLD')            
             self.change_principal_cmd('MadGraph',allow_switch)
             return self.cmd.create_loop_induced(self, line, *args, **opts)
 
@@ -245,7 +245,7 @@
             if not nlo_mode in self._valid_nlo_modes: raise self.InvalidCMD(\
                 'The NLO mode %s is not valid. Please chose one among: %s' \
                 % (nlo_mode, ' '.join(self._valid_nlo_modes)))
-            elif nlo_mode == 'all':
+            elif nlo_mode in ['all']:
                 self.change_principal_cmd('MadLoop')
             elif nlo_mode == 'real':
                 raise self.InvalidCMD('Mode [real=...] not valid for checking processes.')

=== modified file 'madgraph/iolibs/export_fks.py'
--- madgraph/iolibs/export_fks.py	2021-03-24 08:33:08 +0000
+++ madgraph/iolibs/export_fks.py	2021-03-24 10:22:46 +0000
@@ -812,6 +812,7 @@
         
         self.proc_characteristic['grouped_matrix'] = False
         self.proc_characteristic['complex_mass_scheme'] = mg5options['complex_mass_scheme']
+        self.proc_characteristic['nlo_mixed_expansion'] = mg5options['nlo_mixed_expansion']
         # determine perturbation order
         perturbation_order = []
         firstprocess = history.get('generate')
@@ -2328,6 +2329,7 @@
         else:
             QED, QCD = fks_common.get_qed_qcd_orders_from_weighted(\
                     len(process_list[0].get('legs')),
+                    process_list[0].get('model').get('order_hierarchy'),
                     orders['WEIGHTED'])
 
         replace_dict = {}

=== modified file 'madgraph/iolibs/export_v4.py'
--- madgraph/iolibs/export_v4.py	2021-03-24 08:33:08 +0000
+++ madgraph/iolibs/export_v4.py	2021-03-24 10:22:46 +0000
@@ -1030,8 +1030,9 @@
                     logger.debug('WEIGHTED^2%s%s encoutered. Please check behavior for' + \
                             'https://bazaar.launchpad.net/~maddevelopers/mg5amcnlo/3.0.1/revision/613', \
                             (process.get_squared_order_type(user_sqso), sqsos[split_orders.index(user_sqso)]))
-
-                if (process.get_squared_order_type(user_sqso) =='==' and \
+                if user_sqso not in split_orders:
+                    is_a_match = False
+                elif (process.get_squared_order_type(user_sqso) =='==' and \
                         value!=sqsos[split_orders.index(user_sqso)]) or \
                    (process.get_squared_order_type(user_sqso) in ['<=','='] and \
                                 value<sqsos[split_orders.index(user_sqso)]) or \
@@ -3154,6 +3155,7 @@
 
 
         #proc_charac
+        self.proc_characteristics['nlo_mixed_expansion'] = mg5options['nlo_mixed_expansion']
         self.create_proc_charac()
 
         # Write maxparticles.inc based on max of ME's/subprocess groups
@@ -4133,6 +4135,7 @@
         # indicate that the output type is not grouped
         if  not isinstance(self, ProcessExporterFortranMEGroup):
             self.proc_characteristic['grouped_matrix'] = False
+        self.proc_characteristic['nlo_mixed_expansion'] = mg5options['nlo_mixed_expansion']
         
         self.proc_characteristic['complex_mass_scheme'] = mg5options['complex_mass_scheme']
 

=== modified file 'madgraph/various/banner.py'
--- madgraph/various/banner.py	2021-03-24 08:33:08 +0000
+++ madgraph/various/banner.py	2021-03-24 10:22:46 +0000
@@ -1509,7 +1509,8 @@
         self.add_param('perturbation_order', [], typelist=str)        
         self.add_param('limitations', [], typelist=str)        
         self.add_param('hel_recycling', False)  
-        self.add_param('single_color', True)    
+        self.add_param('single_color', True)
+        self.add_param('nlo_mixed_expansion', True)    
 
     def read(self, finput):
         """Read the input file, this can be a path to a file,