***  MCL: MiMiC Communication Library
***  Copyright (C) 2015-2025  The MiMiC Authors (see CONTRIBUTORS file for details).
***
***  This file is part of MCL.
***
***  MCL is free software: you can redistribute it and/or modify
***  it under the terms of the GNU Lesser General Public License as
***  published by the Free Software Foundation, either version 3 of
***  the License, or (at your option) any later version.
***
***  MCL is distributed in the hope that it will be useful, but
***  WITHOUT ANY WARRANTY; without even the implied warranty of
***  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
***  GNU Lesser General Public License for more details.
***
***  You should have received a copy of the GNU Lesser General Public License
***  along with this program.  If not, see <http://www.gnu.org/licenses/>.


*** List of tags and commands for client pre-defined for MiMiC communication.
***
*** FORMAT: <request> | (type, length) <comment>
***         -- requests have to start with "MCL", otherwise they are ignored
***         -- (type, length) type and length of the subsequent message
***                  --> '*'    Indicates message of unknown length, whose data transfer will be
***                             preceded by a (int) message containing the length (tag: MCL_LENGTH)
***                  --> (NONE) Request only, no subsequent message expected
***         -- MCL_X[-] Indicates the respective value from the message received after MCL_X request
***
*** NOTE: A keyword section is denoted by '***' at the begining and the end of a line.
***       For backward compatibility within major releases, keep in mind that new keywords
***       always have to be appended within a section. Do not change the order of requests
***       or tags within sections.


*** Message tags ***

    MCL_REQUEST                         | Message contains a request
    MCL_LENGTH                          | Message contains the size of the subsequent data transfer (int)
    MCL_DATA                            | Message contains data

*** Utility requests ***

    MCL_EXIT                            | (NONE) Requests client to finish the simulation
    MCL_SEND_CLIENT_ID                  | (int) Program ID in MCL (MCL_Get_program_id())
    MCL_SEND_CLIENT_NAME                | (string, *) Client program's name
    MCL_SEND_CLIENT_RUNTYPE             | (int) Calculation type performed by the client (see "Calculation type tags")
    MCL_SEND_CLIENT_APIVER              | (int, 3) Version of the MCL API of the client

*** Calculation type tags ***

    MCL_RUNTYPE_QM_RS_GRID              | QM calculation with a method using real-space grids
    MCL_RUNTYPE_QM_RS_GRID_NONUNI       | QM calculation with a method using non-uniform real-space grids
    MCL_RUNTYPE_QM_GTO                  | QM calculation with a method using GTOs
    MCL_RUNTYPE_MM                      | MM calculation with fixed-point-charge forcefield
    MCL_RUNTYPE_MM_POL                  | MM calculation with polarizable forcefield

*** Initial data requests ***

    MCL_SEND_NUM_PARTICLES              | (int)
    MCL_RECV_NUM_PARTICLES              | (int)
    MCL_SEND_PARTICLE_MULTIPOLE_ORDER   | (int, NUM_PARTICLES or NUM_SPECIES)
    MCL_RECV_PARTICLE_MULTIPOLE_ORDER   | (int, NUM_PARTICLES or NUM_SPECIES)
    MCL_SEND_PARTICLE_MULTIPOLES        | (double, NUM_PARTICLES or NUM_SPECIES)
    MCL_RECV_PARTICLE_MULTIPOLES        | (double, NUM_PARTICLES or NUM_SPECIES)

    MCL_SEND_NUM_FRAGMENTS              | (int)
    MCL_RECV_NUM_FRAGMENTS              | (int)
    MCL_SEND_NUM_PARTICLES_IN_FRAGMENTS | (int, NUM_FRAGMENTS)
    MCL_RECV_NUM_PARTICLES_IN_FRAGMENTS | (int, NUM_FRAGMENTS)
    MCL_SEND_PARTICLE_IDS_IN_FRAGMENTS  | (int, NUM_PARTICLES_IN_FRAGMENT[-])
    MCL_RECV_PARTICLE_IDS_IN_FRAGMENTS  | (int, NUM_PARTICLES_IN_FRAGMENT[-])

    MCL_SEND_NUM_PARTICLE_SPECIES       | (int)
    MCL_RECV_NUM_PARTICLE_SPECIES       | (int)
    MCL_SEND_PARTICLE_SPECIES_IDS       | (int, NUM_PARTICLES)
    MCL_RECV_PARTICLE_SPECIES_IDS       | (int, NUM_PARTICLES)
    MCL_SEND_SPECIES_ELEMENTS           | (int, NUM_PARTICLE_SPECIES)
    MCL_RECV_SPECIES_ELEMENTS           | (int, NUM_PARTICLE_SPECIES)
    MCL_SEND_SPECIES_MASSES             | (double, NUM_PARTICLE_SPECIES)
    MCL_RECV_SPECIES_MASSES             | (double, NUM_PARTICLE_SPECIES)
    MCL_SEND_SPECIES_LABELS             | (string, *) comma delimited, NUM_PARTICLE_SPECIES entries
    MCL_RECV_SPECIES_LABELS             | (string, *) comma delimited, NUM_PARTICLE_SPECIES entries

    MCL_SEND_NUM_CONSTR_BONDS           | (int)
    MCL_RECV_NUM_CONSTR_BONDS           | (int)
    MCL_SEND_CONSTR_BOND_PARTICLE_IDS   | (int, 2*NUM_CONSTR_BONDS)
    MCL_RECV_CONSTR_BOND_PARTICLE_IDS   | (int, 2*NUM_CONSTR_BONDS)
    MCL_SEND_CONSTR_BOND_LENGTHS        | (int, NUM_CONSTR_BONDS)
    MCL_RECV_CONSTR_BOND_LENGTHS        | (int, NUM_CONSTR_BONDS)

    MCL_SEND_NUM_CONSTR_ANGLES          | (int)
    MCL_RECV_NUM_CONSTR_ANGLES          | (int)
    MCL_SEND_CONSTR_ANGLE_PARTICLE_IDS  | (int, 3*NUM_CONSTR_ANGLES)
    MCL_RECV_CONSTR_ANGLE_PARTICLE_IDS  | (int, 3*NUM_CONSTR_ANGLES)
    MCL_SEND_CONSTR_ANGLES              | (int, NUM_CONSTR_ANGLES)
    MCL_RECV_CONSTR_ANGLES              | (int, NUM_CONSTR_ANGLES)
    
    MCL_SEND_BOX_NUM_GRIDPOINTS         | (int) 
    MCL_SEND_BOX_ORIGIN                 | (double, 3)
    MCL_SEND_BOX_VECTORS                | (double, 3*3)
    MCL_SEND_BOX_GRIDPOINT_COORDS       | (double, 3*BOX_NUM_GRIDPOINTS)
    MCL_SEND_BOX_GRIDPOINT_VOLUMES      | (double, BOX_NUM_GRIDPOINTS)
    MCL_SEND_PBC_DIMENSION              | (int) Expected values: 0, 1, 2, 3

    MCL_SEND_NUCLEAR_CHARGES            | (double, NUM_SPECIES)
    MCL_SEND_NUM_BOUNDARY_BONDS         | (int)
    MCL_SEND_BOUNDARY_BOND_ATOMS        | (int, 2*NUM_BOUNDARY_BONDS)

*** Repeated data requests ***

    MCL_SEND_PARTICLE_POSITIONS         | (double, 3*NUM_PARTICLES) 
    MCL_RECV_PARTICLE_POSITIONS         | (double, 3*NUM_PARTICLES)
    MCL_SEND_PARTICLE_FORCES            | (double, 3*NUM_PARTICLES)
    MCL_RECV_PARTICLE_FORCES            | (double, 3*NUM_PARTICLES)
    MCL_SEND_POTENTIAL_ON_GRIDPOINTS    | (double, BOX_NUM_GRIDPOINTS)
    MCL_RECV_POTENTIAL_ON_GRIDPOINTS    | (double, BOX_NUM_GRIDPOINTS)
    MCL_SEND_DENSITY                    | (double, BOX_NUM_GRIDPOINTS)
    MCL_RECV_DENSITY                    | (double, BOX_NUM_GRIDPOINTS)
    MCL_SEND_REFERENCE_CHARGES          | (double, NUM_PARTICLES) 
    MCL_RECV_REFERENCE_CHARGES          | (double, NUM_PARTICLES) 
    MCL_SEND_ENERGY                     | (double) 
    MCL_RECV_ENERGY                     | (double) 

*** Run requests ***

    MCL_COMPUTE_ENERGY                  | (NONE) Requests client to compute subsystem energies
    MCL_COMPUTE_FORCES                  | (NONE) Requests client to compute subsystem forces
