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(mol){
	      // The function completed successfully and the returned
	      // molecule is sent to the callback function.
	      // Use the mol object to complete your function, here
	      // we just alert the number of atoms and bonds.
	      alert(mol.atoms.length+' '+mol.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 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 generateIUPACName(Molecule mol, Object options, Function callback, Function errorback): generates the IUPAC name for the input molecule
    Options:
    none
    Callback Handling:
    The IUPAC name of the molecule is returned as the parameter to the callback function.
  • 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:
    The Molecule generated from the input IUPAC name is sent as a parameter to the callback function.
  • static Function readSMILES(String smiles, Object options, Function callback, Function errorback): parses the input SMILES string and produces the corresponding Molecule
    Options:
    none
    Callback Handling:
    The Molecule generated from the SMILES string is sent as a parameter to the callback function.
  • 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 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(Molecule mol, Object options, Function callback, Function errorback): generates the SMILES string for the input Molecule
    Options:
    none
    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.