Documents > iChemLabs Cloud Services

Introduction

Cloud services provide quick access to advanced cheminformatics algorithms, database access, graphics functions, and other complex features that are not available directly through Javascript. This is done by utilizing the ChemDoodle Java API (the same API that powers the ChemDoodle desktop application). The ChemDoodle Web Components library accesses the ChemDoodle Java API through AJAX XMLHttpRequest Level 2 (XHR2) calls to our server. XHR2 requires that our server recognize your origins (domains). Access to our services from academic organizations is free. Otherwise, our rates are very reasonable, please contact us for options.

Licensees of Cloud services can also host the Cloud servlet on their own servers, and use AJAX XMLHttpRequest Level 1 (XHR1) calls instead, which are fully supported in all browsers. Contact us for more information.

Usage

All iChemLabs cloud services are accessed through the ChemDoodle.iChemLabs package. The complete API is listed below. Before we continue, a little background in AJAX is required. AJAX allows a browser to contact a server and update the Javascript state without reloading the current webpage. This is a very powerful technology. Most AJAX calls will be instantaneous, but it is important to note that this is an additional connection to the internet, and lag can occur for any reason. In the case of lag, we don’t want an AJAX call to hold up the loading of a webpage or to prevent responsiveness while the request is being handled, so these calls are made to be asynchronous. This is done by providing a callback function. When the server has finished handling the request, the response is returned to the callback function, which then executes. This is demonstrated in the following code using the readSMILES() function:

  <script>
    ChemDoodle.iChemLabs.readSMILES(
      // SMILES string
	    'N1(C)C(=O)N(C)C(C(=C1N1)N(C=1)C)=O',
	    // options object
	    // set the options here to control how the function performs,
	    // these options are just placeholders to demonstrate
	    {
	      'option1' : value1,
	      'option2' : value2
	    },
	    // callback function
	    function(content){
	      // The function completed successfully and the returned
	      // content is sent to the callback function.
	      // Use the content object to complete your function, here
	      // we just alert the number of atoms and bonds for the first molecule.
	      alert(content.molecules[0].atoms.length+' '+content.molecules[0].bonds.length);
	    },
	    // errorback function
	    function(){
	      // something went wrong, handle this case here
	      alert('Something went wrong, please contact the webmaster.');
	    }
	  );
  </script>

The average Cloud function will take the input parameters (in this case, the SMILES string), the options object ({}), and two functions, the callback and errorback functions. When our server completes the work, a signal is sent back to the Cloud function to finish and forward the data to the callback function (in the above case, the generated Molecule) so you may make use of it. If something went wrong, the errorback function will be called instead so you can handle errors. The errorback function is optional, and nothing will happen on error if none is provided.

Static Parameters

There are two static parameters in the iChemLabs package, SERVER_URL and asynchronous.

The SERVER_URL parameter is a String and is the url defining the hosted location of the iChemLabs Cloud services. This value is already set and should never be changed unless you have licensed Cloud services for use on your own server to take advantage of XHR1 or another reason. You can change this url as follows:

  <script>
	  ChemDoodle.iChemLabs.SERVER_URL = 'url goes here';
  </script>

The asynchronous parameter is a boolean and determines whether Cloud calls are asynchronous or not. It is true by default and recommended to be true. However, if you wish to make Cloud calls sychronous (for inclusion in testing suites for instance), which will lock the browser while they complete, then set this parameter to false:

  <script>
	  ChemDoodle.iChemLabs.asynchronous = false;
  </script>

Note that XHR2 requests will not work for synchronous calls due to browser security features. So synchronous calls should only be employed directly to your own origin via XHR1.

API

ChemDoodle.iChemLabs

  • static String SERVER_URL: the url to call for iChemLabs Cloud services through AJAX
  • static Boolean asynchronous: this value will determine if calls to AJAX services are synchronous or not
    Default Value: true
    Unit: true/false
  • static Function balanceEquation(Object toBeBalanced, Object options, Function callback, Function errorback): balances the input chemical reaction equation, either from drawn reaction data or a typed reaction equation. If the Object toBeBalanced is a String, ChemDoodle will balance the typed equation, otherwise ChemDoodle will assume it is drawn reaction data.
    Options:
    none
    Callback Handling:
    The callback receives 2 parameters: (1) the first is the balanced equation as a formatted HTML String (it will be undefined if the reaction could not be balanced, and (2) a message describing any warnings or errors associated with the function.
  • static Function calculate(Molecule mol, Object options, Function callback, Function errorback): calculates properties and descriptors for the provided Molecule
    Options:
    • Array descriptors: An array of Strings naming the descriptors to calculate for the input Molecule. If this option is not provided, or if this array is empty, then nothing is returned.

    Callback Handling:
    A named array of values is returned. Each value is associated with the name of the descriptor provided in the descriptors option.
    Descriptor  Code  Data Type
    Average Molecular Polarizability (Kang)  pol_kang  Number
    Average Molecular Polarizability (Miller)  pol_miller  Number
    Balaban Index  balaban  Number
    Bertz Molecular Complexity  bertz  Number
    Bioavailability Score  bioavailability  Number
    Branching Index  branching  Number
    Centric Index  centric  Number (Integer)
    Chi Molecular Connectivity Index  0X  Number
    Chi Molecular Connectivity Index  0Xv  Number
    Chi Molecular Connectivity Index  1X  Number
    Chi Molecular Connectivity Index  1Xv  Number
    Chi Molecular Connectivity Index  2X  Number
    Chi Molecular Connectivity Index  2Xv  Number
    Chi Molecular Connectivity Index  3X  Number
    Chi Molecular Connectivity Index  3Xv  Number
    Critical Pressure  Pc  Number
    Critical Temperature  Tc  Number
    Critical Volume  Vc  Number
    Degree of Unsaturation  deg_unsat  Number (Integer)
    Egan Violations Count  egan  Number (Integer)
    Empirical Formula  ef  String
    Enthalpy of Formation (ideal gas at 298K)  Hf298  Number
    Enthalpy of Fusion  Hf  Number
    Enthalpy of Vaporization (at Tb)  Hvb  Number
    Fraction Molecular Framework  fmf  Number
    Cyclomatic Number  cyclomatic  Number (Integer)
    Gibbs Energy of Formation (ideal gas, unit fugacity, at 298K)  G0f298  Number
    Heat Capacity (ideal gas, at 298K)  Cp0  Number
    Hosoya Index  hosoya  Number (Integer)
    Hydrogen Bond Acceptor Count  hba  Number (Integer)
    Hydrogen Bond Donor Count  hbd  Number (Integer)
    Kappa Shape Index  1K  Number
    Kappa Shape Index  1Ka  Number
    Kappa Shape Index  2K  Number
    Kappa Shape Index  2Ka  Number
    Kappa Shape Index  3K  Number
    Kappa Shape Index  3Ka  Number
    Lightest Isotopic Mass  liw  Number
    Lipinski's Rule of 5 Violations Count  lipinski  Number (Integer)
    Lipophilicity, logP, AlogP98  alogp98  Number
    Lipophilicity, logP, NC + NHET  ncnhet  Number
    Lipophilicity, logP, XlogP v2.0  xlogp2  Number
    Liquid Viscosity (at 298K)  nl  Number
    McGowan Characteristic Volume  mcgowan  Number
    Molar Refractivity (AMR)  amr  Number
    Molar Refractivity (CMR)  cmr  Number
    Molecular Formula  mf  String
    Molecular Mass  mw  Number
    Molecular Topological Index  mti  Number (Integer)
    Monoisotopic Mass  miw  Number
    Normal Boiling Point  Tb  Number
    Normal Freezing Point  Tf  Number
    Platt Index  platt  Number (Integer)
    Ring Complexity  ring_complex  Number (Integer)
    Rotatable Bond Count  rot  Number (Integer)
    Superpendentic Index  super  Number
    Szeged Index  szeged  Number (Integer)
    Topological Diameter  diameter  Number (Integer)
    Topological Polar Surface Area  tpsa  Number
    Total Number of Electrons  electron  Number (Integer)
    Veber Violation Count  veber  Number (Integer)
    Volume as a Sum of Atomic and Bond Contributions  vabc  Number
    Weiner Index  weiner  Number (Integer)
    Zagreb Index  zagreb  Number (Integer)
  • static Function cir(FormData formData, Object options, Function callback, Function errorback): this function recovers a chemical drawing from an image. This is the ChemDoodle Chemical Image Recovery (CIR) function. Others may refer to this function as Optical Structure Recognition (OSR). The FormData object must be appended with the File selected by the user named as "file". A maximum file size of 1MB is allowed.
    Options:
    • Boolean preview: If set to true, an image of the raw interpretation will be sent back as a second parameter to the callback function. The preview parameter will have 3 sub-parameters: imgsrc, width and height. The imgsrc parameter is a String representing the image as formatted Base64 source to be used as the content for the "src" attribute of an "img" element. The width parameter is the image width in pixels as an integer. The height parameter is the image height in pixels as an integer.
      Default Value: false

    Callback Handling:
    The callback function recieves 1 parameter by default. This parameter is an object with attributes of molecules (Array of Molecule) and shapes (Array of Shape) data structures generated from the CIR algorithm; the content may be empty.
  • static Function createLewisDot(Molecule mol, Object options, Function callback, Function errorback): creates a molecule that represents the input molecule as a Lewis Dot Structure; this function will use 90° angles and appropriately place lone pairs to satisfy the octet rule, charges will need to be present on the input molecule
    Options:
    none
    Callback Handling:
    A molecule data structure representing the input molecule as a Lewis Dot Structure.
  • static Function elementalAnalysis(Molecule mol, Object options, Function callback, Function errorback): performs elemental analysis on the input molecule, returning a number of results
    Options:
    none
    Callback Handling:
    One parameter is returned to the callback function, an object containing all of the elemental analysis calculations. From the object, you may access molecular_formula providing the molecular formula in HTML format, molecular_mass provides the value for molecular mass in amu, monoisotopic_mass provides the value for monoisotopic mass in amu, composition provides the elemental analysis composition breakdown, peaks provides the isotopic distribution breakdown, and jcamp is a JCAMP file for the isotopic distribution spectrum. If an error occurs, and the only real reason this would happen is if the user inputs an isotope value where there is no natural abundance on earth, a error parameter will be provided with a String description of the problem. In the case of an error, the molecular_formula variable will likely still be provided, but the other parameters will all be undefined.
  • static Function fileToImage(FormData formData, Object options, Function callback, Function errorback): this function converts a chemistry file provided by the user using a file input element into an image. The FormData object must be appended with the File selected by the user named as "file". A maximum file size of 1MB is allowed.
    Options:
    none
    Callback Handling:
    The callback function recieves 3 parameters. The first is a String representing the image as formatted Base64 source to be used as the content for the "src" attribute of an "img" element. The second is the image width in pixels as an integer. The third is the image height in pixels as an integer.
  • static Function generateIUPACName(Molecule mol, Object options, Function callback, Function errorback): generates IUPAC names for the input molecule, both the traditional name and an attempted PIN
    Options:
    none
    Callback Handling:
    Two parameters are returned to the to the callback function. The first is a String expressing the traditional IUPAC name. The second is a String expressing the attempted PIN.
  • static Function generateImage(Molecule mol, Object options, Function callback, Function errorback): generates an image file of the input Molecule in any of the chemical formats that ChemDoodle understands (specified by the ext parameter)
    Options:
    • String ext: The extension of the file format to write.
      Allowed Values: [any of the image file extensions that ChemDoodle 2D understands]
      Default Value: 'pdf'

    Callback Handling:
    A url to the generated file on our server is sent as a parameter to the callback function.
  • static Function getMoleculeFromContent(String content, Object options, Function callback, Function errorback): generates a molecule data structure from the input content string, specifying the correct format of the content by the extension of its filetype
    Options:
    • String format: The extension of the file format this content is to be interpreted as.
      Allowed Values: [any of the file extensions that ChemDoodle 2D understands, if none is provided, ChemDoodle will attempt to guess the format, but it is recommended that you provide this option]

    Callback Handling:
    The Molecule generated from the input content is sent as a parameter to the callback function.
  • static Function getMoleculeFromDatabase(String query, Object options, Function callback, Function errorback): contacts one of our partner databases to retrieve a structure for the input query
    Options:
    • Number dimension: Either integer 2 or 3, defining the dimensionality of the coordinates of the structure data to retrieve.
      Default Value: 2
      Unit: dimension
    • String database: The database to search through.
      Allowed Values: ['chemexper', 'chemspider', 'pubchem']
      Default Value: 'pubchem'

    Callback Handling:
    If the molecule is found, a Molecule data structure of the result is sent as a parameter to the callback function.
  • static Function getOptimizedPDBStructure(String id, Object options, Function callback, Function errorback): given an input PDB id, will return the atom, bond and ribbon data for the corresponding structure, if it exists; loading PDB files through this method is several magnitudes faster than by loading and parsing the data from a variable in Javascript
    Options:
    • Boolean withAtoms: If this option is false, atoms and bonds will not be returned, only ribbon data will be returned; this is useful if you want to speed up loading and rendering.
      Default Value: false

    Callback Handling:
    If the PDB data is found, a Molecule data structure of the result is sent as a parameter to the callback function.
  • static Function getSimilarityMeasure(Molecule first, Molecule second, Object options, Function callback, Function errorback): this function will compare two molecules, with a number value representing their similarity measure being returned as a parameter to the callback function; similarity is determined by useing a Dice similarity coefficient to equate two fingerprints generated for each of the input molecules using iChemLabs' path fingerprint algorithm
    Options:
    none
    Callback Handling:
    The callback function recieves a number value calculated as the similarity measure.
  • static Function getZeoliteFromIZA(String iza, Object options, Function callback, Function errorback): given an IZA code, a Molecule data structure will be generated for the zeolite data, if it exists
    Options:
    • Number xSuper: The supercell dimension along the X axis.
      Default Value: 1
      Unit: cell dimension
    • Number ySuper: The supercell dimension along the Y axis.
      Default Value: 1
      Unit: cell dimension
    • Number zSuper: The supercell dimension along the Z axis.
      Default Value: 1
      Unit: cell dimension

    Callback Handling:
    If the IZA code is found, a Molecule data structure of the result is sent as a parameter to the callback function.
  • static Function isGraphIsomorphism(Molecule arrow, Molecule target, Object options, Function callback, Function errorback): this function will determine if the arrow molecule (which may be a query molecule) is a graph isomorphism of the target molecule, with the boolean value being returned as a parameter to the callback function
    Options:
    none
    Callback Handling:
    The callback function recieves a boolean parameter defining the result of the match.
  • static Function isSubgraphIsomorphism(Molecule arrow, Molecule target, Object options, Function callback, Function errorback): this function will determine if the arrow molecule (which may be a query molecule) is a subgraph isomorphism of the target molecule, with the boolean value being returned as a parameter to the callback function
    Options:
    none
    Callback Handling:
    The callback function recieves a boolean parameter defining the result of the match.
  • static Function isSupergraphIsomorphism(Molecule arrow, Molecule target, Object options, Function callback, Function errorback): this function will determine if the arrow molecule (which may be a query molecule) is a supergraph isomorphism of the target molecule, with the boolean value being returned as a parameter to the callback function
    Options:
    none
    Callback Handling:
    The callback function recieves a boolean parameter defining the result of the match.
  • static Function kekulize(Molecule mol, Object options, Function callback, Function errorback): provided with an input Molecule, this function will kekulize either the entire single bond system, or just the resonance bonds into a valid kekule structure where pi delocalization is maximized
    Options:
    none
    Callback Handling:
    A kekulized copy of the structure will be returned as a parameter to the callback function.
  • static Function maximumCommonSubstructure(Molecule m1, Molecule m2, Object options, Function callback, Function errorback): this function will find the maximum common substructure (MCS) for the two input molecular structures
    Options:
    • Boolean disconnected: If this option is true, the MCS algorithm will return a disconnected maximum common substructure. By default, a connected maximum substructure is returned.
      Default Value: false

    Callback Handling:
    The callback function recieves an object which defines the MCS mapping, where the property names of the object are indexes (Integers as Strings) for m1 and the values for those property names are the corresponding mapped indexes (Integers as Strings) for m2.
  • static Function mechanismMatch(Molecule arrow, Array targets, Object options, Function callback, Function errorback): this function will match mechanistic drawings, ensuring that pusher arrows are drawn from the correct objects and in the correct direction for any number of molecules; any number of targets may be sent in to be matched; an array of integer values will be returned as a parameter to the callback function, 0 means no match, 1 means exact match, and 2 means partial match
    Options:
    • Boolean enforceStereo: If this option is true, the mechanism matching algorithm will enforce stereochemistry while matching. By default, stereocenters are not important.
      Default Value: false

    Callback Handling:
    The callback function recieves an array of integers with length equal to that of the array of molecules sent in as targets parameter, 0 means no match, 1 means exact match, and 2 means partial match.
  • static Function optimize(Molecule mol, Object options, Function callback, Function errorback): optimizes the input Molecule's coordinates given a dimension (2 or 3)
    Options:
    • Number dimension: Either integer 2 or 3, defining the dimensionality of the coordinates to optimize.
      Default Value: 2
      Unit: dimension

    Callback Handling:
    If the dimension is 2, then nothing is sent to the callback function, the coordinates of the input molecule are updated accordingly when the callback function is executed; if the dimension is 3, a new Molecule object is sent as a parameter to the callback function.
  • static Function readIUPACName(String iupac, Object options, Function callback, Function errorback): generates a Molecule given an IUPAC name
    Options:
    none
    Callback Handling:
    An array of Molecule data structures generated from the input IUPAC name is sent as the first parameter to the callback function; the array may be empty. The second parameter is any warning (as a String) associated with the parsing of the IUPAC name, which may be undefined.
  • static Function readSMILES(String smiles, Object options, Function callback, Function errorback): parses the input SMILES string and produces the corresponding Molecule(s) and Shape (a reaction arrow may be created) objects
    Options:
    • Number generate_coordinates: The dimension of the coordinates to generate for the structures. A dimension of 0 will instruct the call not to generate coordinates.
      Default Value: 2
    • Boolean kekulize: SMILES with aromatic models enforced will be input using resonance bonds. Setting this option to true will Kekulize those resonance systems.
      Default Value: false
      Unit: true/false
    • Boolean infer_ambiguous_double_bonds: If this option is true, double bonds that do not have stereochemistry defined in the SMILES string will be represented with an ambiguous double bond type.
      Default Value: false
      Unit: true/false

    Callback Handling:
    An object with attributes of the molecules (Array of Molecule) and shapes (Array of Shape) generated is sent as a parameter to the callback function.
  • static Function readWLN(String wln, Object options, Function callback, Function errorback): parses the input WLN string and produces the corresponding content of molecules and associated shapes
    Options:
    none
    Callback Handling:
    An object with attributes of molecules (Array of Molecule) and shapes (Array of Shape) data structures generated from the input WLN string is sent as the first parameter to the callback function; the content may be empty.
  • static Function resolveCIP(Molecule mol, Object options, Function callback, Function errorback): resolves atom and bond stereocenters using CIP rules for the input Molecule
    Options:
    none
    Callback Handling:
    The callback receives 2 parameters, which are both arrays. The first is the CIP configuration tags for atoms and the second is the CIP configuration tags for bonds. The ordering is identical to the atom and bond ordering of the input molecule. If an atom or bond is not a stereocenter, the corresponding result in the array will be an empty String.
  • static Function saveFile(Molecule mol, Object options, Function callback, Function errorback): saves the input Molecule in any of the chemical formats that ChemDoodle understands (specified by the ext option)
    Options:
    • String ext: The extension of the file format to write.
      Allowed Values: [any of the chemical file extensions that ChemDoodle 2D understands]
      Default Value: 'icl'

    Callback Handling:
    A url to the generated file on our server is sent as a parameter to the callback function.
  • static Function simulate13CNMR(Molecule mol, Object options, Function callback, Function errorback): simulates the 13C NMR spectrum for the input molecule, the resulting Spectrum object is sent to the callback function
    Options:
    none
    Callback Handling:
    The Spectrum generated from the input Molecule is sent as a parameter to the callback function.
  • static Function simulate1HNMR(Molecule mol, Object options, Function callback, Function errorback): simulates the 1H NMR spectrum for the input molecule, the resulting Spectrum object is sent to the callback function
    Options:
    none
    Callback Handling:
    The Spectrum generated from the input Molecule is sent as a parameter to the callback function.
  • static Function simulateMassParentPeak(Molecule mol, Object options, Function callback, Function errorback): simulates the parent peak in a mass spectrum for the input molecule (isotopic distribution)
    Options:
    none
    Callback Handling:
    The Spectrum generated from the input Molecule is sent as a parameter to the callback function.
  • static Function stoichiometry(Object providedInformation, Object options, Function callback, Function errorback): this function handles the stoichometry table calculations and should not be called directly, as the Stoichiometry class provides a developer API; when initializing the table, the providedInformation object can be either a String or a drawn reaction, if the table is already initialized and requires updating, providedInformation is the current table structure
    Options:
    none
    Callback Handling:
    The callback function recieves an object with the current calculation values as a table data structure (this table should be updated and sent back to this function for further updates). There is a also a second parameter returned named message, with optional information about the stoichiometry table, which may be undefined.
  • static Function version(): a method to determine the version information from the server currently being queried
    Options:
    none
    Callback Handling:
    A string is returned containing version information.
  • static Function writeSMILES(Array molecules, Array shapes, Object options, Function callback, Function errorback): generates the SMILES string for the input molecules (of Molecule data structures) and shapes (of Shape data structures). A single reaction arrow is allowed to be sent in the shapes array, but an empty array should be sent if there is no reaction arrow.
    Options:
    • Boolean aromaticity: If true, SMILES output will have the SMILES aromaticity model enforced (lower case letters).
      Default Value: false
      Unit: true/false
    • Boolean include_all_explicit_hydrogens: If true, explicitly drawn hydrogen atoms will be output as explicit atoms in the SMILES string.
      Default Value: false
      Unit: true/false
    • Boolean stereochemistry: If true, stereochemistry will be output into the SMILES string.
      Default Value: true
      Unit: true/false
    • Boolean include_implied_double_bond_stereo: Some double bond stereo characters can be implied and are not necessary, shortening the SMILES string. If true, these implied characters will be included in the string.
      Default Value: false
      Unit: true/false

    Callback Handling:
    The generated SMILES string is sent as a parameter to the callback function.
  • static abstract Function _contactServer(String call, Object content, Object options, Function callback, Function errorback): the core function for contacting our server; this function takes parameters specific to our server protocol, is able to communicate the protocol and then returns the appropriate response to the callback function; this should never be manually called, use the other functions in this package instead; the errorback function is optional, and if provided and any error occurs, the errorback function will be called

Get your work done with our popular desktop software.