/*
 * Copyright (c) 2026 University of Insubria <https://www.uninsubria.it>
 *
 * This library 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 2.1 of the License, or (at
 * your option) any later version. All we ask is that proper credit is given
 * for our work, which includes - but is not limited to - adding the above
 * copyright notice to the beginning of your source code files, and to any
 * copyright notice that you may distribute with programs based on this work.
 *
 * This library 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, write to the Free Software Foundation, Inc.
 * <https://fsf.org/>
 */

package qsardes.descriptor;

import java.util.List;
import java.util.Map;
import qsardes.molecule.AbstractMoleculeBuilder;

/**
 * Descriptor calculator classes interface.
 * <BR><BR>
 * The following literature has been consulted for the descriptors calculators
 * development.
 * <BR><BR>
 * Burden, F. R. (1997). A chemically intuitive molecular index based on the
 * eigenvalues of a modified adjacency matrix. Quantitative Structure‐Activity
 * Relationships, 16(4), 309-314.
 * <BR><BR>
 * Consonni, V., Todeschini, R. (2010). Molecular Descriptors. In: Puzyn,
 * T. et al. Recent Advances in QSAR Studies. Challenges and Advances in
 * Computational Chemistry and Physics, vol 8. Springer, Dordrecht.
 * <BR><BR>
 * Edusoft-LC (2008). Molconn-Z version 4.10 documentation.
 * <BR><BR>
 * Gramatica, P., et al. (2000). Modelling and prediction of soil sorption
 * coefficients of non-ionic organic pesticides by molecular descriptors.
 * Chemosphere, 41(5), 763-777.
 * <BR><BR>
 * Hall, L. H., et al. (1991). The electrotopological state: structure
 * information at the atomic level for molecular graphs. Journal of chemical
 * information and computer sciences, 31(1), 76-82.
 * <BR><BR>
 * Hall, L. H., &amp; Kier, L. B. (1995). Electrotopological state indices for
 * atom types: a novel combination of electronic, topological, and valence state
 * information. Journal of Chemical Information and Computer Sciences, 35(6),
 * 1039-1045.
 * <BR><BR>
 * Hall, L. H., et al. (1995). Molecular similarity based on novel atom-type
 * electrotopological state indices. Journal of chemical information and
 * computer sciences, 35(6), 1074-1080.
 * <BR><BR>
 * Kellogg, G. E., et al. (1996). E-state fields: Applications to 3D QSAR.
 * Journal of computer-aided molecular design, 10(6), 513-520.
 * <BR><BR>
 * Kier, L. B., &amp; Hall, L. H. (1986). Molecular Connectivity in
 * Structure-Activity Analysis. Research studies press LTD.
 * <BR><BR>
 * Kier, L. B., &amp; Hall, L. H. (1990). An electrotopological-state index for
 * atoms in molecules. Pharmaceutical research, 7(8), 801-807.
 * <BR><BR>
 * Kier, L. B., et al. (1991). An index of electrotopological state for atoms in
 * molecules. Journal of Mathematical Chemistry, 7(1), 229-241.
 * <BR><BR>
 * Kier, L. B., &amp; Hall, L. H. (1997). The E-State as an extended free
 * valence. Journal of Chemical Information and Computer Sciences, 37(3),
 * 548-552.
 * <BR><BR>
 * McGillen, M. R., et al. (2024). The use of the electrotopological state as a
 * basis for predicting hydrogen abstraction rate coefficients: a proof of
 * principle for the reactions of alkanes and haloalkanes with OH. Environmental
 * Science: Atmospheres, 4(1), 18-34.
 * <BR><BR>
 * Mordred online documentation (2025).
 * https://mordred-descriptor.github.io/documentation/master/
 * <BR><BR>
 * Moriwaki, H. et al. (2018). Mordred: a molecular descriptor calculator.
 * Journal of cheminformatics, 10(1), 4.
 * <BR><BR>
 * Nilakantan, R., et al. (2006). A family of ring system-based structural
 * fragments for use in Structure− Activity studies: Database mining and
 * recursive partitioning. Journal of chemical information and modeling, 46(3),
 * 1069-1077.
 * <BR><BR>
 * Roy, K., &amp; Ghosh, G. (2004). QSTR with extended topochemical atom
 * indices. 2. Fish toxicity of substituted benzenes. Journal of chemical
 * information and computer sciences, 44(2), 559-567.
 * <BR><BR>
 * Roy, K., &amp; Das, R. N. (2011). On some novel extended topochemical atom
 * (ETA) parameters for effective encoding of chemical information and modelling
 * of fundamental physicochemical properties. SAR and QSAR in Environmental
 * Research, 22(5-6), 451-472.
 * <BR><BR>
 * Roy, K., &amp; Kabir, H. (2012). QSPR with extended topochemical atom (ETA)
 * indices: Modeling of critical micelle concentration of non-ionic surfactants.
 * Chemical engineering science, 73, 86-98.
 * <BR><BR>
 * Todeschini, R. &amp; Consonni, V. (2000). Handbook of Molecular Descriptors.
 * Wiley VCH.
 * <BR><BR>
 * Todeschini, R. &amp; Consonni, V. (2009). Molecular Descriptors for
 * Chemoinformatics. Wiley VCH.
 * <BR><BR>
 * Trinajstić, N., Nikolić, S., Lučić, B., Amić, D., &amp; Mihalić, Z. (1997).
 * The detour matrix in chemistry. Journal of chemical information and computer
 * sciences, 37(4), 631-638.
 * <BR><BR>
 * Petitjean, M. (1992). Applications of the radius-diameter diagram to the
 * classification of topological and geometrical shapes of chemical compounds.
 * Journal of chemical information and computer sciences, 32(4), 331-337.
 * <BR><BR>
 * Platts, J. A., et al. (1999). Estimation of molecular linear free energy
 * relation descriptors using a group contribution approach. Journal of Chemical
 * Information and Computer Sciences, 39(5), 835-845.
 * <BR><BR>
 * U.S Environmental Protection Agency (2008). Molecular descriptors guide
 * version 1.0.2.
 * <BR><BR>
 * Wagener, M., et al. (1995). Autocorrelation of molecular surface properties
 * for modeling corticosteroid binding globulin and cytosolic Ah receptor
 * activity by neural networks. Journal of the American Chemical Society,
 * 117(29), 7769-7775.
 * <BR><BR>
 * Yap, Chun Wei (2011). PaDEL-descriptor: An open source software to calculate
 * molecular descriptors and fingerprints. Journal of computational chemistry.
 * 32(7), 1466-1474.
 *
 * @author Nicola Chirico
 */
public interface Descriptor
{
    /**
     * Gets the descriptor class type.
     *
     * @return Descriptor class type.
     */
    public DescriptorType get_descriptor_type();

    /**
     * Gets descriptors names.
     *
     * @return Descriptor names.
     */
    public List<String> get_descriptor_names();

    /**
     * Calculates descriptors values.
     *
     * @param mol_build Molecular builder representation.
     *
     * @return Descriptor values mapped as name:value.
     */
    public Map<String, String> get_descriptor_values(
            AbstractMoleculeBuilder mol_build);
}
